Simulate a bbi_nonmem_model object

Source: R/vpc-simulation.R

Create and submit a new bbi_nmsim_model object, which is then attached to the existing bbi_nonmem_model object

add_simulation(
  .mod,
  n = 200,
  seed = 1234,
  data = NULL,
  sim_cols = c("DV", "PRED"),
  gitignore_sim = getOption("bbr.gitignore_sim"),
  .join_col = "NUM",
  .inherit_tags = TRUE,
  .bbi_args = NULL,
  .mode = getOption("bbr.bbi_exe_mode"),
  ...,
  .overwrite = NULL,
  .config_path = NULL,
  .wait = TRUE,
  .dry_run = FALSE
)

has_simulation(.mod)

get_simulation(.mod)

Arguments

.mod

A bbi_nonmem_model or bbi_nonmem_summary object

n

Number of simulations/subproblems. Adds SUBPROBLEMS=n to a $SIMULATION record.

seed

A seed for simulation. Appended to $SIMULATION record.

data

A dataset to simulate from. Defaults to NULL, which will use use the original data. If provided, must include the same column names as what's returned from nm_data(.mod).

sim_cols

Character column name(s) defining the simulated values to table out.

gitignore_sim

If TRUE, the default, add the simulation output directory to a .gitignore file. The intention here is to avoid committing large files (i.e. large simulation tables). This can be passed directly to this argument or set globally with options("bbr.gitignore_sim").

.join_col

Character column name(s) used to join table files post execution. Gets appended to the generated $TABLE record. See nm_join_sim() documentation for details. Defaults to 'NUM'.

.inherit_tags

If TRUE, the default, inherit any tags from .mod.

.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.

.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.

Details

add_simulation does the following things:

  • Checks that .mod was previously executed and tabled out an MSF file (i.e. $EST MSFO=1.MSF).

    • Note: If you are using bbi <= 3.3.0, the MSF file must have an upper case extension. By default, bbi <= 3.3.0 will delete .msf (lower case) files upon model completion.

  • Performs various checks to confirm the status of .mod, the contents of its control stream, and the input data.

  • Creates a new bbi_nmsim_model object with the following differences from the original control stream:

    • Removes the following record types for simulation: $EST, $COV, $TABLE, $SIMULATION

    • Removes PK and prior records: $PRIOR, $THETA/$THETAP/$THETAPV, $OMEGA/$OMEGAP/$OMEGAPD, $SIGMA/$SIGMAP/$SIGMAPD

    • Adds a new custom $SIMULATION record using user specified values (e.g. seed and n).

      • TRUE=FINAL is appended to ensure the final values are used rather than the initial estimates.

      • ONLYSIMULATION flag is appended to reduce run times.

    • Adds a new $TABLE record tabling out simulated values (sim_cols) and .join_col column(s)

    • Adds a new $MSFI record (run with NOMSFTEST) pointing to the MSF file of .mod

  • Creates a specification file, storing seeds, n, and other various items helpful for traceability purposes.

  • Submits the model for execution.

Functions

  • add_simulation(): Add a simulation to a bbi_nonmem_model object

  • has_simulation(): Helper for determining if a bbi_nonmem_model has a simulation attached to it. Returns TRUE if a bbi_nmsim_model specification file is found within the output directory of .mod, and FALSE otherwise.

  • get_simulation(): Read in and return a bbi_nmsim_model object stored within the output directory of .mod.

Re-running existing simulation

By default, the output directory of the simulation is gitignore'd (see gitignore_sim argument). When a collaborator attempts to read in the parent model, they would see it has an attached simulation with a status of "Not Run".

To re-run this simulation using the specs that were originally used, you can simply execute the following commands:

.sim <- get_simulation(.mod)
submit_model(.sim)

This will execute the simulation using the same n, seed, and data that were provided by the collaborator.

See also

nm_join_sim()

Examples

if (FALSE) {

# Add a new simulation and submit for execution
add_simulation(
  .mod,
  n = 100,
  .mode = "local",
  .wait = FALSE
)

# Optionally read in simulation model object
if(has_simulation(.mod)){
 .sim <- get_simulation(.mod)
}
}