R: Simulate from a model object

mrgsim {mrgsolve} | R Documentation

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

### See Also

mrgsim_variants, `mrgsim_q()`

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

[Package mrgsolve version 1.0.0 Index]