Skip to contents

Submit a model to be run

Source: R/submit-model.R
submit_model.Rd

Submits a model to be run by calling out to bbi.

Usage

submit_model(
  .mod,
  .bbi_args = NULL,
  .mode = getOption("bbr.bbi_exe_mode"),
  ...,
  .overwrite = NULL,
  .config_path = NULL,
  .wait = TRUE,
  .dry_run = FALSE
)

# S3 method for class 'bbi_base_model'
submit_model(
  .mod,
  .bbi_args = NULL,
  .mode = getOption("bbr.bbi_exe_mode"),
  ...,
  .overwrite = NULL,
  .config_path = NULL,
  .wait = TRUE,
  .dry_run = FALSE
)

# S3 method for class 'bbi_nmsim_model'
submit_model(
  .mod,
  .bbi_args = NULL,
  .mode = getOption("bbr.bbi_exe_mode"),
  ...,
  .overwrite = NULL,
  .config_path = NULL,
  .wait = TRUE,
  .dry_run = FALSE
)

# S3 method for class 'bbi_nmboot_model'
submit_model(
  .mod,
  .bbi_args = NULL,
  .mode = "sge",
  ...,
  .overwrite = FALSE,
  .config_path = NULL,
  .wait = FALSE,
  .dry_run = FALSE,
  .batch_size = 100
)

Arguments

.mod

The model object to submit.

.bbi_args

A named list specifying arguments to pass to bbi formatted like list("nm_version" = "nm74gf_nmfe", "json" = T, "threads" = 4). Run print_bbi_args() to see valid arguments. Note that bbr does not support changing the output directory (including through the model or global YAML files).

.mode

Mode for model submission: "local", "sge", or "slurm". If unspecified, the value is set to the value of the bbr.bbi_exe_mode option. This option defaults to "sge" on Linux and "local" otherwise.

...

args passed through to bbi_exec()

.overwrite

Logical to specify whether or not to overwrite existing model output from a previous run. If NULL, the default, will defer to setting in .bbi_args or bbi.yaml. If not NULL will override any settings in .bbi_args or bbi.yaml. The exception to this are bootstrap runs (bbi_nmboot_model objects). For bootstrap runs, this defaults to FALSE and does not respect any setting passed via .bbi_args or a bbi.yaml config file. To overwrite existing bootstrap output, a user must pass TRUE through this argument.

.config_path

Path to a bbi configuration file. If NULL, the default, will attempt to use a bbi.yaml in the same directory as the model.

.wait

If TRUE, the default, wait for the bbi process to return before this function call returns. If FALSE function will return while bbi process runs in the background.

.dry_run

Returns an object detailing the command that would be run, insted of running it. This is primarily for testing but also a debugging tool.

.batch_size

Number of models to submit to run concurrently as a "batch." Passing NULL (or a number larger than the number of submitted models) will bypass this and submit all models concurrently. This will launch a background process to manage the batch submission. Details from this process are logged in the OUTPUT file in top-level bootstrap model directory.

Value

While submit_model() does return something, it is primarily called for its side effects, specifically that it runs the model and writes all model outputs to disk under get_output_dir(.mod).

NONMEM For NONMEM models, a bbi_process object is returned. The typical NONMEM output files are all written into get_output_dir(.mod). A summary of the contents of these files can be accessed with model_summary(), and the path to individual files can be easily constructed like build_path_from_model(.mod, ".lst").

A bbi_config.json file is also written, which stores information about the configuration of the run. See config_log() for more details about this file.

Methods (by class)

  • submit_model(bbi_base_model): Takes a bbi_base_model object.

  • submit_model(bbi_nmsim_model): Takes a bbi_base_model object.

  • submit_model(bbi_nmboot_model): Takes a bbi_nmboot_model object.

Notes on NONMEM model extensions

Before executing the model, bbi first copies the control stream file to a subdirectory. Whether a relative path to the data file in the control stream is adjusted for this change in directory depends on the control stream's file extension:

  • For a model with a .mod extension, bbi automatically adjusts a relative data path to make it relative to the execution directory, following the behavior of PsN.

  • For a model with a .ctl extension, bbi does not adjust the data path. A relative data path in the control stream must be specified one level deeper (i.e. with an additional ../) to account for the model being executed in a subdirectory.

See also

submit_models()

Other NONMEM model extensions: get_data_path(), submit_models()