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