Submit a model to be run

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

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 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 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 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: Either "sge", the default, to submit model(s) to the grid or "local" for local execution. This can be passed directly to this argument or set globally with options("bbr.bbi_exe_mode").
...: 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.

Arguments

Value

Methods (by class)

Notes on NONMEM model extensions

See also

Notes on `NONMEM` model extensions