lib/common_options.pm

   1 package common_options;
   2
   3 use FindBin qw($Bin);
   4 use lib "$Bin/../lib";
   5 use Getopt::Long;
   6
   7 ## Configure the command line parsing
   8 Getopt::Long::config("auto_abbrev");
   9
  10 my @tool_options = ( "abort_on_fail",
  11                      "clean:0",
  12                      "compress",
  13                      "condition_number_limit:f",
  14                      "correlation_limit:f",
  15                      "cpu_time:i",
  16                      "directory:s",
  17                      "drop_dropped",
  18                      "grid_batch_size:i",
  19                      "grid_poll_interval:i",
  20                      "handle_maxevals",
  21                      "large_theta_cv_limit:f",
  22                      "large_omega_cv_limit:f",
  23                      "large_sigma_cv_limit:f",
  24                      "lsf_job_name:s",
  25                      "lsf_options:s",
  26                      "lsf_project_name:s",
  27                      "lsf_queue:s",
  28                      "lsf_resources:s",
  29                      "lsf_ttl:s",
  30                      "missing_data_token:s",
  31                      "near_bound_sign_digits:i",
  32                      "near_zero_boundary_limit:f",
  33                      "nice:i",
  34                      "nm_version:s",
  35                      "nm_directory:s",
  36                      "no_remote_compile",
  37                      "no_remote_execution",
  38                      "picky",
  39                      "remove_temp_files",
  40                      "results_file:s",
  41                      "retries:i",
  42                      "run_on_nordugrid",
  43                      "run_on_lsf",
  44                      "seed:s",
  45                      "sigdig_rerun:f",
  46                      "sign_digits_off_diagonals:i",
  47                      "summarize",
  48                      "threads:i",
  49                      "tweak_inits",
  50                      "wrap_data"
  51                      );
  52
  53
  54 my @model_options = ("extra_data_files:s@",
  55                      "extra_files:s",
  56                      "sde",
  57                      "outputfile:s",
  58                      );
  59
  60 my @script_options = ( "debug:0",
  61                        "debug_package:s",
  62                        "debug_subroutine:s",
  63                        "h|?",
  64                        "help",
  65                        "html_help",
  66                        "silent",
  67                        "submit_self",
  68                        "warn_with_trace:i"
  69                        );
  70
  71 @get_opt_strings = (@tool_options, @model_options, @script_options);
  72
  73 sub options_to_parameters {
  74   my $opts = shift;
  75   my @options = @{$opts};
  76
  77   my $parameter_string = '( ';
  78
  79   foreach my $opt ( @options ){
  80     $opt =~ s/:.*//g;
  81     $parameter_string .= "$opt => \$options{'$opt'},\n";
  82   }
  83
  84   $parameter_string .= ' )';
  85
  86   return $parameter_string;
  87 }
  88
  89 $parameters = options_to_parameters(\@tool_options);
  90
  91 @extra_files;
  92
  93 sub print_help {
  94   my( $command, $required, $optional ) = @_;
  95   my %is_required;
  96   my %all_options = (%{$required},%{$optional});
  97
  98   foreach my $req( keys %{$required} ){
  99     $is_required{$req} = 1;
 100   }
 101
 102   my $option_help;
 103
 104   $option_help .= "[ -h | -? ] [ --help ]\n\t" . ' ' x (1+length($command));
 105   foreach my $help( sort(keys %{$required}), sort(keys %{$optional}), sort(@get_opt_strings) ){
 106     next if( $help eq 'help' or $help eq 'h|?' );
 107     unless( $is_required{$help} ){
 108       $option_help .= "[ ";
 109     } else {
 110       $option_help .= "  ";
 111     }
 112     if( $all_options{$help} ne '' ){
 113       $help =~ /^([^:]+)/;
 114       $option_help .= "--$1=\'" . $all_options{$help} . "\'";
 115     } elsif( $help =~ /(.+):s/ ){
 116       $option_help .= "--$1=\'string\'";
 117     } elsif( $help =~ /(.+):i/ ){
 118       $option_help .= "--$1=\'integer\'";
 119     } elsif( $help =~ /(.+):f/ ){
 120       $option_help .= "--$1=\'number\'";
 121     } elsif( $help =~ /(.+):(\d)/ ){
 122       $option_help .= "--$1=$2";
 123     } elsif( $help =~ /(.+)[^:]$/ ){
 124       $option_help .= "--$help";
 125     }
 126     unless( $is_required{$help} ){
 127       $option_help .= " ]";
 128     }
 129     $option_help .= "\n\t".' ' x (1+length($command));
 130   }
 131
 132   return $option_help;
 133 }
 134
 135 sub model_parameters {
 136   my $options = shift;
 137   #my %options = %{$opt};
 138
 139   if( defined $options -> {'extra_data_files'} ){
 140     for( my $i=0; $i < scalar(@{$options -> {'extra_data_files'}}) ; $i++ ){
 141       my @arr = split( /,/ , @{$options -> {'extra_data_files'}}[$i] );
 142       if( @arr < 2 ){
 143         die "extra_data_file must be of form: \"filename, head1, head2\"\n" ;
 144       }
 145
 146       @{$options -> {'extra_data_files'}}[$i] = $arr[0];
 147       my @subarray = @arr[1..$#arr];
 148       push( @{$options -> {'extra_data_headers'}}, \@subarray )
 149     }
 150   }
 151   if( defined $options -> {'extra_files'} ){
 152     @{$options -> {'extra_files'}} = split( /,/ , $opt_extra_files );
 153   }
 154   push(@model_options, 'extra_data_headers');
 155
 156   return options_to_parameters(\@model_options);
 157
 158 }
 159
 160
 161 sub online_help {
 162
 163   my $command = shift;
 164   my $opts = shift;
 165   my $help_text = shift;
 166   my $required_options = shift;
 167   my $optional_options = shift;
 168   my %options = %{$opts};
 169
 170   my %help_hash;
 171
 172   $help_hash{Pre_help_message} = << 'EOF';
 173   <h3 class="heading1">execute</h3>
 174
 175       Perl script running one or more modelfiles using PsN.
 176
 177   <h3 class="heading1">Usage:</h3>
 178 EOF
 179
 180     $help_hash{Description} = <<'EOF';
 181   <h3 class="heading1">Description:</h3>
 182
 183     The execute utility is a Perl script that allows you to run multiple
 184     modelfiles either sequentially or in parallel. It is more or less an
 185     nmfe replacement.
 186     <br><br>
 187     The execute utility creates subdirectories where it puts NONMEMs
 188     input and output files, to make sure that parallel NONMEM runs do not
 189     interfere with each other. The top directory is by default named
 190     'modelfit_dirX' where 'X' is a number that starts at 0 and is
 191     increased by one each time you run the execute utility.
 192     <br><br>
 193     When the NONMEM runs are finished, the output and table files will be
 194     copied to the directory where execute started in which means that you
 195     can normaly ignore the 'modelfit_dirX' directory. If you need to
 196     access any special files you can find them inside the
 197     'modelfit_dirX'. Inside the 'modelfit_dirX' you find a few
 198     subdirectories named 'NM_runY'. For each model file you
 199     specified on the command line there will be one 'NM_runY' directory in
 200     which the actual NONMEM execution takes place. The order of the
 201     'NM_runY' directories corresponds to the order of the modelfiles given
 202     on the command line. The first run will take place inside 'NM_run1',
 203     the second in 'NM_run2' and so on.
 204 EOF
 205
 206     $help_hash{Examples} = <<'EOF';
 207   <h3 class="heading1">Example:</h3>
 208
 209     <p align="justify" class="style2">$ execute pheno.mod </p>
 210
 211     <p align="justify">Runs one model file and accepts all default values.</p>
 212
 213     <p align="justify" class="style2">$ execute -threads=2  -retries=5 phenobarbital.mod pheno_alternate.mod</p>
 214
 215     <p align="justify">Runs two model files in parallel using 5 possible retries.</>p
 216 EOF
 217
 218     $help_hash{Options} = <<'EOF';
 219   <h3 class="heading1">Options:</h3>
 220
 221     The options are given here in their long form. Any option may be
 222     abbreviated to any nonconflicting prefix. The <span class="style2">-threads</span> option may
 223     be abbreviated to <span class="style2">-t</span> (or even <span class="style2">-thr</span>) but <span class="style2">-debug</span> may not be
 224     abbreviated to <span class="style2">-d</span> because it conflicts with <span class="style2">-debug_packages</span> and
 225     <span class="style2">-debug_subroutines</span>.
 226     <br><br>
 227     The following options are valid:
 228 EOF
 229
 230     $help_hash{'-?'} = <<'EOF';
 231     <p class="style2">-h | -?</p>
 232
 233     With <span class="style2">-h</span> or <span class="style2">-?</span> execute.pl prints the list of options and exit.
 234 EOF
 235
 236     $help_hash{-help} = <<'EOF';
 237     <p class="style2">-help</p>
 238
 239     With <span class="style2">-help</span> execute will print this, longer, help message.
 240 EOF
 241
 242     $help_hash{-nm_version} = <<'EOF';
 243     <p class="style2">-nm_version='integer'</p>
 244
 245     If you have more than one installation of NONMEM you can choose
 246     between them using the <span class="style2">-nm_version</span> option. The installations must be
 247     specified in the psn.conf file. The default value is 5.
 248 EOF
 249
 250     $help_hash{-threads} = <<'EOF';
 251     <p class="style2">-threads='integer'</p>
 252
 253     Use the threads option to enable parallel execution of multiple
 254     NONMEM runs. On a desktop computer it is recommended to set
 255     <span class="style2">-threads</span> to the number of CPUs in the system plus one. You can
 256     specify more threads, but it will probably not increase the
 257     performance. If you are running on a computer cluster, you should
 258     consult your systems administrator to find out how many threads
 259     you can specify. The <span class="style2">-threads</span> option will be ignored if you run on
 260     a grid system, since gridshave ther own scheduling algoritms. The
 261     default value for the <span class="style2">-threads</span> option is 1.
 262 EOF
 263
 264     $help_hash{-nice} = <<'EOF';
 265     <p class="style2">-nice='integer'</p>
 266
 267     This option only has effect on unix like operating systems. It
 268     sets the priority (or nice value) on a process. You can give any
 269     value that is legal for the "nice" command, likely it is between 0
 270     and 19, where 0 is the highest priority. Check "man nice" for
 271     details.
 272 EOF
 273
 274     $help_hash{-directory} = <<'EOF';
 275     <p class="style2">-directory='string'</p>
 276
 277     The directory option sets the directory in which execute will run
 278     NONMEM. The default directory name is 'modelfit_dirX' where X will
 279     be increased by one each time you run the execute utility. You do
 280     not have to create the directory, it will be done for you.
 281
 282     If you abort execute or if your system crashes you can use the
 283     '<span class="style2">-directory</span>' option set to the directory of the execute run that
 284     crashed. Execute will then not run the modelfiles that had
 285     finished before the crash, thereby saving some time. Notice that
 286     is important that you give exactly the same options that you gave
 287     the first time.
 288 EOF
 289
 290     $help_hash{-seed} = <<'EOF';
 291     <p class="style2">-seed='string'</p>
 292
 293     If you use the <span class="style2">-retries='integer'</span> option, execute will use a
 294     random number to create new intial estimates for the model
 295     parameters. To make sure that the same result is produced if you
 296     redo the same run, you can set your own random seed with the <span class="style2">-seed</span>
 297     option.
 298 EOF
 299
 300     $help_hash{-remove_temp_files} = <<'EOF';
 301     <p class="style2">-remove_temp_files</p>
 302
 303     If the <span class="style2">-remove_temp_files</span> option is set to 1, execute will remove
 304     the 'FCON', 'FDATA', 'FREPORT', 'FSUBS', 'FSUBS.f', 'LINK.LNK',
 305     'FSTREAM', 'PRDERR' and 'nonmem' files from the 'NM_runX'
 306     directory. The default value is 0.
 307 EOF
 308
 309     $help_hash{-clean} = <<'EOF';
 310     <p class="style2">-clean</p>
 311
 312     A more thorough version of <span class="style2">'-remove_temp_files'</span>. If the <span class="style2">-clean</span>
 313     option is set to 1, execute will remove the entire 'NM_runX'
 314     directory after the NONMEM run is finished. The dfault value of
 315     <span class="style2">-clean </span>is 0.
 316 EOF
 317
 318     $help_hash{-compress} = <<'EOF';
 319     <p class="style2">-compress</p>
 320
 321     The execute utility will compress the contents of 'NM_runX' to the
 322     file 'nonmem_files.tgz' if the <span class="style2">-compress</span> option is used and if you
 323     have the archive and compress programs <strong>tar</strong> and <strong>gzip</strong> installed. If
 324     you use the <span class="style2">-remove_temp_files</span> options, temporary files will be
 325     removed before the compression. The <span class="style2">-compress</span> option obviously has
 326     no effect if you also use the <span class="style2">-clean</span> option.
 327 EOF
 328
 329     $help_hash{-tweak_inits} = <<'EOF';
 330     <p class="style2">-tweak_inits</p>
 331
 332     <!--/>If NONMEM terminates nonsuccessfully, PsN can perturb the initial
 333     estimates and run NONMEM again. The generation of new initial
 334     estimates init_i for the i:th retry are performed according to
 335
 336     init_i = init_0 + rand_uniform(+-0.1*i*init_0)
 337
 338     where init_0 are the initial estimates of the original run. The
 339     updating procedure makes sure that boundary conditions on the
 340     parameters are still valid. For this option to have effect, the
 341     -retries option must be set to number larger than zero. The
 342     default setting uses tweak_inits.<-->
 343
 344     <?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>'; ?>
 345 EOF
 346
 347     $help_hash{-outputfile} = <<'EOF';
 348     <p class="style2">-outputfile</p>
 349
 350     The <span class="style2">-outputfile</span> option specifies the output file name for the
 351     NONMEM run. Currently This option is only valid when a single
 352     model is supplied to the execute utility.
 353 EOF
 354
 355     $help_hash{-picky} = <<'EOF';
 356     <p class="style2">-picky</p>
 357
 358     The <span class="style2">-picky</span> option is only valid together with
 359     <span class="style2">-tweak_inits</span>. Normally PsN only tries new initial estimates if
 360     '<span class="style2">MINIMZATION SUCCESSFUL</span>' is not found in the NONMEM output
 361     file. With the <span class="style2">-picky</span> option, PsN will regard any of the following
 362     messages as a signal for rerunning:
 363 <p class="style2">
 364     0ESTIMATE OF THETA IS NEAR THE BOUNDARY<br>
 365     0PARAMETER ESTIMATE IS NEAR ITS BOUNDARY<br>
 366     0R MATRIX ALGORITHMICALLY SINGULAR<br>
 367     0S MATRIX ALGORITHMICALLY SINGULAR</p>
 368 EOF
 369
 370     $help_hash{-retries} = <<'EOF';
 371     <p class="style2">-retries='integer'</p>
 372
 373     The <span class="style2">-retries</span> option tells the execute utility how many times it
 374     shall try to rerun a NONMEM job if it gets an error message. In
 375     the current version of PsN (2.2), the <span class="style2">-retries</span> option is only
 376     valid together with <span class="style2">-tweak_inits</span>. The default value of the
 377     <span class="style2">-retries</span> option is 0.
 378 EOF
 379
 380     $help_hash{-abort_on_fail} = <<'EOF';
 381     <p class="style2">-abort_on_fail</p>
 382
 383     If the <span class="style2">-abort_on_fail</span> option is set and one of the NONMEM runs
 384     fails, execute will stop scheduling more runs and try to stop
 385     those that are currently running.
 386 EOF
 387
 388     $help_hash{-run_on_nordugrid} = <<'EOF';
 389     <p class="style2">-run_on_nordugrid</p>
 390
 391     !! Currently only valid for Linux system !!
 392     execute will run on nordugrid clusters listed in ~/.ng_cluster .
 393     If you do not know about Nordugrid, you can safely ignore this option.
 394     Read more on http://www.nordugrid.org
 395 EOF
 396
 397     $help_hash{-cpu_time} = <<'EOF';
 398     <p class="style2">-cpu_time='integer'</p>
 399
 400     !! Currently only valid for Linux system !!
 401     This option specifies the number of minutes allocated for a
 402     gridjob. The default value is 120 minutes. This option is only
 403     valid together with the <span class="style2">-run_on_nordugrid</span> option.
 404 EOF
 405
 406     $help_hash{-grid_batch_size} = <<'EOF';
 407     <p class="style2">-grid_batch_size='integer'</p>
 408
 409     This option specifies the number of nonmem runs that will be
 410     grouped together into one grid job. The default number is 5. This
 411     option is only valid together with the '<span class="style2">-run_on_nordugrid'</span> option.
 412 EOF
 413
 414     $help_hash{-silent} = <<'EOF';
 415     <p class="style2">-silent</p>
 416
 417     The silent option turns off all output from PsN. Results and log
 418     files are still written to disk, but nothing i printed to the
 419     screen.
 420 EOF
 421
 422     $help_hash{-debug} = <<'EOF';
 423     <p class="style2">-debug='integer'</p>
 424
 425     The <span class="style2">-debug</span> option is mainly intended for developers who whish to
 426     debug PsN. By default <span class="style2">-debug</span> is set to zero but you can try
 427     setting it to '1' to enable warning messages. If you run in to
 428     problems that require support, you may have to increase this
 429     number to 2 or 3 and send the output to us.
 430 EOF
 431
 432     $help_hash{-debug_package} = <<'EOF';
 433     <p class="style2">-debug_package='string'</p>
 434
 435     When used together with <span class="style2">-debug</span>, the <span class="style2">-debug_package</span> option makes is
 436     possible to choose which part of PsN you want to see debug
 437     messages for. Again, this option is mostly for developers.
 438 EOF
 439
 440     $help_hash{-debug_subroutine} = <<'EOF';
 441     <p class="style2">-debug_subroutine='string'</p>
 442
 443     Default value is: empty string
 444
 445     With this option it is possible to specify, with even finer
 446     granularity, which part of PsN you want to see debug messages
 447     from. This is definitly only for developers.
 448 EOF
 449
 450     $help_hash{-sde} = <<'EOF';
 451     <p class="style2">-sde</p>
 452
 453     If you are running SDE models, you must use this option, otherwise
 454     PsN will destroy the formatting of the models, and the NONMEM runs
 455     will fail.
 456 EOF
 457
 458
 459
 460   if( defined $help_text ){
 461     %help_hash = %{$help_text};
 462   }
 463
 464   my $help;
 465
 466   if($options{'h'} or $options{'?'} or $options{'help'} ) {
 467
 468     if( $options{'html_help'} ){
 469
 470       open(EXAMPLES, '>', 'html/' . $command . '_examples.php' );
 471       print EXAMPLES $help_hash{Examples};
 472       close( EXAMPLES );
 473
 474       open(SYNOPSIS, '>', 'html/' . $command . '_synopsis.php' );
 475       print SYNOPSIS $help_hash{Pre_help_message} . "<pre>\t$command " . common_options::print_help($command,$required_options, $optional_options)."</pre>" ;
 476       close( SYNOPSIS );
 477
 478       open(OPTIONS, '>', 'html/' . $command . '_options.php' );
 479       my $opt_help;
 480       foreach my $option(sort(keys %help_hash)){
 481         if( $option =~ /^-/ ){
 482           $opt_help .= $help_hash{$option}."\n\n";
 483         }
 484       }
 485       print OPTIONS $help_hash{Options} . $opt_help;
 486       close( OPTIONS );
 487
 488       open(DESC, '>', 'html/' . $command . '_description.php' );
 489       print DESC $help_hash{Description};
 490       close( DESC );
 491
 492       exit;
 493     } else {
 494
 495       if( scalar( @ARGV ) > 0 ){
 496         foreach my $option ( @ARGV ){
 497
 498           if( exists $help_hash{'-'.$option} ){
 499             $help .= "\n".$help_hash{'-'.$option}. "\n";
 500           } else {
 501             $help .= "\nNo help available for '$option'\n\n";
 502           }
 503         }
 504         $help =~ s/<\?.*\?>//g;
 505         $help =~ s/<[^>]*>//g;
 506         print $help;
 507         exit;
 508       }
 509
 510       $help .= "\n" . $help_hash{Pre_help_message} . "\n";
 511       $help .= "\t$command ";
 512       $help .= common_options::print_help($command,$required_options, $optional_options);
 513
 514
 515       if( $options{'help'} and not( $options{'?'} or $options{'h'} ) ){
 516
 517         $help .= "\n\n".$help_hash{Description}."\n\n";
 518         $help .= $help_hash{Examples}."\n\n";
 519         $help .= $help_hash{Options}."\n\n";
 520
 521         foreach my $option(sort(keys %help_hash)){
 522           if( $option =~ /^-/ ){
 523             $help .= $help_hash{$option}."\n\n";
 524           }
 525         }
 526
 527         $help .= $help_hash{Post_help_message} . "\n";
 528
 529       } else {
 530         $help .= "\n  Use '$command -help' for a longer desctription.\n\n";
 531       }
 532
 533       $help =~ s/<\?.*\?>//g;
 534       $help =~ s/<[^>]*>//g;
 535       print $help;
 536
 537       exit;
 538     }
 539   }
 540 }
 541
 542
 543
 544 1;