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