simulate: Simulate a 'bbi_nonmem_model' object

In metrumresearchgroup/rbabylon: R package for bbi

Simulate a bbi_nonmem_model object

Description

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

Usage

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

## Not run: 

# 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)
}

## End(Not run)

metrumresearchgroup/rbabylon documentation built on April 12, 2025, 3:51 p.m.