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