mrgsolve: mrgsim – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

mrgsim

Simulate from a model object

Description

This function sets up the simulation run from data stored in the model object as well as arguments passed in. Use mrgsim_q() instead to benchmark mrgsolve or to do repeated quick simulation for tasks like parameter optimization, sensitivity analyses, or optimal design. See mrgsim_variants for other mrgsim-like functions that have more focused inputs. mrgsim_df coerces output to data.frame prior to returning.

Usage

mrgsim(x, data = NULL, idata = NULL, events = NULL, nid = 1, ...)

mrgsim_df(..., output = "df")

do_mrgsim(
  x,
  data,
  idata = no_idata_set(),
  carry_out = carry.out,
  carry.out = character(0),
  recover = character(0),
  seed = as.integer(NA),
  Request = character(0),
  output = NULL,
  capture = NULL,
  obsonly = FALSE,
  obsaug = FALSE,
  tgrid = NULL,
  recsort = 1,
  deslist = list(),
  descol = character(0),
  filbak = TRUE,
  tad = FALSE,
  nocb = TRUE,
  skip_init_calc = FALSE,
  ss_n = 500,
  ss_fixed = FALSE,
  interrupt = 256,
  ...
)

Arguments

`x`	the model object
`data`	NMTRAN-like data set (see `data_set()`)
`idata`	a matrix or data frame of model parameters, one parameter per row (see `idata_set()`)
`events`	an event object
`nid`	integer number of individuals to simulate; only used if idata and data are missing
`...`	passed to `update()` and `do_mrgsim()`
`output`	if `NULL` (the default) a mrgsims object is returned; otherwise, pass `df` to return a data.frame or `matrix` to return a matrix
`carry_out`	numeric data items to copy into the output
`carry.out`	soon to be deprecated; use `carry_out` instead
`recover`	character column names in either `data` or `idata` to join back (recover) to simulated data; may be any class (e.g. numeric, character, factor, etc)
`seed`	deprecated
`Request`	compartments or captured variables to retain in the simulated output; this is different than the `request` slot in the model object, which refers only to model compartments
`capture`	character file name used for debugging (not related to `$CAPTURE`)
`obsonly`	if `TRUE`, dosing records are not included in the output
`obsaug`	augment the data set with time grid observations; when `TRUE` and a full data set is used, the simulated output is augmented with an observation at each time in `stime()`. When using `obsaug`, a flag indicating augmented observations can be requested by including `a.u.g` in `carry_out`
`tgrid`	a tgrid object; or a numeric vector of simulation times or another object with an `stime` method
`recsort`	record sorting flag. Default value is 1. Possible values are 1,2,3,4: 1 and 2 put doses in a data set after padded observations at the same time; 3 and 4 put those doses before padded observations at the same time. 2 and 4 will put doses scheduled through `addl` after observations at the same time; 1 and 3 put doses scheduled through `addl` before observations at the same time. `recsort` will not change the order of your input data set if both doses and observations are given.
`deslist`	a list of tgrid objects
`descol`	the name of a column for assigning designs
`filbak`	carry data items backward when the first data set row has time greater than zero
`tad`	when `TRUE` a column is added to simulated output is added showing the time since the last dose. Only data records with `evid == 1` will be considered doses for the purposes of `tad` calculation. The `tad` can be properly calculated with a dosing lag time in the model as long as the dosing lag time (specified in `$MAIN`) is always appropriate for any subsequent doses scheduled through `addl`. This will always be true if the lag time doesn't change over time. But it might (possibly) not hold if the lag time changes prior to the last dose in the `addl` sequence. This known limitation shouldn't affect `tad` calculation in most common dosing lag time implementations.
`nocb`	if `TRUE`, use next observation carry backward method; otherwise, use `locf`.
`skip_init_calc`	don't use `$MAIN` to calculate initial conditions
`ss_n`	maximum number of iterations for determining steady state for the PK system; a warning will be issued if steady state is not achieved within `ss_n` iterations when `ss_fixed` is `TRUE`
`ss_fixed`	if `FALSE` (the default), then a warning will be issued if the system does not reach steady state within `ss_n` iterations given the model tolerances `rtol` and `atol`; if `TRUE`, the number of iterations for determining steady state are capped at `ss_n` and no warning will be issued if steady state has not been reached within `ss_n` dosing iterations. To silence warnings related to steady state, set `ss_fixed` to `TRUE` and set `ss_n` as the maximum number of iterations to try when advancing the system for steady state determination.
`interrupt`	integer check user interrupt interval; when `interrupt` is a positive integer, the simulation will check for the user interrupt signal every `interrupt` simulation records; pass a negative number to never check for the user interrupt interval.

Details

Use mrgsim_df() to return a data frame rather than mrgsims object
Both data and idata will be coerced to numeric matrix
carry_out can be used to insert data columns into the output data set. This is partially dependent on the nature of the data brought into the problem
When using data and idata together, an error is generated if an ID occurs in data but not idata. Also, when looking up data in idata, ID in idata is assumed to be uniquely keyed to ID in data. No error is generated if ID is duplicated in data; parameters will be used from the first occurrence found in idata
carry_out: idata is assumed to be individual-level and variables that are carried from idata are repeated throughout the individual's simulated data. Variables carried from data are carried via last-observation carry forward. NA is returned from observations that are inserted into simulated output that occur prior to the first record in data
recover: this is similar to carry_out with respect to end result, but it uses a different process. Columns to be recovered are cached prior to running the simulation, and then joined back on to the simulated data. So, whereas carry_out will only accept numeric data items, recover can handle data frame columns of any type. There is a small decrease in performance with recover compared to carry_out, but it is likely that the performance difference is difficult to perceive (when the simulation runs very fast) or only a small fractional increase in run time when the simulation is very large. And any performance hit is likely to be well worth it in light of the convenience gain. Just think carefully about using this feature when every millisecond counts.

Value

An object of class mrgsims

Examples

## example("mrgsim")

e <- ev(amt = 1000)

mod <- mrgsolve::house() 

out <- mod %>% ev(e) %>% mrgsim()

plot(out)

out <- mod %>% ev(e) %>% mrgsim(end=22)

out

data(exTheoph)

out <- mod %>% data_set(exTheoph) %>% mrgsim()

out

out <- mod %>% mrgsim(data=exTheoph)

out <- mrgsim(mod, data=exTheoph, obsonly=TRUE)

out

out <- mod %>% mrgsim(data=exTheoph, obsaug=TRUE, carry_out="a.u.g")

out

out <- mod %>% ev(e) %>% mrgsim(outvars="CP,RESP")

out

a <- ev(amt = 1000, group = 'a')
b <- ev(amt = 750, group = 'b')
data <- as_data_set(a,b)

out <- mrgsim_d(mod, data, recover="group")

out

mrgsolve

Simulate from ODE-Based Models

v0.11.1

GPL (>= 2)

Authors

Kyle T Baron [aut, cre] (<https://orcid.org/0000-0001-7252-5656>), Bill Gillespie [ctb], Charles Margossian [ctb], Devin Pastoor [ctb], Bill Denney [ctb] (<https://orcid.org/0000-0002-5759-428X>), Dilawar Singh [ctb], Felicien Le Louedec [ctb] (<https://orcid.org/0000-0003-3699-2729>), Timothy Waterhouse [ctb] (<https://orcid.org/0000-0002-0954-9660>), Metrum Research Group [cph]

Initial release