7  Simulated output

7.1 Output types

When mrgsim() is used to simulate from a model, it by default returns an object with class mrgsims. This is an S4 object containing a data.frame of simulated output and a handful of other pieces of data related to the simulation run that can be coerced to other types (like data.frame or tibble).

For simulations with large outputs or extremely brief simulations where efficiency is important, users can request the output be returned as a data frame. This is most efficient when the features provided by the mrgsims object are not needed. To do this, pass the output argument to mrgsim()

out <- mrgsim(mod, ..., output = "df")

or use mrgsim_df()

out <- mrgsim_df(mod, ....)

7.2 Methods for mrgsim output

mrgsolve provides several methods for working with mrgsims objects or coercing the simulation matrix into other R objects. Note the discussion in the following subsections all refer to working with mrgsims objects, not data.frame output.

7.2.1 Coercion methods

  • as_tibble(): convert to tibble
  • as.data.frame(): convert to data.frame
  • as.matrix(): convert to matrix

7.2.2 Query methods

  • head(): shows the first n = 5 rows
  • tail(): shows the last n = 5 rows
  • names(): shows the column names
  • dim(): shows the number of rows and columns
  • summary(): shows a numeric summary of all columns
  • $: extracts a column

7.2.3 Graphical methods

There is a plot() methods for simulated output that is aware of independent and dependent variables from the simulation. If out is the simulated output (an mrgsims object)

plot(out)

Plot with a formula; the following example selects only the CP and RESPONSE outputs and plots them versus time

plot(out, CP + RESPONSE ~ time)

To select a large number of responses to plot, pass a character vector or comma-separated character data containing output columns to plot

plot(out, "CP, RESPONSE, WT, DOSE")

7.2.4 Methods for dplyr verbs

mrgsolve provides several S3 methods to make it possible to include dplyr verbs in your simulation pipeline.

For example

library(dplyr)
library(mrgsolve)

mod <- house()

mod %>% 
  ev(amt=100) %>%
  mrgsim() %>% 
  filter(time >= 10)

Here, mrgsim() returns an mrgsims object. When dplyr is also loaded, this object can be piped directly to dplyr::filter() or dplyr::mutate() etc.

It is important to note that when mrgsims output is piped to dplyr functionality, it is coerced to tibble (data.frame) and there is no way to get the data back to mrgsims object. Most of the time, this is desirable and there is no need to explicitly coerce to tibble() when calling dplyr verbs on simulated output.

Other dplyr functions that can be used with mrgsims objects

  • group_by()
  • mutate()
  • filter()
  • summarise()
  • select()
  • slice()
  • pull()
  • distinct()
  • slice()

7.2.5 Modify methods

You can modify the underlying data in the mrgsims object and keep it as an mrgsims object.

  • filter_sims(): calls dplyr::filter() to pick rows to keep or discard
  • select_sims(): calls dplyr::select(); note that ID and time columns are always retained
  • mutate_sims(): calls dplyr::mutate() to add or modify columns

7.3 Controlling output scope

7.3.1 Background

Limiting the volume of simulated data can have a major impact on simulation efficiency, memory footprint, and ease (or lack of ease) in reviewing and dealing with the output. For any large simulation or any simulation from a large model, the user should consider selecting what gets returned when the simulation is performed.

By default, mrgsim() returns a data.frame with the following

  1. ID: regardless of whether you simulated a population or not
  2. time / TIME: the independent variable
  3. Simulated values for all model compartments
  4. Simulated values for derived outputs listed in $CAPTURE

You will always get ID and time and the compartments and any captured items must be written into the model file. This defines the list of data items that could (possibly) get returned under items 3 and 4 above. Again: this must be written into the model file and is locked at the time the model is compiled.

However, mrgsolve allows the user to pick what is actually returned at run time. Because this is done at run time, different runs can return different data items. And (importantly) mrgsim() only allocates space in the output for data items that are requested. So, opting out of unneeded outputs will decrease memory consumption and increase efficiency.

7.3.2 Implementation

The mrgsolve model object tracks compartments and captures that are currently being requested. This can be queried using outvars()

mod <- house()

outvars(mod)
. $cmt
. [1] "GUT"  "CENT" "RESP"
. 
. $capture
. [1] "DV" "CP"

Items are listed under cmt and capture. The user can update the model object with the names of columns that are being requested by passing outvars to update()

mod <- update(mod, outvars = "CP, RESP")

outvars(mod)
. $cmt
. [1] "RESP"
. 
. $capture
. [1] "CP"

This will exclude anything that isn’t named in the update. The outvars list can be reset by passing (all)

mod <- update(mod, outvars = "(all)")

Remember that ... passed to mrgsim() are also passed to update() so it is possible to select outputs right in your mrgsim() call

out <- mrgsim(mod, outvars = "CP, RESP")

7.3.3 Copy items from data to simulated output

Users can also use carry_out and recover to copy items from the input data into the output. This is covered in a different chapter.