lib/common_options.pm

   1 package common_options;
   2
   3 use FindBin qw($Bin);
   4 use lib "$Bin/../lib";
   5 use Getopt::Long;
   6 use Text::Wrap;
   7
   8 ## Configure the command line parsing
   9 Getopt::Long::config("auto_abbrev");
  10
  11 my @tool_options = ( "abort_on_fail",
  12                      "adaptive!",
  13                      "clean:i",
  14                      "compress",
  15                      "condition_number_limit:f",
  16                      "correlation_limit:f",
  17                      "crash_restarts:i",
  18                      "directory:s",
  19                      "drop_dropped",
  20                      "handle_maxevals",
  21                      "handle_msfo",
  22                      "handle_crashes",
  23                      "large_theta_cv_limit:f",
  24                      "large_omega_cv_limit:f",
  25                      "large_sigma_cv_limit:f",
  26                      "lsf_job_name:s",
  27                      "lsf_options:s",
  28                      "lsf_project_name:s",
  29                      "lsf_queue:s",
  30                      "lsf_resources:s",
  31                      "lsf_ttl:s",
  32                      "min_retries:i",
  33                      "missing_data_token:s",
  34                      "near_bound_sign_digits:i",
  35                      "near_zero_boundary_limit:f",
  36                      "nice:i",
  37                      "nm_version:s",
  38                      "nm_directory:s",
  39                      "nonparametric_etas",
  40                      "nonparametric_marginals",
  41                      "picky",
  42                      "prepend_model_file_name",
  43                      "quick_summarize|quick_summary",
  44                      "rerun:i",
  45                      "retries:i",
  46                      "run_on_lsf",
  47                      "run_on_ud",
  48                      "run_on_sge",
  49                      "sge_resource:s",
  50                      "sge_queue:s",
  51                      "seed:s",
  52                      "shrinkage",
  53                      "significant_digits_rerun:f",
  54                      "sign_digits_off_diagonals:i",
  55                      "summarize|summary",
  56                      "threads:i",
  57                      "tweak_inits:i",
  58                      "ud_native_retrieve",
  59                      "ud_sleep:i",
  60                      "verbose!",
  61                      "wrap_data",
  62                      "unwrap_table_files",
  63                      "near_bound_sign_digits:i",
  64                      "near_zero_boundary_limit:f",
  65                      "large_theta_cv_limit:f",
  66                      "large_omega_cv_limit:f",
  67                      "large_sigma_cv_limit:f",
  68                      "confidence_level:f",
  69                      "precision:i",
  70                      );
  71
  72
  73 my @model_options = ("extra_data_files:s@",
  74                      "extra_files:s",
  75                      "extra_output:s",
  76                      "sde",
  77                      "cwres",
  78                      "mirror_plots:i",
  79                      "iofv",
  80                      "mirror_from_lst!",
  81                      "nm_version:s",
  82                      "outputfile:s",
  83                      );
  84
  85 my @script_options = ( "debug:i",
  86                        "debug_package:s",
  87                        "debug_subroutine:s",
  88                        "h|?",
  89                        "help",
  90                        "html_help",
  91 #                      "project:s",
  92                        "silent",
  93 #                      "user:s",
  94                        "warn_with_trace:i"
  95                        );
  96
  97 @get_opt_strings = (sort(@tool_options), sort(@model_options), sort(@script_options));
  98
  99 sub options_to_parameters {
 100   my $opts = shift;
 101   my @options = @{$opts};
 102
 103   my $parameter_string = '( ';
 104
 105   foreach my $opt ( @options ){
 106     $opt =~ s/[!:|].*//g;
 107     $parameter_string .= "$opt => \$options{'$opt'},\n";
 108   }
 109   $parameter_string .= ' )';
 110   return $parameter_string;
 111 }
 112
 113 $parameters = options_to_parameters([@tool_options,'top_tool']);
 114
 115
 116 @extra_files;
 117 @extra_output;
 118
 119 sub set_globals {
 120   my $opts = shift;
 121   my %options = %{$opts};
 122   if ( $PsN::config -> {'_'} -> {'use_database'} ) {
 123
 124     $PsN::config -> {'_'} -> {'project'}  =
 125         defined $options{'project'} ? $options{'project'} :
 126         $PsN::config -> {'_'} -> {'default_project'};
 127     $PsN::config -> {'_'} -> {'user'}  =
 128         defined $options{'user'} ? $options{'user'} :
 129         $PsN::config -> {'_'} -> {'default_user'};
 130     print "Using database ".$PsN::config -> {'_'} -> {'project'}."\n";
 131     if ( defined $options{'password'} ) {
 132       $PsN::config -> {'_'} -> {'password'} = $options{'password'};
 133     } elsif( defined $PsN::config -> {'_'} -> {'password'} ) {
 134       $PsN::config -> {'_'} -> {'password'} =
 135           $PsN::config -> {'_'} -> {'default_password'};
 136     } else {
 137       system( "stty -echo" );
 138       print "Database password for ".$PsN::config -> {'_'} -> {'user'}.": ";
 139       my $word;
 140       chomp($word = <STDIN>);
 141       print "\n";
 142       system( "stty echo" );
 143       $PsN::config -> {'_'} -> {'password'} = $word;
 144     }
 145   }
 146 }
 147
 148 sub get_defaults {
 149   my $options = shift;
 150   my $tool    = shift;
 151   foreach my $default_option ( keys %{$PsN::config -> {'default_'.$tool.'_options'}} ){
 152     unless( exists $options -> {$default_option} ){
 153       $options -> {$default_option} = $PsN::config -> {'default_'.$tool.'_options'} -> {$default_option};
 154     }
 155
 156   }
 157
 158
 159   foreach my $default_option ( keys %{$PsN::config -> {'default_options'}} ){
 160     unless( exists $options -> {$default_option} ){
 161       $options -> {$default_option} = $PsN::config -> {'default_options'} -> {$default_option};
 162     }
 163
 164   }
 165   $options -> {'top_tool'} = 1;
 166 }
 167
 168 sub print_help {
 169   my( $command, $required, $optional ) = @_;
 170   my %is_required;
 171   my %all_options = (%{$required},%{$optional});
 172
 173   foreach my $req( keys %{$required} ){
 174     $is_required{$req} = 1;
 175   }
 176
 177   my $option_help;
 178
 179   $option_help .= "[ -h | -? ] [ --help ]\n" . ' ' x (1+length($command));
 180
 181   my @loop_array;
 182   if( $command eq 'execute' ){
 183     @loop_array = sort(@get_opt_strings);
 184   } else {
 185     @loop_array = (keys %{$required}, keys %{$optional});
 186   }
 187
 188   foreach my $help( @loop_array ) {
 189     next if( $help eq 'help' or $help eq 'h|?' );
 190     unless( $is_required{$help} ){
 191       $option_help .= "[ ";
 192     } else {
 193       $option_help .= "  ";
 194     }
 195     if( $all_options{$help} ne '' ){
 196       $help =~ /^([^:]+)/;
 197       $option_help .= "--$1=\'" . $all_options{$help} . "\'";
 198     } elsif( $help =~ /(.+):s/ ){
 199       $option_help .= "--$1=\'string\'";
 200     } elsif( $help =~ /(.+):i/ ){
 201       $option_help .= "--$1=\'integer\'";
 202     } elsif( $help =~ /(.+):f/ ){
 203       $option_help .= "--$1=\'number\'";
 204     } elsif( $help =~ /(.+):(\d)/ ){
 205       $option_help .= "--$1=$2";
 206     } elsif( $help =~ /(.+)[^:]$/ ){
 207       $option_help .= "--$help";
 208     }
 209     unless( $is_required{$help} ){
 210       $option_help .= " ]";
 211     }
 212     $option_help .= "\n".' ' x (1+length($command));
 213   }
 214
 215   return $option_help;
 216 }
 217
 218 sub model_parameters {
 219   my $options = shift;
 220   #my %options = %{$opt};
 221
 222   if( defined $options -> {'extra_data_files'} ){
 223     for( my $i=0; $i < scalar(@{$options -> {'extra_data_files'}}) ; $i++ ){
 224       my @arr = split( /,/ , @{$options -> {'extra_data_files'}}[$i] );
 225       if( @arr < 2 ){
 226         die "extra_data_file must be of form: \"filename, head1, head2\"\n" ;
 227       }
 228
 229       @{$options -> {'extra_data_files'}}[$i] = $arr[0];
 230       my @subarray = @arr[1..$#arr];
 231       push( @{$options -> {'extra_data_headers'}}, \@subarray )
 232     }
 233   }
 234
 235   push(@model_options, 'extra_data_headers');
 236
 237   if( defined $options -> {'extra_files'} ){
 238     my @array = split( /,/ , $options -> {'extra_files'} );
 239     $options -> {'extra_files'} = \@array;
 240   }
 241
 242   if( defined $options -> {'extra_output'} ){
 243     my @array = split( /,/ , $options -> {'extra_output'} );
 244     $options -> {'extra_output'} = \@array;
 245   }
 246
 247   return options_to_parameters(\@model_options);
 248
 249 }
 250
 251
 252 sub online_help {
 253
 254   my $command = shift;
 255   my $opts = shift;
 256   my $help_text = shift;
 257   my $required_options = shift;
 258   my $optional_options = shift;
 259   my %options = %{$opts};
 260
 261   my %help_hash;
 262
 263   $help_hash{Pre_help_message} = << 'EOF';
 264   <h3 class="heading1">execute</h3>
 265
 266       Perl script running one or more modelfiles using PsN.
 267
 268   <h3 class="heading1">Usage:</h3>
 269 EOF
 270
 271     $help_hash{Description} = <<'EOF';
 272   <h3 class="heading1">Description:</h3>
 273
 274     The execute utility is a Perl script that allows you to run multiple
 275     modelfiles either sequentially or in parallel. It is more or less an
 276     nmfe replacement.
 277     <br><br>
 278     The execute utility creates subdirectories where it puts NONMEMs
 279     input and output files, to make sure that parallel NONMEM runs do not
 280     interfere with each other. The top directory is by default named
 281     'modelfit_dirX' where 'X' is a number that starts at 0 and is
 282     increased by one each time you run the execute utility.
 283     <br><br>
 284     When the NONMEM runs are finished, the output and table files will be
 285     copied to the directory where execute started in which means that you
 286     can normaly ignore the 'modelfit_dirX' directory. If you need to
 287     access any special files you can find them inside the
 288     'modelfit_dirX'. Inside the 'modelfit_dirX' you find a few
 289     subdirectories named 'NM_runY'. For each model file you
 290     specified on the command line there will be one 'NM_runY' directory in
 291     which the actual NONMEM execution takes place. The order of the
 292     'NM_runY' directories corresponds to the order of the modelfiles given
 293     on the command line. The first run will take place inside 'NM_run1',
 294     the second in 'NM_run2' and so on.
 295 EOF
 296
 297     $help_hash{Examples} = <<'EOF';
 298   <h3 class="heading1">Example:</h3>
 299
 300     <p align="justify" class="style2">$ execute pheno.mod </p>
 301
 302     <p align="justify">Runs one model file and accepts all default values.</p>
 303
 304     <p align="justify" class="style2">$ execute -threads=2  -retries=5 phenobarbital.mod pheno_alternate.mod</p>
 305
 306     <p align="justify">Runs two model files in parallel using 5 possible retries.</>p
 307 EOF
 308
 309     $help_hash{Options} = <<'EOF';
 310   <h3 class="heading1">Options:</h3>
 311
 312     The options are given here in their long form. Any option may be
 313     abbreviated to any nonconflicting prefix. The <span class="style2">-threads</span> option may
 314     be abbreviated to <span class="style2">-t</span> (or even <span class="style2">-thr</span>) but <span class="style2">-debug</span> may not be
 315     abbreviated to <span class="style2">-d</span> because it conflicts with <span class="style2">-debug_packages</span> and
 316     <span class="style2">-debug_subroutines</span>.
 317     <br><br>
 318     The following options are valid:
 319 EOF
 320
 321     $help_hash{'-?'} = <<'EOF';
 322     <p class="style2">-h | -?</p>
 323
 324     With <span class="style2">-h</span> or <span class="style2">-?</span> execute.pl prints the list of available options
 325     and exit.
 326 EOF
 327
 328     $help_hash{-help} = <<'EOF';
 329     <p class="style2">-help</p>
 330
 331     With <span class="style2">-help</span> execute will print a longer help message.
 332 EOF
 333
 334     $help_hash{-nm_version} = <<'EOF';
 335     <p class="style2">-nm_version='integer'</p>
 336
 337     If you have more than one installation of NONMEM you can choose
 338     between them using the <span class="style2">-nm_version</span> option. The installations must be
 339     specified in the psn.conf file. The default value is 5.
 340 EOF
 341
 342     $help_hash{-threads} = <<'EOF';
 343     <p class="style2">-threads='integer'</p>
 344
 345     Use the threads option to enable parallel execution of multiple
 346     NONMEM runs. On a desktop computer it is recommended to set
 347     <span class="style2">-threads</span> to the number of CPUs in the system plus one. You can
 348     specify more threads, but it will probably not increase the
 349     performance. If you are running on a computer cluster, you should
 350     consult your systems administrator to find out how many threads
 351     you can specify. The <span class="style2">-threads</span> option will be ignored if you run on
 352     a grid system, since gridshave ther own scheduling algoritms. The
 353     default value for the <span class="style2">-threads</span> option is 1.
 354 EOF
 355
 356     $help_hash{-nice} = <<'EOF';
 357     <p class="style2">-nice='integer'</p>
 358
 359     This option only has effect on unix like operating systems. It
 360     sets the priority (or nice value) on a process. You can give any
 361     value that is legal for the "nice" command, likely it is between 0
 362     and 19, where 0 is the highest priority. Check "man nice" for
 363     details.
 364 EOF
 365
 366     $help_hash{-directory} = <<'EOF';
 367     <p class="style2">-directory='string'</p>
 368
 369     The directory option sets the directory in which execute will run
 370     NONMEM. The default directory name is 'modelfit_dirX' where X will
 371     be increased by one each time you run the execute utility. You do
 372     not have to create the directory, it will be done for you.
 373
 374     If you abort execute or if your system crashes you can use the
 375     '<span class="style2">-directory</span>' option set to the directory of the execute run that
 376     crashed. Execute will then not run the modelfiles that had
 377     finished before the crash, thereby saving some time. Notice that
 378     is important that you give exactly the same options that you gave
 379     the first time.
 380 EOF
 381
 382     $help_hash{-drop_dropped} = <<'EOF';
 383     <p class="style2">-drop_dropped</p>
 384
 385     If there are drop columns in your control file and <span class="style2">-drop_dropped</span>
 386     is used, PsN will remove those columns from the data set used
 387     internally. It saves both diskspace and conserves memory
 388     usage. Note that PsN does NOT alter your original data set, only
 389     those used internally in PsN.
 390 EOF
 391
 392     $help_hash{-extra_data_files} = <<'EOF';
 393     <p class="style2">-extra_data_files='extra_data1.dta, COLUMN1, COLUMN2'</p>
 394
 395     NONMEM only allows 20 column datasets, but PsN can add code to
 396     control files that reads extra data columns from a separate
 397     file. To use this feature you must create a new data file which
 398     has the same ID row as the main data file. Then you specify a
 399     comma separated list with <span class="style2">-extra_data_files</span>. The first element
 400     in the list is the filename and the rest of the list is the header
 401     of the extra data file. You can have multiple extra files if neccesary.
 402 EOF
 403
 404     $help_hash{-extra_files} = <<'EOF';
 405     <p class="style2">-extra_files='extra_file1.dta, extra_file2.dta'</p>
 406
 407     If you need extra files in the directory where NONMEM is run you
 408     specify them in list to the <span class="style2">-extra_files</span> list. It could for
 409     example be fortran subroutines you need compiled with NONMEM.
 410 EOF
 411
 412     $help_hash{-handle_maxevals} = <<'EOF';
 413     <p class="style2">-handle_maxevals='number'</p>
 414
 415     NONMEM only allows 9999 function evaluations. PsN can expand this
 416     limit by adding an MSFO option to $ESTIMATION, later when NONMEM
 417     hits the max number of function evaluations(9999) PsN will remove
 418     intial estimates from the modelfile and add $MSFI and restart
 419     NONMEM. PsN will do this until the number of evaluations specified
 420     with <span class="style2">-handle_maxevals</span> is reached.
 421 EOF
 422
 423     $help_hash{-seed} = <<'EOF';
 424     <p class="style2">-seed='string'</p>
 425
 426     If you use the <span class="style2">-retries='integer'</span> option, execute will use a
 427     random number to create new intial estimates for the model
 428     parameters. To make sure that the same result is produced if you
 429     redo the same run, you can set your own random seed with the <span class="style2">-seed</span>
 430     option.
 431
 432 EOF
 433
 434     $help_hash{'-summarize|summary'} = <<'EOF';
 435     <p><span class="style2">-summarize</span> or <span class="style2">-summary</span></p>
 436
 437     <span class="style2">summarize</span> or <span class="style2">-summary</span> will do a set of diagnostics test
 438     and print minimization message for each model run.
 439 EOF
 440
 441     $help_hash{-verbose} = <<'EOF';
 442     <p class="style2">-verbose</p>
 443
 444     With <span class="style2">verbose</span> set to 1, PsN will print
 445     more details about NONMEM runs. More precisely PsN will print the
 446     minimization message for each successfull run and a R:X for each
 447     retry PsN makes of a failed run, where X is the run number.
 448 EOF
 449
 450     $help_hash{-wrap_data} = <<'EOF';
 451     <p class="style2">-wrap_data</p>
 452
 453     NONMEM only allows 20 column datasets, but it is possible to wrap
 454     observation lines into multiple rows by adding a CONT column. With
 455     <span class="style2">wrap_data</span> PsN does it automatically.
 456 EOF
 457
 458     $help_hash{-lsf_job_name} = <<'EOF';
 459     <p class="style2">-lsf_job_name='string'</p>
 460
 461     <span class="style2">lsf_job_name</span> sets the name of the LSF job name of every NONMEM run,
 462     they all get the same name.
 463 EOF
 464
 465     $help_hash{-lsf_options} = <<'EOF';
 466     <p class="style2">-lsf_options='string'</p>
 467
 468     LSF jobs are submitted using bsub and all LSF related options are
 469     translated to corresponding bsub options. For maximum flexibility
 470     we allow any string to be passed as options to bsub, so if a specific
 471     bsub feature not available through any ot the other -lsf_ options
 472     is needed, use <span class="style2">lsf_options</span> to pass any option to bsub.
 473 EOF
 474
 475     $help_hash{-lsf_project_name} = <<'EOF';
 476     <p class="style2">-lsf_project_name='string'</p>
 477
 478     Use <span class="style2">lsf_project_name</span> to assign a
 479     project name to your LSF runs.
 480 EOF
 481
 482     $help_hash{-lsf_resources} = <<'EOF';
 483     <p class="style2">-lsf_resources='string'</p>
 484
 485     <span class="style2">lsf_resources</span> specifies which LSF resources is required when submiting
 486     NONMEM runs.
 487 EOF
 488
 489     $help_hash{-lsf_ttl} = <<'EOF';
 490     <p class="style2">-lsf_ttl='string'</p>
 491
 492     <span class="style2">lsf_ttl</span> sets the maximum time a NONMEM run should be allowed to run on
 493     the LSF grid.
 494 EOF
 495
 496     $help_hash{-lsf_queue} = <<'EOF';
 497     <p class="style2">-lsf_queue='string'</p>
 498
 499     <span class="style2">lsf_queue</span> specifies which LSF queue PsN should submit NONMEM runs
 500     to and is used in conjuction with <span class="style2">-run_on_lsf</span>
 501 EOF
 502
 503     $help_hash{-min_retries} = <<'EOF';
 504     <p class="style2">-min_retries='string'</p>
 505
 506     <span class="style2">min_retries</span> forces the PsN to try
 507     several initial values for each estimate and selecting the best
 508     one. The best model is chosen in the following maner: if <span class="style2">-picky</span>
 509     is used the model must pass the picky test. Then the one with
 510     highest number of significant digits and an ofv value no more than
 511     five units above than the lowest ofv value among all models.
 512 EOF
 513
 514     $help_hash{-remove_temp_files} = <<'EOF';
 515     <p class="style2">-remove_temp_files</p>
 516
 517     If the <span class="style2">-remove_temp_files</span> option is set to 1, execute will remove
 518     the 'FCON', 'FDATA', 'FREPORT', 'FSUBS', 'FSUBS.f', 'LINK.LNK',
 519     'FSTREAM', 'PRDERR' and 'nonmem' files from the 'NM_runX'
 520     directory. The default value is 0.
 521 EOF
 522
 523     $help_hash{-clean} = <<'EOF';
 524     <p class="style2">-clean</p>
 525
 526     If the <span class="style2">-clean</span>
 527     option is set to 1, execute will remove the entire 'NM_runX'
 528     directory after the NONMEM run is finished. The default value of
 529     <span class="style2">-clean </span>is 0.
 530 EOF
 531
 532     $help_hash{-missing_data_token} = <<'EOF';
 533     <p class="style2">-missing_data_token='string'</p>
 534
 535     <span class="style2">missing_data_token</span> sets the string
 536     that PsN accepts as missing data, default is -99.
 537 EOF
 538
 539     $help_hash{-nm_directory} = <<'EOF';
 540     <p class="style2">-nm_directory='string'</p>
 541
 542     The argument of <span class="style2">nm_directory</span> is
 543     directory where NONMEM is installed. Normally its easiest to setup
 544     a version in psn.conf and use <span class="style2">-nm_version</span> to access it.
 545 EOF
 546
 547     $help_hash{-no_remote_compile} = <<'EOF';
 548     <p class="style2">-no_remote_compile</p>
 549
 550     When running on LSF it is no guaranteed that NONMEM is available
 551     on the computing node, then <span class="style2">-no_remote_compile</span> allows you to compile
 552     NONMEM localy and only submit the NONMEM executable to the grid.
 553 EOF
 554
 555     $help_hash{-no_remote_execution} = <<'EOF';
 556     <p class="style2">-no_remote_execution</p>
 557
 558     <span class="style2">no_remote_execution</span> prohibits execution on the LSF grid. Used together
 559     with <span class="style2">-no_remote_compile</span> it cancels out <span class="style2">-run_on_lsf</span>
 560 EOF
 561
 562     $help_hash{-compress} = <<'EOF';
 563     <p class="style2">-compress</p>
 564
 565     The execute utility will compress the contents of 'NM_runX' to the
 566     file 'nonmem_files.tgz' if the <span class="style2">-compress</span> option is used and if you
 567     have the archive and compress programs <strong>tar</strong> and <strong>gzip</strong> installed. If
 568     you use the <span class="style2">-clean</span> options, run files will be
 569     removed before the compression. The <span class="style2">-compress</span> option obviously has
 570     no effect if you also use the <span class="style2">-clean</span> option.
 571 EOF
 572
 573     $help_hash{-tweak_inits} = <<'EOF';
 574     <p class="style2">-tweak_inits</p>
 575
 576     <!--/>If NONMEM terminates nonsuccessfully, PsN can perturb the initial
 577     estimates and run NONMEM again. The generation of new initial
 578     estimates init_i for the i:th retry are performed according to
 579
 580     init_i = init_0 + rand_uniform(+-0.1*i*init_0)
 581
 582     where init_0 are the initial estimates of the original run. The
 583     updating procedure makes sure that boundary conditions on the
 584     parameters are still valid. For this option to have effect, the
 585     -retries option must be set to number larger than zero. The
 586     default setting uses tweak_inits.<-->
 587     <?php print '<p>  If NONMEM terminates nonsuccessfully, PsN can perturb the initial estimates  and run NONMEM again. The generation of new initial estimates <img src="images/init1.gif"> for the <em>i</em>:th retry are performed according to</p><p align="center"><img src="images/perturb1.gif" width="236" height="32"></p> <p>where <img src="images/init_orig1.gif" width="29" height="28"> are the initial estimates of the original run. The updating procedure makes sure that boundary conditions on the parameters are still valid. For this option to be valid, the <span class="style2">-retries</span> option must be set to a number larger than zero. The default setting uses tweak_inits. </p>'; ?>
 588 EOF
 589
 590     $help_hash{-outputfile} = <<'EOF';
 591     <p class="style2">-outputfile</p>
 592
 593     The <span class="style2">-outputfile</span> option specifies the output file name for the
 594     NONMEM run. Currently This option is only valid when a single
 595     model is supplied to the execute utility.
 596 EOF
 597
 598     $help_hash{-picky} = <<'EOF';
 599     <p class="style2">-picky</p>
 600
 601     The <span class="style2">-picky</span> option is only valid together with <span class="style2">-tweak_inits</span>.
 602     Normally PsN only tries new initial estimates if
 603     '<span class="style2">MINIMZATION SUCCESSFUL</span>' is not found in the NONMEM output
 604     file. With the <span class="style2">-picky</span> option, PsN will regard any of the
 605     following messages as a signal for rerunning:
 606 <p class="style2">
 607     0ESTIMATE OF THETA IS NEAR THE BOUNDARY<br>
 608     0PARAMETER ESTIMATE IS NEAR ITS BOUNDARY<br>
 609     0R MATRIX ALGORITHMICALLY SINGULAR<br>
 610     0S MATRIX ALGORITHMICALLY SINGULAR</p>
 611 EOF
 612
 613     $help_hash{'-quick_summarize|quick_summary'} = <<'EOF';
 614     <p><span class="style2">-quick_summarize</span> or <span class="style2">-quick_summary</span></p>
 615
 616     If either of <span class="style2">quick_summarize</span> and <span class="style2">quick_summary</span> is used, PsN will print
 617     the ofv value and minimization message for each NONMEM run.
 618 EOF
 619
 620     $help_hash{-rerun} = <<'EOF';
 621     <p class="style2">-rerun</p>
 622
 623     PsN can redo or resume a run using information in PsN run
 624     directory(see documentation for <span class="style2">-directory</span>). It is called
 625     a rerun. During a rerun PsN will consider to redo parts of
 626     the run. With the <span class="style2">-rerun</span> option you can control which parts
 627     will be redone. The default value of <span class="style2">-rerun</span> is 1.
 628     With rerun set to 1 PsN will rerun any model with a missing
 629     list file. Notice that every "retry" (see the documentation
 630     for <span class="style2">-retries</span> and <span class="style2">-min_retries</span>) will be considered for a rerun.
 631     This means you can change the value of the <span class="style2">-retries</span> and
 632     <span class="style2">-min_retries</span> options if you like more or less retries.
 633     Setting <span class="style2">-rerun</span> to 0 means that PsN will not check for
 634     missing or incomplete "retry" list files. This is usefull
 635     if you have one or more run modelfiles and you wish to have
 636     a PsN raw_results file or a PsN summary, you do a "execute"
 637     run with them as arguments and specify <span class="style2">-rerun=0</span>, PsN will not
 638     do any NONMEM run, but produce usefull output summary.
 639     You can also set <span class="style2">-rerun</span> to 2, and PsN will ignore any existing
 640     list files and rerun everything, creating raw_results and
 641     summaries from the new listfiles.
 642 EOF
 643
 644     $help_hash{-run_on_lsf} = <<'EOF';
 645     <p class="style2">-run_on_lsf</p>
 646
 647     PsN connects with Platform Load Sharing Facility (LsF). With
 648     <span class="style2">-run_on_lsf</span>. PsN will submit to the queue defined in "psn.conf"
 649     unless specified with <span class="style2">-lsf_queue</span>.
 650 EOF
 651
 652     $help_hash{-run_on_ud} = <<'EOF';
 653     <p class="style2">-run_on_ud</p>
 654
 655     PsN connects with United Devices Grid MP. With <span class="style2">-run_on_ud</span> PsN will submit to the UD grid
 656     with parameters defined in the "uduserconf" file.
 657 EOF
 658
 659     $help_hash{-retries} = <<'EOF';
 660     <p class="style2">-retries='integer'</p>
 661
 662     The <span class="style2">-retries</span> option tells the execute utility how many times it
 663     shall try to rerun a NONMEM job if it fails according to given criterias.. In
 664     the current version of PsN (2.2), the <span class="style2">-retries</span> option is only
 665     valid together with <span class="style2">-tweak_inits</span>. The default value of the
 666     <span class="style2">-retries</span> option is 6.
 667 EOF
 668
 669     $help_hash{-crash_restarts} = <<'EOF';
 670     <p class="style2">-crash_restarts='integer'</p>
 671
 672     If a NONMEM outputfile is produced but PsN is unable to read it
 673     properly it is assumed that NONMEM crashed, probably due to
 674     something in the operating system, and PsN will start the run
 675     again. But PsN will not consider it a retry and will not change
 676     initial estimates. The default value is 4.
 677 EOF
 678     $help_hash{-significant_digits_rerun} = <<'EOF';
 679     <p class="style2">-significant_digits_rerun='number'</p>
 680
 681     The <span class="style2">-picky</span> option is only valid together with <span class="style2">-tweak_inits</span>.
 682     Normally PsN only tries new initial estimates if
 683     '<span class="style2">MINIMZATION SUCCESSFUL</span>' is not found in the NONMEM output
 684     file. With the <span class="style2">-significant_digits_rerun</span>, PsN will rerun if
 685     the resulting significant digits is lower than the value
 686     specified with this option.
 687 EOF
 688
 689     $help_hash{-abort_on_fail} = <<'EOF';
 690     <p class="style2">-abort_on_fail</p>
 691
 692     If the <span class="style2">-abort_on_fail</span> option is set and one of the NONMEM runs
 693     fails, execute will stop scheduling more runs and try to stop
 694     those that are currently running. A run is considered failed if it
 695     fails to produce a list file which PsN can read. This can occure
 696     if a nonmem run crashes or gets killed.
 697 EOF
 698
 699     $help_hash{-adaptive} = <<'EOF';
 700     <p class="style2">-adaptive</p>
 701
 702     <span class="style2">-adaptive</span> enables a highly experimental feature to dynamically
 703     assign the number of threads depending on the number of running
 704     nonmem processes on the computer. It requires a server program
 705     which is not distributed with PsN. If you are interrested in this
 706     feature, contact the PsN developers.
 707 EOF
 708
 709     $help_hash{-run_on_nordugrid} = <<'EOF';
 710     <p class="style2">-run_on_nordugrid</p>
 711
 712     !! Currently only valid for Linux system !!
 713     execute will run on nordugrid clusters listed in ~/.ng_cluster .
 714     If you do not know about Nordugrid, you can safely ignore this option.
 715     Read more on http://www.nordugrid.org
 716 EOF
 717
 718     $help_hash{-cpu_time} = <<'EOF';
 719     <p class="style2">-cpu_time='integer'</p>
 720
 721     !! Currently only valid for Linux system !!
 722     This option specifies the number of minutes allocated for a
 723     gridjob. The default value is 120 minutes. This option is only
 724     valid together with the <span class="style2">-run_on_nordugrid</span> option.
 725 EOF
 726
 727     $help_hash{-grid_batch_size} = <<'EOF';
 728     <p class="style2">-grid_batch_size='integer'</p>
 729
 730     This option specifies the number of nonmem runs that will be
 731     grouped together into one grid job. The default number is 5. This
 732     option is only valid together with the '<span class="style2">-run_on_nordugrid'</span> option.
 733 EOF
 734
 735     $help_hash{-silent} = <<'EOF';
 736     <p class="style2">-silent</p>
 737
 738     The silent option turns off all output from PsN. Results and log
 739     files are still written to disk, but nothing is printed to the
 740     screen.
 741 EOF
 742
 743     $help_hash{-debug} = <<'EOF';
 744     <p class="style2">-debug='integer'</p>
 745
 746     The <span class="style2">-debug</span> option is mainly intended for developers who whish to
 747     debug PsN. By default <span class="style2">-debug</span> is set to zero but you can try
 748     setting it to '1' to enable warning messages. If you run in to
 749     problems that require support, you may have to increase this
 750     number to 2 or 3 and send the output to us.
 751 EOF
 752
 753     $help_hash{-debug_package} = <<'EOF';
 754     <p class="style2">-debug_package='string'</p>
 755
 756     When used together with <span class="style2">-debug</span>, the <span class="style2">-debug_package</span> option makes is
 757     possible to choose which part of PsN you want to see debug
 758     messages for. Again, this option is mostly for developers.
 759 EOF
 760
 761     $help_hash{-debug_subroutine} = <<'EOF';
 762     <p class="style2">-debug_subroutine='string'</p>
 763
 764     Default value is: empty string
 765
 766     With this option it is possible to specify, with even finer
 767     granularity, which part of PsN you want to see debug messages
 768     from. This is definitly only for developers.
 769 EOF
 770
 771     $help_hash{-warn_with_trace} = <<'EOF';
 772     <p class="style2">-warn_with_trace</p>
 773
 774     If the <span class="style2">-debug</span> level is bigger than zero PsN will print warning
 775     messages. If <span class="style2">-warn_with_trace</span> is set, PsN will print a stack
 776     trace from the point where the warning message was printed.
 777     This is definitly only for developers.
 778
 779 EOF
 780
 781     $help_hash{-sde} = <<'EOF';
 782     <p class="style2">-sde</p>
 783
 784     If you are running SDE models, you must use this option, otherwise
 785     PsN will destroy the formatting of the models, and the NONMEM runs
 786     will fail.
 787 EOF
 788
 789     $help_hash{'-h'} = $help_hash{'-?'};
 790
 791
 792   if( defined $help_text ){
 793     %help_hash = %{$help_text};
 794   }
 795
 796   my $help;
 797
 798   if($options{'h'} or $options{'?'} or $options{'help'} ) {
 799
 800     if( $options{'html_help'} ){
 801
 802       open(EXAMPLES, '>', 'html/' . $command . '_examples.php' );
 803       print EXAMPLES $help_hash{Examples};
 804       close( EXAMPLES );
 805
 806       open(SYNOPSIS, '>', 'html/' . $command . '_synopsis.php' );
 807       print SYNOPSIS $help_hash{Pre_help_message},"\n";
 808       print SYNOPSIS "<h3 class=\"heading1\">Synopsis</h3>\n";
 809       print SYNOPSIS "<span class=\"option\">\n";
 810       print SYNOPSIS "<pre>$command " . common_options::print_help($command,$required_options, $optional_options)."\n</pre></span>\n" ;
 811       close( SYNOPSIS );
 812
 813       open(OPTIONS, '>', 'html/' . $command . '_options.php' );
 814       my $opt_help;
 815
 816       if( $command eq 'execute' ){
 817         @loop_array = @get_opt_strings;
 818       } else {
 819         @loop_array = (sort(keys %{$required_options}), sort(keys %{$optional_options}));
 820       }
 821
 822       foreach my $option( @loop_array ){
 823         #foreach my $option(keys %help_hash){
 824         $option =~ s/[^\w]*$|:.*//;
 825         if( exists $help_hash{'-'.$option}){
 826           $opt_help .= $help_hash{'-'.$option}."\n\n";
 827         } else {
 828           $opt_help .= "      <p class=\"option\">-$option</p>     <p>No help available for '$option'</p>";
 829         }
 830       }
 831       print OPTIONS $help_hash{Options} . $opt_help;
 832       close( OPTIONS );
 833
 834       open(DESC, '>', 'html/' . $command . '_description.php' );
 835       print DESC $help_hash{Description};
 836       close( DESC );
 837
 838       exit;
 839     } else {
 840
 841       if( scalar( @ARGV ) > 0 ){
 842         foreach my $option ( @ARGV ){
 843
 844           if( exists $help_hash{'-'.$option} ){
 845             $help .= "\n".$help_hash{'-'.$option}. "\n";
 846           } else {
 847             $help .= "\nNo help available for '$option'\n\n";
 848           }
 849         }
 850
 851         $help =~ s/<\?.*\?>//g;
 852         $help =~ s/<[^>]*>//g;
 853         print $help;
 854         exit;
 855       }
 856
 857       $help .= "\n" . $help_hash{Pre_help_message} . "\n";
 858       $help .= "\t$command ";
 859       $help .= common_options::print_help($command,$required_options, $optional_options);
 860
 861
 862       if( $options{'help'} ){
 863
 864         $help .= "\n\n".$help_hash{Description}."\n\n";
 865         $help .= $help_hash{Examples}."\n\n";
 866         $help .= $help_hash{Options}."\n\n";
 867
 868         my @loop_array;
 869
 870         if( $command eq 'execute' ){
 871           @loop_array = @get_opt_strings;
 872         } else {
 873           @loop_array = (sort(keys %{$required_options}), sort(keys %{$optional_options}));
 874         }
 875
 876         foreach my $option( @loop_array ){
 877           #print "special case: $option\n" if ( $option =~ /\W+$|:.*/ );
 878           $option =~ s/[^\w]*$|:.*//;
 879           #$option = '-'.$option unless( $option =~ /^-/ );
 880           if( exists $help_hash{'-'.$option}){
 881             $help .= $help_hash{'-'.$option}."\n\n";
 882           } else {
 883             $help .= "      -$option\n\n      No help available for '$option'\n\n\n";
 884           }
 885         }
 886
 887         $help .= $help_hash{Post_help_message} . "\n";
 888
 889       } else {
 890         $help .= "\n  Use '$command -help' for a longer desctription.\n\n";
 891       }
 892
 893       $help =~ s/<\?.*\?>//g;
 894       $help =~ s/<[^>]*>//g;
 895       print $help;
 896
 897       exit;
 898     }
 899   }
 900 }
 901
 902
 903
 904 1;