Type:	Package
Title:	Simulate from ODE-Based Models
Version:	1.5.2
Maintainer:	Kyle T Baron <kyleb@metrumrg.com>
Description:	Fast simulation from ordinary differential equation (ODE) based models typically employed in quantitative pharmacology and systems biology.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	https://mrgsolve.org/docs/, https://github.com/metrumresearchgroup/mrgsolve
BugReports:	https://github.com/metrumresearchgroup/mrgsolve/issues
Depends:	R (≥ 3.6.2), methods
Imports:	Rcpp (≥ 1.0.7), dplyr (≥ 1.0.8), magrittr (≥ 2.0.1), tibble (≥ 3.1.6), rlang (≥ 1.0.1), tidyselect (≥ 1.1.1), lifecycle, glue
Suggests:	lattice, testthat, xml2 (≥ 1.3.2), rmarkdown, yaml, knitr, data.table (≥ 1.14.2), pmxTools
LinkingTo:	Rcpp (≥ 1.0.7), RcppArmadillo (≥ 0.10.7.3.0), BH (≥ 1.75.0-0)
RdMacros:	lifecycle
Encoding:	UTF-8
Language:	en-US
LazyLoad:	yes
NeedsCompilation:	yes
RoxygenNote:	7.3.2
Collate:	'RcppExports.R' 'utils.R' 'package.R' 'generics.R' 'class_tgrid.R' 'class_numericlist.R' 'class_matlist.R' 'class_ev.R' 'class_derived.R' 'class_mrgmod.R' 'class_mrgsims.R' 'Aaaa.R' 'annot.R' 'chain.R' 'class_build.R' 'class_evd.R' 'events.R' 'class_rx.R' 'compile.R' 'data_set.R' 'datasets.R' 'env.R' 'funset.R' 'handle_spec_block.R' 'idata_set.R' 'init.R' 'inven.R' 'knobs.R' 'matlist.R' 'matrix.R' 'mcode.R' 'model_include.R' 'modlib.R' 'modspec.R' 'mread.R' 'mrgindata.R' 'mrgsim_q.R' 'mrgsims.R' 'mrgsolve.R' 'mwrite.R' 'nm-mode.R' 'nmxml.R' 'param.R' 'print.R' 'r_to_cpp.R' 'realize_addl.R' 'relabel.R' 'render.R' 'update.R' 'workflows.R'
Packaged:	2024-10-18 12:42:49 UTC; kyleb
Author:	Kyle T Baron [aut, cre], Bill Gillespie [ctb], Charles Margossian [ctb], Devin Pastoor [ctb], Bill Denney [ctb], Dilawar Singh [ctb], Felicien Le Louedec [ctb], Timothy Waterhouse [ctb], Kyle Meyer [ctb], Metrum Research Group [cph]
Repository:	CRAN
Date/Publication:	2024-10-18 13:20:05 UTC

mrgsolve: Simulate from ODE-Based Models

Description

mrgsolve is an R package maintained under the auspices of Metrum Research Group that facilitates simulation from models based on systems of ordinary differential equations (ODE) that are typically employed for understanding pharmacokinetics, pharmacodynamics, and systems biology and pharmacology. mrgsolve consists of computer code written in the R and C++ languages, providing an interface to a C++ translation of the lsoda differential equation solver. See aboutsolver for more information.

Resources

• Main mrgsolve resource page: https://mrgsolve.org

• User guide: https://mrgsolve.org/user_guide/

• Package documentation and vignettes: https://mrgsolve.org/docs/

Package-wide options

• mrgolve.project: sets the default project director (mread())

• mrgsolve.soloc: sets the default package build directory (mread())

• mrgsolve_mread_quiet: don't print messages during mread()

• mrgsolve.update.strict: this option has been deprecated; use the strict argument to update() instead

Author(s)

Maintainer: Kyle T Baron kyleb@metrumrg.com (ORCID)

Other contributors:

• Bill Gillespie [contributor]

• Charles Margossian [contributor]

• Devin Pastoor [contributor]

• Bill Denney (ORCID) [contributor]

• Dilawar Singh [contributor]

• Felicien Le Louedec (ORCID) [contributor]

• Timothy Waterhouse (ORCID) [contributor]

• Kyle Meyer [contributor]

• Metrum Research Group [copyright holder]

See Also

Useful links:

• https://mrgsolve.org/docs/

• https://github.com/metrumresearchgroup/mrgsolve

• Report bugs at https://github.com/metrumresearchgroup/mrgsolve/issues

Examples

## example("mrgsolve")

mod <- mrgsolve::house(delta=0.1)  %>% param(CL=0.5)

events <-  ev(amt=1000, cmt=1, addl=5, ii=24)

events

mod

see(mod)

## Not run: 
stime(mod)

## End(Not run)
param(mod)

init(mod)

out <- mod %>% ev(events) %>% mrgsim(end=168)

head(out)
tail(out)
dim(out)

plot(out, GUT+CP~.)

sims <- as.data.frame(out)

t72 <- dplyr::filter(sims, time==72)

str(t72)

idata <- data.frame(ID=c(1,2,3), CL=c(0.5,1,2),VC=12)
out <- mod %>% ev(events) %>% mrgsim(end=168, idata=idata, req="")
plot(out)

out <- mod %>% ev(events) %>% mrgsim(carry_out="amt,evid,cmt,CL")
head(out)

ev1 <- ev(amt=500, cmt=2,rate=10)
ev2 <- ev(amt=100, cmt=1, time=54, ii=8, addl=10)
events <- c(ev1+ev2)
events

out <- mod %>% ev(events) %>% mrgsim(end=180, req="")
plot(out)


## "Condensed" data set
data(extran1)
extran1

out <- mod %>% data_set(extran1) %>% mrgsim(end=200)

plot(out,CP~time|factor(ID))


## idata
data(exidata)

out <- 
  mod %>% 
  ev(amt=1000, cmt=1) %>% 
  idata_set(exidata) %>%  
  mrgsim(end=72)

plot(out, CP~., as="log10")


# Internal model library
## Not run: 
mod <- mread("irm1", modlib())

mod

x <- mod %>% ev(amt=300, ii=12, addl=3) %>% mrgsim


## End(Not run)

Select columns from an ev object

Description

Select columns from an ev object

Usage

## S4 method for signature 'ev'
x$name

## S4 method for signature 'ev'
x[[i, exact = TRUE]]

Arguments

Select parameter values from a model object

Description

The $ and [[ operators get the value of a single parameter in the model. The [ gets several values, returning a named list.

Usage

## S4 method for signature 'mrgmod'
x$name

## S4 method for signature 'mrgmod'
x[[i, exact = TRUE]]

## S4 method for signature 'mrgmod'
x[i]

Arguments

Forward pipe

Description

Forward pipe

Functions to parse code blocks

Description

Most of the basic blocks are listed in this help topic. But see also PKMODEL() which has more-involved options and is documented separately.

Usage

PARAM(
  x,
  env,
  pos = 1,
  annotated = FALSE,
  object = NULL,
  as_object = FALSE,
  covariates = FALSE,
  input = FALSE,
  tag = NULL,
  ...
)

FIXED(x, env, pos = 1, annotated = FALSE, ...)

THETA(
  x,
  env,
  pos = 1,
  annotated = FALSE,
  object = NULL,
  as_object = FALSE,
  name = "THETA",
  fill = NULL,
  ...
)

INIT(x, env, pos = 1, annotated = FALSE, object = NULL, as_object = FALSE, ...)

CMT(
  x,
  env,
  pos = 1,
  annotated = FALSE,
  object = NULL,
  as_object = FALSE,
  number = NULL,
  prefix = "A",
  ...
)

CAPTURE(x, env, pos = 1, annotated = FALSE, etas = NULL, ...)

HANDLEMATRIX(
  x,
  env,
  pos = 1,
  annotated = FALSE,
  object = NULL,
  as_object = FALSE,
  name = "...",
  type = NULL,
  oclass = "",
  prefix = "",
  labels = NULL,
  unlinked = FALSE,
  ...
)

Arguments

Details

When using object or as_object populate the block contents, the following types are required

• PARAM: a named list

• INIT : a named list

• THETA : a numeric vector; names are ignored

• CMT: a character vector

• OMEGA: matrix; set rownames on the matrix to create ETA labels; setting rownames is the only way to specify labels when working through the object or as_object directives

• SIGMA: matrix; set rownames on the matrix to create EPS labels; setting rownames is the only way to specify labels when working through the object or as_object directives

See Also

PKMODEL()

Parse PKMODEL BLOCK data

Description

Parse PKMODEL BLOCK data

Usage

PKMODEL(
  ncmt = 1,
  depot = FALSE,
  cmt = NULL,
  trans = pick_trans(ncmt, depot),
  env = list(),
  pos = 1,
  ...
)

Arguments

Details

When using $PKMODEL, certain symbols must be defined in the model specification depending on the value of ncmt, depot and trans.

• ncmt 1, depot FALSE, trans 2: CL, V

• ncmt 1, depot TRUE , trans 2: CL, V, KA

• ncmt 2, depot FALSE, trans 4: CL, V1, Q, V2

• ncmt 2, depot TRUE , trans 4: CL, V2, Q, V3, KA

If trans=11 is specified, use the symbols listed above for the ncmt / depot combination, but append i at the end (e.g. CLi or Qi or KAi).

If trans=1, the user must utilize the following symbols:

• pred_CL for clearance

• pred_V or pred_V2 for central compartment volume of distribution

• pred_Q for intercompartmental clearance

• pred_V3 for for peripheral compartment volume of distribution

• pred_KA for absorption rate constant

See Also

BLOCK_PARSE

Request simulated output

Description

Use this function to select, by name, either compartments or derived variables that have been captured (see CAPTURE) into the simulated output.

Usage

Req(x, ...)

req(x, ...)

## S3 method for class 'mrgmod'
req(x, ...)

Arguments

Details

There is also a Req argument to mrgsim() that can be set to accomplish the same thing as a call to Req in the pipeline.

Note the difference between req and Req: the former only selects compartments to appear in output while the latter selects both compartments and captured items. Also, when there are items explicitly listed in Req, all other compartments or captured items not listed there are ignored. But when compartments are selected with req all of the captured items are returned. Remember that req is strictly for compartments.

Examples

mod <- mrgsolve::house()

mod %>% Req(CP,RESP) %>% ev(amt=1000) %>%  mrgsim()

About the lsoda differential equation solver used by mrgsolve

Description

The differential equation solver is a C++ translation of DLSODA from ODEPACK. The C++ translation was created by Dilawar Singh and hosted here https://github.com/dilawar/libsoda-cxx/. As we understand the history of the code, Heng Li was also involved in early versions of the code written in C. There was a potentially-related project hosted here https://github.com/sdwfrost/liblsoda/.

Details

The C++ translation by Dilawar Singh contains functions that appear to be based on BLAS and LAPACK routines. These functions have been renamed to be distinct from the respective BLAS and LAPACK function names. References are given in the section below.

History

The following history was recorded in the source code published by Dilawar Singh:

/*
* HISTORY:
* This is a CPP version of the LSODA library for integration into MOOSE
somulator.
* The original was aquired from
* http://www.ccl.net/cca/software/SOURCES/C/kinetics2/index.shtml and modified
by
* Heng Li <lh3lh3@gmail.com>. Heng merged several C files into one and added a
* simpler interface. [Available
here](http://lh3lh3.users.sourceforge.net/download/lsoda.c)

* The original source code came with no license or copyright
* information. Heng Li released his modification under the MIT/X11 license. I
* maintain the same license. I have removed quite a lot of text/comments from
* this library. Please refer to the standard documentation.
*
* Contact: Dilawar Singh <dilawars@ncbs.res.in>
*/

References

1. LAPACK: https://netlib.org/lapack/

2. BLAS: https://netlib.org/blas/

Coerce an object to class ev

Description

Use this function to convert a data frame to an event object.

Usage

as.ev(x, ...)

## S4 method for signature 'data.frame'
as.ev(x, keep_id = TRUE, clean = FALSE, ...)

## S4 method for signature 'ev'
as.ev(x, ...)

Arguments

Details

If CMT (or cmt) is missing from the input, it will be set to 1 in the event object.

If TIME (or time) is missing from the input, it will be set to 0 in the event object.

If EVID (or evid) is missing from the input, it will be set to 1 in the event object.

Value

An object with class ev.

Examples

data <- data.frame(AMT = 100) 

as.ev(data)

as.ev(data, clean = TRUE)

Coerce a model object to list

Description

Coerce a model object to list

Usage

## S4 method for signature 'mrgmod'
as.list(x, deep = FALSE, ...)

Arguments

Details

If deep is TRUE, then the values for trans, advan, and mindt are returned as well as a summary of internal model functions (with a call to mrgsolve:::funset()).

Value

A named list containing formatted contents from x.

Slots

• npar: number of parameters

• neq: number of compartments or differential equations

• pars: names of model parameters

• covariates: names of parameters identified as covariates

• cmt: names of model compartments

• param: the parameter list

• init: initial condition list

• omega: ⁠$OMEGA⁠ matrices, as a matlist object

• sigma: ⁠$SIGMA⁠ matrices, as a matlist object

• fixed: named list of ⁠$FIXED⁠ values

• model: model name

• project: model project directory

• soloc: directory where the model is being built

• sodll: complete path to the model shared object

• cfile: path for the model source code file

• shlib: list of compilation information

• start: simulation start time

• end: simulation end time

• delta: simulation time step

• add: additional simulation times

• capture: names of captured data items

• request: compartments requested upon simulation

• cmti: named indices for current output compartments

• capturei: named indices for current output capture

• random: names and labels of ⁠$OMEGA⁠ and ⁠$SIGMA⁠

• code: model source code from cfile

• details: model details data frame

• nm_import: a character vector listing the names of nonmem output files that were read to import estimates from a completed nonmem run

• cpp_variables: a data frame listing variables internal to the model cpp file

• atol: see solversettings

• rtol: see solversettings

• ss_atol: absolute tolerance to use when advancing to PK steady state

• ss_rtol: relative tolerance to use when advancing to PK steady state

• maxsteps: see solversettings

• hmin: see solversettings

• hmax: see solversettings

• envir: the model environment

• plugins: plugins invoked in the model

• digits: number of digits to request in simulated data

• tscale: multiplicative scalar for time in results only

• mindt: simulation output time below which there model will assume to have not advanced

• preclean: logical indicating to clean up compilation artifacts prior to compiling

• debug: print debugging information during simulation run

• verbose: print extra information during setup for model run

Examples

mod <- mrgsolve::house()
l <- as.list(mod)

Coerce an mrgsims object to list

Description

Coerce an mrgsims object to list

Usage

## S4 method for signature 'mrgsims'
as.list(x, ...)

Arguments

Coerce R objects to block or diagonal matrices

Description

These are simple functions that may be helpful to create the matrix objects that mrgsolve expects. Functions are named based on whether they create a diagonal matrix (d), a block matrix (b), or a a correlation matrix (c).

Usage

as_bmat(x, ...)

## S4 method for signature 'list'
as_bmat(x, ...)

## S4 method for signature 'numeric'
as_bmat(x, pat = "*", ...)

## S4 method for signature 'data.frame'
as_bmat(x, pat = "*", cols = NULL, ...)

## S4 method for signature 'ANY'
as_bmat(x, ...)

as_dmat(x, ...)

## S4 method for signature 'list'
as_dmat(x, ...)

## S4 method for signature 'ANY'
as_dmat(x, ...)

## S4 method for signature 'numeric'
as_dmat(x, pat = "*", ...)

## S4 method for signature 'data.frame'
as_dmat(x, pat = "*", cols = NULL, ...)

as_cmat(x, ...)

Arguments

Details

Use as_dmat() to create a diagonal matrix, as_bmat() to create a block matrix, and as_cmat() to create a block matrix where off-diagonal elements are understood to be correlations rather than covariances. as_cmat() uses as_bmat() to form the matrix and then converts off-diagonal elements to covariances before returning.

The methods for data.frame will work down the rows of the data frame and make the appropriate matrix from the data in each row. The result is a list of matrices.

Value

A numeric matrix for list and numeric methods. For data.frames, a list of matrices are returned.

See Also

bmat(), dmat(), cmat()

Examples

df <- data.frame(
  OMEGA1.1 = c(1,2),
  OMEGA2.1 = c(11,22),
  OMEGA2.2 = c(3,4),
  SIGMA1.1 = 1,
  FOO=-1
)

as_bmat(df, "OMEGA")
as_dmat(df,"SIGMA")
as_dmat(df[1,],"OMEGA")

Create a simulation data set from ev objects or data frames

Description

The goal is to take a series of event objects or data frames and combine them into a single data frame that can be passed to data_set().

Usage

as_data_set(x, ...)

## S4 method for signature 'ev'
as_data_set(x, ...)

## S4 method for signature 'data.frame'
as_data_set(x, ...)

Arguments

Details

Each event object or data frame is added to the data frame as an ID or set of IDs that are distinct from the IDs in the other event objects. Note that including ID argument to the ev() call where length(ID) is greater than one will render that set of events for all of IDs that are requested.

When determining the case for output names, the case attribute for the first ev object passed will be used to set the case for the output data.frame. In the event x is a data frame, the case of special column names (like amt/AMT or cmt/CMT) in the first data frame will be assessed and the case in the output data frame will be determined based on the relative numbers of lower or upper names.

To get a data frame with one row (event) per ID, look at expand.ev().

Value

A data frame suitable for passing into data_set(). The columns will appear in a standardized order.

See Also

expand.ev(), expand.evd(), ev(), evd(), uctran(), lctran()

Examples

a <- ev(amt = c(100,200), cmt=1, ID = seq(3))
b <- ev(amt = 300, time = 24, ID = seq(2))
c <- ev(amt = 1000, ii = 8, addl = 10, ID = seq(3))

as_data_set(a, b, c)

d <- evd(amt = 500)

as_data_set(d, a)

# Output will have upper case nmtran names
as_data_set(
  data.frame(AMT = 100, ID = 1:2), 
  data.frame(amt = 200, rate = 5, cmt = 2)
)

# Instead of this, use expand.ev
as_data_set(ev(amt = 100), ev(amt = 200), ev(amt = 300))

Create a list of designs from a data frame

Description

Create a list of designs from a data frame

Usage

as_deslist(data, descol = "ID")

Arguments

Details

The input data set must have a column with the same name as the value of descol. Other column names should be start (the time of the first observation), end (the time of the last observation), delta (the time steps to take between start and end), and add (other, ad-hoc times). Note that add might be a list-column to get a vector of times for each time grid object.

Value

The function returns a list of tgrid objects, one for each unique value found in descol.

Examples

idata <- tibble::tibble(ID=1:4, end=seq(24,96,24), delta=6,
add=list(c(122,124,135),c(111), c(99),c(88)))

idata <- dplyr::mutate(idata, GRP = ID %%2)

idata

l <- as_deslist(idata,"GRP")

l

lapply(l,stime)

lapply(as_deslist(idata, "ID"),stime)

Return the code blocks from a model specification file

Description

Return the code blocks from a model specification file

Usage

blocks(x, ...)

## S4 method for signature 'mrgmod'
blocks(x, ...)

## S4 method for signature 'character'
blocks(x, ...)

Arguments

Examples

mod <- mrgsolve::house()
mod %>% blocks
mod %>% blocks(PARAM,TABLE)

Operations with matlist objects

Description

Operations with matlist objects

Usage

## S4 method for signature 'matlist'
c(x, ..., recursive = FALSE)

Arguments

Operations with tgrid objects

Description

Operations with tgrid objects

Usage

## S4 method for signature 'tgrid'
c(x, ..., recursive = FALSE)

## S4 method for signature 'tgrids'
c(x, ..., recursive = FALSE)

## S4 method for signature 'tgrid,numeric'
e1 + e2

## S4 method for signature 'tgrid,numeric'
e1 * e2

## S4 method for signature 'tgrids,numeric'
e1 + e2

## S4 method for signature 'tgrids,numeric'
e1 * e2

Arguments

Run the model cama function

Description

Run the model cama function

Usage

cama(mod, fn = "cama", ...)

Arguments

Details

sah-mah

Select items to carry into simulated output

Description

When items named in this function are found in the input data set (either data_set() or idata_set()), they are copied into the simulated output. Special items like evid or amt or the like are not copied from the data set per se, but they are copied from datarecord objects that are created during the simulation.

Usage

carry_out(x, ...)

carry.out(x, ...)

Arguments

Details

There is also a carry_out argument to mrgsim() that can be set to accomplish the same thing as a call to carry_out in the pipeline.

carry.out and carry_out both do the same thing; using the underscore version is now preferred.

Examples

mod <- mrgsolve::house()

e <- ev(amt = 100, ii = 6, addl = 3, WT = 70, dose = amt)

out <- mod %>% ev(e) %>% carry_out(amt, dose, WT) %>% mrgsim()

head(out)

Check input data set names against model parameters

Description

Use this function to check names of input data sets against parameters that have been assigned different tags. Assignment is made in the model specification file. This is useful to alert the user to misspelled or otherwise misspecified parameter names in input data sets. See param_tags() for information on associating tags with parameters.

Usage

check_data_names(
  data,
  x,
  check_covariates = TRUE,
  check_inputs = TRUE,
  tags = NULL,
  mode = c("warn", "error", "inform"),
  silent = FALSE
)

Arguments

Details

By default, data will be checked for parameters with the covariates or input tags; these checks can be bypassed with the check_covariates and check_inputs arguments. When a parameter name is missing from data the user will be warned by default. Use mode = "error" to generate an error instead of a warning and use mode = "inform" to simply be informed. When the user has not tagged any parameters for checking, there will either be a warning (default) or an error (when mode = "error").

It is an error to request a parameter tag via the tags argument when that tag is not found in the model.

It is an error to call check_data_names when no parameters have been tagged in the model specification file (see param_tags()).

Value

A logical value is returned; TRUE if all expected parameters were found and FALSE otherwise.

See Also

param_tags()

Examples

mod <- mcode("ex-cdn", "$PARAM @input \n CL = 1, KA = 2", compile = FALSE)

param(mod)

# Coding mistake!
data <- expand.evd(amt = 100, cl = 2, KA = 5)

check_data_names(data, mod)

try(check_data_names(data, mod, mode = "error"))

check_data_names(data, mod, mode = "inform")

S4 cmt_list class

Description

S4 cmt_list class

Get the compartment number from a compartment name

Description

Get the compartment number from a compartment name

Usage

cmtn(x, ...)

## S4 method for signature 'mrgmod'
cmtn(x, tag, ...)

Arguments

Examples

mod <- mrgsolve::house()
cmtn(mod, "CENT")

Extract the code from a model

Description

This function is currently not exported, so be sure to call it with mrgsolve:::code(...).

Usage

code(x)

Arguments

Value

A character vector of model code.

Examples

mod <- mrgsolve::house()
mrgsolve:::code(mod)

# Alternative
as.list(mod)$code

Collapse the matrices of a matlist object

Description

This function is called by collapse_omega() and collapse_sigma() to convert multiple matrix blocks into a single matrix block. This "collapsing" of the matrix list is irreversible.

Usage

collapse_matrix(x, range = NULL, name = NULL)

Arguments

Value

An update matlist object (either omegalist or sigmalist).

See Also

collapse_omega(), collapse_sigma(), omat(), smat()

Examples

omega <- omat(list(dmat(1, 2), dmat(3, 4, 5)))
omega
collapse_matrix(omega)

Collapse OMEGA or SIGMA matrix lists

Description

If multiple OMEGA (or SIGMA) blocks were written into the model, these can be collapsed into a single matrix. This will not change the functionality of the model, but will alter how OMEGA (or SIGMA) are updated, usually making it easier. This "collapsing" of the matrix list is irreversible.

Usage

collapse_omega(x, range = NULL, name = NULL)

collapse_sigma(x, range = NULL, name = NULL)

Arguments

Value

A model object with updated OMEGA or SIGMA matrix lists.

See Also

collapse_matrix()

Examples

code <- '
$OMEGA 1 2 3
$OMEGA 4 5
$OMEGA 6 7 8 9
'

mod <- mcode("collapse-example", code, compile = FALSE)
revar(mod)
collapse_omega(mod) %>% omat()
collapse_omega(mod, range = c(2,3), name = "new_matrix") %>% omat()
collapse_omega(mod, range = c(2,NA), name = "new_matrix") %>% omat()

Create create character vectors

Description

Create create character vectors

Usage

cvec(x)

## S3 method for class 'character'
cvec(x)

s_(...)

Arguments

Examples

cvec("A,B,C")
s_(A,B,C)

Select and modify a data set for simulation

Description

The input data set (data_set) is a data frame that specifies observations, model events, and / or parameter values for a population of individuals.

Usage

data_set(x, data, ...)

## S4 method for signature 'mrgmod,data.frame'
data_set(
  x,
  data,
  .subset = TRUE,
  .select = TRUE,
  object = NULL,
  need = NULL,
  ...
)

## S4 method for signature 'mrgmod,ANY'
data_set(x, data, ...)

## S4 method for signature 'mrgmod,ev'
data_set(x, data, ...)

## S4 method for signature 'mrgmod,missing'
data_set(x, object, ...)

Arguments

Details

Input data sets are R data frames that can include columns with any valid name, however columns with selected names are treated specially by mrgsolve and incorporated into the simulation.

ID specifies the subject ID and is required for every input data set.

When columns have the same name as parameters (⁠$PARAM⁠ or ⁠$INPUT⁠ in the model specification file), the values in those columns will be used to update the corresponding parameter as the simulation progresses.

Input data set may include the following columns related to PK dosing events: TIME, CMT, AMT, RATE, II, ADDL, SS. Both ID and TIME are required columns in the input data set unless ⁠$PRED⁠ is in use. Lower case PK dosing column names including time, cmt, amt, rate, ii, addl, ss are also recognized. However, an error will be generated if a mix of both upper case and lower case columns in this family are found. Use the functions lctran() and uctran() to convert between upper and lower case naming for these data items.

TIME is the observation or event time, CMT is the compartment number (see init()), AMT is the dosing amount, RATE is the infusion rate, II is the dosing interval, ADDL specifies additional doses to administer, and ss is a flag indicating that the system should be advanced to a pharmacokinetic steady state prior to administering the dose. These column names operate similarly to other non-linear mixed effects modeling software.

EVID is an integer value specifying the ID of an event record. Values include:

• 0: observation

• 1: dose event, either bolus or infusion

• 2: other-type event; in mrgsolve, this functions like an observation record, but a discontinuity is created in the simulation at the time of the event (i.e., the ODE solver will stop and restart at the time of the event)

• 3: reset the system

• 4: reset the system and dose

• 8: replace the amount in a compartment

For all EVID greater than 0, a discontinuity is created in the simulation, as described for ⁠EVID 2⁠.

An error will be generated when mrgsolve detects that the data set is not sorted by time within an individual. mrgsolve does not allow time to be reset to zero on records where EVID is set to 4 (reset and dose).

Only numeric data can be brought in to the problem. Any non-numeric data columns will be dropped with warning. See numerics_only(), which is used to prepare the data set.

An error will be generated if any parameter columns in the input data set contain missing values (NA). Likewise, and error will be generated if missing values are found in the following columns: ID, time/TIME, rate/RATE.

See exdatasets for several example data sets that are provided by mrgsolve.

See Also

idata_set(), ev(), valid_data_set(), valid_idata_set(), lctran(), uctran().

Examples

mod <- mrgsolve::house()

data <- expand.ev(ID = seq(3), amt = c(10, 20))

mod %>% data_set(data, ID > 1) %>% mrgsim()

data(extran1)
head(extran1)

mod %>% data_set(extran1) %>% mrgsim()
mod %>% mrgsim(data = extran1)

Set observation designs for the simulation

Description

This function also allows you to assign different designs to different groups or individuals in a population.

Usage

design(x, deslist = list(), descol = character(0), ...)

Arguments

Details

This setup requires the use of an idata_set, with individual-level data passed in one ID per row. For each ID, specify a grouping variable in idata (descol). For each unique value of the grouping variable, make one tgrid object and pass them in order as ... or form them into a list and pass as deslist.

You must assign the idata_set before assigning the designs in the command chain (see the example below).

Examples

peak <- tgrid(0,6,0.1)
sparse <- tgrid(0,24,6)

des1 <- c(peak,sparse)
des2 <- tgrid(0,72,4)


data <- expand.ev(ID = 1:10, amt=c(100,300))
data$GRP <- data$amt/100

idata <- data[,c("ID", "amt")]

mod <- mrgsolve::house()

mod %>%
  omat(dmat(1,1,1,1)) %>%
  carry_out(GRP) %>%
  idata_set(idata) %>%
  design(list(des1, des2),"amt") %>%
  data_set(data) %>%
  mrgsim() %>% 
  plot(RESP~time|GRP)

Extract model details

Description

Extract model details

Usage

details(x, complete = FALSE, values = TRUE, ...)

Arguments

Details

This function is not exported. You will have to call it with mrgsolve:::details().

Examples

mod <- mrgsolve::house()

mrgsolve:::details(mod)

Re-evaluate the code in the ENV block

Description

The ⁠$ENV⁠ block is a block of R code that can realize any sort of R object that might be used in running a model.

Usage

env_eval(x, seed = NULL)

Arguments

See Also

env_get(), env_ls()

Return model environment

Description

Return model environment

Usage

env_get(x, tolist = TRUE)

env_get_env(x)

Arguments

List objects in the model environment

Description

Each model keeps an internal environment that allows the user to carry any R object along. Objects are coded in ⁠$ENV⁠.

Usage

env_ls(x, ...)

Arguments

Update objects in model environment

Description

Update objects in model environment

Usage

env_update(.x, ..., .dots = list())

Arguments

Event objects for simulating PK and other interventions

Description

An event object specifies dosing or other interventions that get implemented during simulation. Event objects do similar things as data_set, but simpler and easier to create.

Usage

ev(x, ...)

## S4 method for signature 'mrgmod'
ev(x, object = NULL, ...)

## S4 method for signature 'missing'
ev(
  time = 0,
  amt = 0,
  evid = 1,
  cmt = 1,
  ID = numeric(0),
  replicate = TRUE,
  until = NULL,
  tinf = NULL,
  realize_addl = FALSE,
  ...
)

## S4 method for signature 'ev'
ev(x, realize_addl = FALSE, ...)

Arguments

Details

• Required items in events objects include time, amt, evid and cmt.

• If not supplied, evid is assumed to be 1.

• If not supplied, cmt is assumed to be 1.

• If not supplied, time is assumed to be 0.

• If amt is not supplied, an error will be generated.

• If total is supplied, then addl will be set to total-1.

• Other items can include ii, ss, and addl (see data_set for details on all of these items).

• ID may be specified as a vector.

• If replicate is TRUE (default), then the events regimen is replicated for each ID; otherwise, the number of event rows must match the number of IDs entered.

Value

ev() returns an event object.

See Also

evd(), ev_rep(), ev_days(), ev_repeat(), ev_assign(), ev_seq(), mutate.ev(), as.ev(), as.evd(), ev_methods.

Examples

mod <- mrgsolve::house()

mod <- mod %>% ev(amt = 1000, time = 0, cmt = 1)

loading <- ev(time = 0, cmt = 1, amt = 1000)

maint <- ev(time = 12, cmt = 1, amt = 500, ii = 12, addl = 10)

c(loading, maint)

reduced_load <- dplyr::mutate(loading, amt = 750)

# Three additional doses in this case
e <- ev(amt = 100, ii = 4*7, until = 16*7)
e
# Last dose is given at 84
realize_addl(e)

# Four additional doses with last at 112 in this case
e <- ev(amt = 100, ii = 4*7, until = 16*7 + 0.001)
realize_addl(e)

S4 events class

Description

S4 events class

Slots

data

a data frame of events

case

indicates how to handle column naming upon coerce to data.frame

Replicate a list of events into a data set

Description

Replicate a list of events into a data set

Usage

ev_assign(l, idata, evgroup, join = FALSE)

assign_ev(...)

Arguments

Details

ev_assign() connects events in a list passed in as the l argument to values in the data set identified in the evgroup argument. For making assignments, the unique values in the evgroup column are first sorted so that the first sorted unique value in evgroup is assigned to the first event in l, the second sorted value in evgroup column is assigned to the second event in l, and so on. This is a change from previous behavior, which did not sort the unique values in evgroup prior to making the assignments.

Examples

ev1 <- ev(amt = 100)
ev2 <- ev(amt = 300, rate = 100, ii = 12, addl = 10)

idata <- data.frame(ID = seq(10)) 
idata$arm <- 1+(idata$ID %%2)

ev_assign(list(ev1, ev2), idata, "arm", join = TRUE)

Schedule dosing events on days of the week

Description

This function lets you schedule doses on specific days of the week, allowing you to create dosing regimens on Monday/Wednesday/Friday, or Tuesday/Thursday, or every other day (however you want to define that) etc.

Usage

ev_days(
  ev = NULL,
  days = "",
  addl = 0,
  ii = 168,
  unit = c("hours", "days"),
  ...
)

Arguments

Details

Valid names of the week are:

• m for Monday

• t for Tuesday

• w for Wednesday

• th for Thursday

• f for Friday

• sa for Saturday

• s for Sunday

The whole purpose of this function is to schedule doses on specific days of the week, in a repeating weekly schedule. Please do use caution when changing ii from its default value.

Examples

# Monday, Wednesday, Friday x 4 weeks
e1 <- ev(amt = 100)
ev_days(e1, days="m,w,f", addl = 3)

# 50 mg Tuesdays, 100 mg Thursdays x 6 months
e2 <- ev(amt = 50)
ev_days(t = e2, th = e1, addl = 23)

Various methods for event objects

Description

Various methods for event objects

Usage

## S3 method for class 'ev'
names(x)

## S3 method for class 'ev'
dim(x)

## S3 method for class 'ev'
as.matrix(x, ...)

## S3 method for class 'ev'
as.data.frame(x, row.names = NULL, optional = FALSE, add_ID = NULL, ...)

## S4 method for signature 'ev'
show(object)

Arguments

Examples

e <- ev(amt = 100)

names(e)

as.data.frame(e)

dim(e)

nrow(e)

Operations for ev objects

Description

Operations for ev objects

Usage

## S4 method for signature 'ev,ev'
e1 + e2

e1 %then% e2

## S4 method for signature 'ev,ev'
e1 %then% e2

## S4 method for signature 'ev,numeric'
e1 + e2

## S4 method for signature 'ev'
c(x, ..., recursive = TRUE)

Arguments

Details

All operations involving mrgmod objects have been deprecated.

Replicate an event object

Description

An event sequence can be replicated a certain number of times in a certain number of IDs.

Usage

ev_rep(x, ID = 1, n = NULL, wait = 0, as.ev = FALSE, id = NULL)

Arguments

Value

A single data.frame or event object as determined by the value of as.ev().

See Also

ev_repeat()

Examples

e1 <- c(ev(amt=100), ev(amt=200, ii=24, addl=2, time=72))

ev_rep(e1, 1:5)

Repeat a block of dosing events

Description

Repeat a block of dosing events

Usage

ev_repeat(x, n, wait = 0, as.ev = FALSE)

Arguments

Value

See as.ev argument.

Examples

e1 <- ev(amt = 100, ii = 24, addl = 20)
e4 <- ev_repeat(e1, n = 4, wait = 168)
mod <- mrgsolve::house()
out <- mrgsim(mod, events = e4, end = 3200)
plot(out, "CP")

Create intervention objects from Rx input

Description

See details below for Rx specification. Actual parsing is done by parse_rx(); this function can be used to debug Rx inputs.

Usage

ev_rx(x, y, ...)

## S4 method for signature 'mrgmod,character'
ev_rx(x, y, ...)

## S4 method for signature 'character,missing'
ev_rx(x, df = FALSE, ...)

parse_rx(x)

Arguments

Value

The method dispatched on model object (mrgmod) returns another model object. The character method returns an event object. The parse_rx function return a list named with arguments for the event object constructor ev().

Rx specification

• The dose is found at the start of the string by sequential digits; this may be integer, decimal, or specified in scientific notation

• Use ⁠in⁠ to identify the dosing compartment number; must be integer

• Use q to identify the dosing interval; must be integer or decimal number (but not scientific notation)

• Use over to indicate an infusion and its duration; integer or decimal number

• Use x to indicate total number of doses; must be integer

• Use then or ⁠,⁠ to separate dosing periods

• Use after to insert a lag in the start of a period; integer or decimal number (but not scientific notation)

• Use & to implement multiple doses at the same time

Examples

# example("ev_rx")

ev_rx("100")

ev_rx("100 in 2")

ev_rx("100 q12 x 3")

ev_rx("100 over 2")

ev_rx("100 q 24 x 3 then 50 q12 x 2")

ev_rx("100 then 50 q 24 after 12")

ev_rx("100.2E-2 q4")

ev_rx("100 over 2.23")

ev_rx("100 q 12 x 3")

ev_rx("100 in 1 & 200 in 2") 

parse_rx("100 mg q 24 then 200 mg q12")

Schedule a series of event objects

Description

Use this function when you want to schedule two or more event objects in time according the dosing interval (ii) and additional doses (addl).

Usage

ev_seq(..., ID = NULL, .dots = NULL, id = NULL)

## S3 method for class 'ev'
seq(...)

Arguments

Details

Use the generic seq() when the first argument is an event object. If a waiting period (wait or ii) is the first event, you will need to use ev_seq(). When an event object has multiple rows, the end time for that sequence is taken to be one dosing interval after the event that takes place on the last row of the event object.

The doses for the next event line start after all of the doses from the previous event line plus one dosing interval from the previous event line (see Examples).

When numerics named wait or ii are mixed in with the event objects, a period with no dosing activity is incorporated into the sequence, between the adjacent dosing event objects. wait and ii accomplish a similar result, but differ by the starting point for the inactive period.

• Use wait to schedule the next dose relative to the end of the dosing interval for the previous dose.

• Use ii to schedule the next dose relative to the time of the the previous dose.

So wait acts like similar to an event object, by starting the waiting period from one dosing interval after the last dose while ii starts the waiting period from the time of the last dose itself. Both wait and ii can accomplish identical behavior depending on whether the last dosing interval is included (or not) in the value. Values for wait or ii can be negative.

NOTE: .ii had been available historically as an undocumented feature. Starting with mrgsolve version ⁠0.11.3⁠, the argument will be called ii. For now, both ii and .ii will be accepted but you will get a deprecation warning if you use .ii. Please use ii instead.

Values for time in any event object act like a prefix time spacer wherever that event occurs in the event sequence (see Examples).

Value

A single event object sorted by time.

Examples

e1 <- ev(amt = 100, ii = 12, addl = 1)

e2 <- ev(amt = 200)

seq(e1, e2)

seq(e1, ii = 8, e2)

seq(e1, wait = 8, e2)

seq(e1, ii = 8, e2, ID = seq(10))

ev_seq(ii = 12, e1, ii = 120, e2, ii = 120, e1)

seq(ev(amt = 100, ii = 12), ev(time = 8, amt = 200))

Create an event object with data-like names

Description

This function calls ev() to create an event object and then sets the case attribute so that it renders nmtran data names in upper case. An object created with evd() can be used in the same way as an object created with ev().

Usage

evd(x, ...)

## S4 method for signature 'mrgmod'
evd(x, ...)

## S4 method for signature 'missing'
evd(x, ...)

## S4 method for signature 'ev'
evd(x, ...)

as.evd(x)

Arguments

Details

Note that evd isn't a separate class; it is just an ev object with a specific case attribute. See examples which illustrate the difference.

See Also

ev(), lctran(), uctran()

Examples

a <- evd(amt = 100)
b <- ev(amt = 300)
a
as.data.frame(a)
as_data_set(a, b)
as_data_set(b, a)
as.data.frame(seq(a, b))

Example input data sets

Description

Example input data sets

Usage

data(exidata)

data(extran1)

data(extran2)

data(extran3)

data(exTheoph)

data(exBoot)

Details

• exidata holds individual-level parameters and other data items, one per row

• extran1 is a "condensed" data set

• extran2 is a full dataset

• extran3 is a full dataset with parameters

• exTheoph is the theophylline data set, ready for input into mrgsolve

• exBoot a set of bootstrap parameter estimates

Examples

mod <- mrgsolve::house() %>% update(end=240) %>% Req(CP)

## Full data set
data(exTheoph)
out <- mod %>% data_set(exTheoph) %>% mrgsim
out
plot(out)

## Condensed: mrgsolve fills in the observations
data(extran1)
out <- mod %>% data_set(extran1) %>% mrgsim
out
plot(out)

## Add a parameter to the data set
stopifnot(require(dplyr))
data <- extran1 %>% distinct(ID) %>% select(ID) %>%
  mutate(CL=exp(log(1.5) + rnorm(nrow(.), 0,sqrt(0.1)))) %>%
  left_join(extran1,.)
  
data

out <- mod %>% data_set(data) %>% carry_out(CL) %>%  mrgsim
out
plot(out)

## idata
data(exidata)
out <- mod %>% idata_set(exidata) %>% ev(amt=100,ii=24,addl=10) %>% mrgsim
plot(out, CP~time|ID)

Create template data sets for simulation

Description

These functions expand all combinations of arguments using expand.grid(). expand.idata() generates an idata set; the others generate a full data set. The result always has only one row for one individual. Use expand.evd() or evd_expand() to render NMTRAN names (e.g. AMT or CMT) in upper case.

Usage

expand.idata(...)

expand.ev(...)

expand.evd(...)

ev_expand(...)

evd_expand(...)

Arguments

Details

An ID column is added as if not supplied by the user. In the output data frame, ID is always re-written as the row number.

For expand.ev(), defaults also added include cmt = 1, time = 0, evid = 1. If total is included, then addl is derived as total-1. If tinf is included, then an infusion rate is derived for row where tinf is greater than zero.

ev_expand() is a synonym for expand.ev() and evd_expand() is a synonym for expand.evd().

Value

A data frame containing one row for each combination of the items passed in .... The result always has ID set to the row number.

Examples

idata <- expand.idata(CL = c(1,2,3), VC = c(10,20,30))

doses <- expand.ev(amt = c(300,100), ii = c(12,24), cmt = 1)

infusion <- expand.ev(amt = 100, tinf = 2)

Insert observations into a data set

Description

Insert observations into a data set

Usage

expand_observations(data, times, unique = FALSE, obs_pos = -1L)

Arguments

Details

Non-numeric columns will be dropped with a warning.

Value

A data frame with additional rows for added observation records.

Examples

data <- expand.ev(amt = c(100, 200, 300))

expand_observations(data, times = seq(0, 48, 2))

Show model specification and C++ files

Description

Show model specification and C++ files

Usage

file_show(x, spec = TRUE, source = TRUE, ...)

Arguments

Return a pre-compiled, PK/PD model

Description

This model is used in a lot of package tests, but it can be useful to support user experimentation as well.

Usage

house(...)

Arguments

Value

A packmod object, ready to simulate.

Examples

mod <- mrgsolve::house()

see(mod)

mod %>% ev(amt = 100) %>% mrgsim() %>% plot()

Select and modify a idata set for simulation

Description

The individual data set (idata_set) is a data frame with one row for each individual in a population, specifying parameters and other individual-level data.

Usage

idata_set(x, data, ...)

## S4 method for signature 'mrgmod,data.frame'
idata_set(
  x,
  data,
  .subset = TRUE,
  .select = TRUE,
  object = NULL,
  need = NULL,
  ...
)

## S4 method for signature 'mrgmod,ANY'
idata_set(x, data, ...)

## S4 method for signature 'mrgmod,missing'
idata_set(x, object, ...)

Arguments

Details

The idata_set is a data frame that specifies individual-level data for the problem. An ID column is required and there can be no more than one row in the data frame for each individual.

In most cases, the columns in the idata_set have the same names as parameters in the param() list. When this is the case, the parameter set is updated as the simulation proceeds once at the start of each individual. The idata_set can also be used to set initial conditions for each individual: for a compartment called CMT, make a column in idata_set called CMT_0 and make the value the desired initial value for that compartment. Note that this initial condition will be overridden if you also set the CMT_0 in ⁠$MAIN⁠ (⁠$PK⁠).

The most common application of idata_set is to specify a population or batch of simulations to do. We commonly use idata_set with an event object (see ev()). In that case, the event gets applied to each individual in the idata_set.

It is also possible to provide both a data_set and a idata_set. In this case, the idata_set is used as a parameter lookup for IDs found in the data_set. Remember in this case, it is the data_set (not the idata_set) that determines the number of individuals in the simulation.

An error will be generated if any parameter columns in the input idata set contain NA.

See Also

data_set(), ev()

Examples

mod <- mrgsolve::house()

data(exidata)

exidata

mod %>% 
  idata_set(exidata, ID <= 2) %>% 
  ev(amt = 100) %>%
  mrgsim() %>% 
  plot()

mod %>% 
  idata_set(exidata) %>% 
  ev(amt = 100) %>%
  mrgsim()

mod %>% ev(amt = 100) %>% mrgsim(idata=exidata) 

Methods for working with the model compartment list

Description

Calling init() with the model object as the first argument will return the model initial conditions as a numericlist object. See numericlist for methods to deal with cmt_list objects.

Usage

init(.x, ...)

## S4 method for signature 'mrgmod'
init(.x, .y = list(), ..., .pat = "*")

## S4 method for signature 'mrgsims'
init(.x, ...)

## S4 method for signature 'missing'
init(.x, ...)

## S4 method for signature 'list'
init(.x, ...)

## S4 method for signature 'ANY'
init(.x, ...)

Arguments

Details

Can be used to either get a compartment list object from a mrgmod model object or to update the compartment initial conditions in a model object. For both uses, the return value is a cmt_list object. For the former use, init() is usually called to print the compartment initial conditions to the screen, but the cmt_list object can also be coerced to a list or numeric R object.

Value

An object of class cmt_list (see numericlist).

Examples

## example("init")
mod <- mrgsolve::house()

init(mod)

init(mod, .pat="^C") ## may be useful for large models

class(init(mod))

init(mod)$CENT

as.list(init(mod))

as.data.frame(init(mod))

Check whether all required parameters needed in a model are present in an object

Description

This function has largely been superseded by check_data_names().

Usage

inventory(x, obj, ..., .strict = FALSE)

Arguments

Details

If parameter requirements are not explicitly stated, the requirement defaults to all parameter names in x. Note that, by default, the inventory is not .strict unless the user explicitly states the parameter requirement. That is, if parameter requirements are explicitly stated, .strict will be set to TRUE if a value .strict was not passed in the call.

Value

x is returned invisibly.

See Also

check_data_names()

Examples

## Not run: 
  inventory(mod, idata, CL:V) # parameters defined, inclusively, CL through Volume 
  inventory(mod, idata, everything()) # all parameters
  inventory(mod, idata, contains("OCC")) # all parameters containing OCC
  inventory(mod, idata, -F) # all parameters except F

## End(Not run)

Check if an object is a model object

Description

The function checks to see if the object is either mrgmod or packmod.

Usage

is.mrgmod(x)

Arguments

Value

TRUE if the object inherits from either mrgmod or packmod class.

Examples

mod <- mrgsolve::house()
is.mrgmod(mod)

Check if an object is mrgsims output

Description

Check if an object is mrgsims output

Usage

is.mrgsims(x)

Arguments

Value

TRUE if x inherits mrgsims.

Run sensitivity analysis on model settings

Description

Knobs can be parameter values or PK dosing items (e.g. amt). By design, all combinations of specified knob/values are simulated.

Usage

knobs(x, y, ...)

## S4 method for signature 'mrgmod,missing'
knobs(x, y, ...)

## S4 method for signature 'mrgmod,batch_mrgsims'
knobs(x, y, ...)

## S4 method for signature 'batch_mrgsims'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S4 method for signature 'batch_mrgsims,ANY'
knobs(x, y, ...)

## S4 method for signature 'batch_mrgsims'
show(object)

Arguments

Details

Valid knob names include: any parameter name (in param(mod)), time variables (start, end, delta), PK dosing items (amt, ii, rate, and others ...), and solver settings (atol, hmax, etc...).

Value

An object of class batch_mrgsims. Most methods for mrgsims objects also work on batch_mrgsims object.

Examples

## example("knobs")

mod <- mrgsolve::house(end=72)

events <- ev(amt=1000, cmt=1, addl=3, ii=12)

out <- mod %>% ev(events) %>% knobs(CL=c(1,2,3))
plot(out)

out

out <- mod %>% ev(events) %>% knobs(CL=c(1,2,3), VC=c(5,20,50))
plot(out)
plot(out,CP~.)
plot(out, CP~time|VC, groups=CL, lty=2)

out <- knobs(mod, amt=c(100,300,500), cmt=1)
plot(out)

out <- mod %>% knobs(amt=c(100,300), CL=c(1,3), VC=c(5,20), cmt=1)
plot(out)
plot(out, CP~.)

out <- knobs(mod, CL=c(1,2,3))
out

out <- knobs(mod, CL=c(1,2,3))
out

Change the case of nmtran-like data items

Description

Previous data set requirements included lower case names for data items like AMT and EVID. Lower case is no longer required. However, it is still a requirement that nmtran like data column names are either all lower case or all upper case.

Usage

lctran(data, ...)

## S3 method for class 'data.frame'
lctran(data, warn = TRUE, ...)

## S3 method for class 'ev'
lctran(data, ...)

uctran(data, ...)

## S3 method for class 'data.frame'
uctran(data, warn = TRUE, ...)

## S3 method for class 'ev'
uctran(data, ...)

Arguments

Details

Columns that will be renamed with lower or upper case versions:

• AMT / amt

• II / ii

• SS / ss

• CMT / cmt

• ADDL / addl

• RATE / rate

• EVID / evid

• TIME / time

If both lower and upper case versions of the name are present in the data frame, no changes will be made.

Value

A data frame or event object, with column names possibly converted to upper or lower case.

Examples

data <- data.frame(TIME = 0, AMT = 5, II = 24, addl = 2, WT = 80)
lctran(data)

data <- data.frame(TIME = 0, AMT = 5, II = 24, addl = 2, wt = 80)
uctran(data)

ev <- evd(amt = 100, evid = 3)
uctran(ev)

# warning
data <- data.frame(TIME = 1, time = 2, CMT = 5)
lctran(data)

Load the model shared object

Description

Once the model is compiled, the model object can be used to re-load the model shared object (the compiled code underlying the mode) when the simulation is to be done in a different R process.

Usage

loadso(x, ...)

## S3 method for class 'mrgmod'
loadso(x, ...)

Arguments

Details

The loadso function most frequently needs to be used when parallelizing simulations across worker nodes. The model can be run after calling loadso, without requiring that it is re-compiled on worker nodes. It is likely required that the model is built (and the shared object stored) in a local directory off of the working R directory (see the second example).

Value

The model object (invisibly).

Examples

## Not run:  
  mod <- mread("pk1", modlib())
  loadso(mod)
  
  mod2 <- mread("pk2", modlib(), soloc = "build")
  loadso(mod2)

## End(Not run)

Create a square numeric matrix from the lower-triangular elements

Description

Create a square numeric matrix from the lower-triangular elements

Usage

lower2matrix(x, context = NULL)

Arguments

Value

a square symmetric numeric matrix with column names

Methods for working with matrix-list objects

Description

Methods for working with matrix-list objects

Usage

## S4 method for signature 'matlist'
as.list(x, detailed = FALSE, ...)

## S4 method for signature 'matlist'
as.matrix(x, ...)

## S3 method for class 'matlist'
names(x)

## S3 method for class 'matlist'
length(x)

## S4 method for signature 'matlist'
labels(object, ...)

## S4 method for signature 'matlist'
dim(x)

## S4 method for signature 'matlist'
nrow(x)

## S4 method for signature 'matlist'
show(object)

Arguments

S4 class matlist

Description

S4 class matlist

Create matrices from vector input

Description

These functions are simple utilities for creating diagonal, block or correlation matrices.

Usage

bmat(..., correlation = FALSE, digits = -1)

cmat(..., digits = -1)

dmat(...)

Arguments

Details

bmat() makes a block matrix. cmat() makes a correlation matrix. dmat() makes a diagonal matrix.

Value

A matrix.

See Also

as_bmat(), as_dmat()

Examples

dmat(1,2,3)/10

bmat(0.5,0.01,0.2)

cmat(0.5, 0.87,0.2)

Set RNG to use L'Ecuyer-CMRG

Description

Set RNG to use L'Ecuyer-CMRG

Usage

mcRNG()

Write, compile, and load model code

Description

This is a convenience function that ultimately calls mread(). Model code is written to a file and read back in using mread().

Usage

mcode(model, code, project = getOption("mrgsolve.project", tempdir()), ...)

mcode_cache(
  model,
  code,
  project = getOption("mrgsolve.project", tempdir()),
  ...
)

Arguments

Details

Note that the arguments are in slightly different order than mread(). The default project is tempdir().

See the mread() help topic for discussion about caching compilation results with mcode_cache().

See Also

mread(), mread_cache()

Examples

## Not run:  
code <- '
$CMT DEPOT CENT
$PKMODEL ncmt=1, depot=TRUE
$MAIN
double CL = 1;
double V = 20;
double KA = 1;
'

mod <- mcode("example", code, compile = FALSE)

## End(Not run)

Merge two lists

Description

Merge two lists

Usage

## S3 method for class 'list'
merge(x, y, ..., open = FALSE, warn = TRUE, context = "object", wild = "...")

Arguments

Details

Wild-card names (wild) are always retained in x and are brought along from y only when open.

Return the model object

Description

Return the model object

Usage

mod(x, ...)

## S4 method for signature 'mrgsims'
mod(x, ...)

Arguments

Create a matrix

Description

Create a matrix

Usage

modMATRIX(
  x,
  use = TRUE,
  block = FALSE,
  correlation = FALSE,
  digits = -1,
  context = "matlist",
  ...
)

Arguments

Examples

modMATRIX("1 2.2 333")
modMATRIX("1 1.1 2.2", block=TRUE)
modMATRIX("23 234 234 5234", use=FALSE)

ans <- modMATRIX("1.1 0.657 2.2", correlation=TRUE, block=TRUE)
ans
cov2cor(ans)

Parse model specification text

Description

Parse model specification text

Usage

modelparse(txt, split = FALSE, drop_blank = TRUE, comment_re = c("//", "##"))

modelparse_rmd(txt, split = FALSE, drop_blank = TRUE, comment_re = "//")

Arguments

Examples

file <- file.path(modlib(), "pk1.cpp")

modelparse(readLines(file))

Internal model library

Description

Pre-coded models are included in the mrgsolve installation; these can be compiled and loaded with modlib(). These models are usually most useful for exploratory simulation or learning mrgsolve. Production simulation work is typically accomplished by a custom-coded model.

Usage

modlib(model = NULL, ..., list = FALSE)

Arguments

Details

See modlib_details, modlib_pk, modlib_pkpd, modlib_tmdd, modlib_viral for details.

Call modlib("<modelname>") to compile and load a mode from the library.

Call modlib(list=TRUE) to list available models. Once the model is loaded (see examples below), call as.list(mod)$code to extract model code and equations.

Examples

## Not run: 
mod <- mread("pk1cmt", modlib())
mod <- mread("pk2cmt", modlib()) 
mod <- mread("pk3cmt", modlib()) 
mod <- mread("pk1",    modlib())
mod <- mread("pk2",    modlib())
mod <- mread("popex",  modlib())
mod <- mread("irm1",   modlib()) 
mod <- mread("irm2",   modlib()) 
mod <- mread("irm3",   modlib()) 
mod <- mread("irm4",   modlib())
mod <- mread("emax",   modlib())
mod <- mread("effect", modlib())
mod <- mread("tmdd",   modlib())
mod <- mread("viral1", modlib())
mod <- mread("viral2", modlib())
mod <- mread("pred1",  modlib())
mod <- mread("pbpk",   modlib())
mod <- mread("1005",   modlib())  # embedded NONMEM result
mod <- mread("nm-like", modlib()) # model with nonmem-like syntax
mod <- mread("evtools", modlib())

as.list(mod)$code

## End(Not run)

modlib: PK/PD Model parameters, compartments, and output variables

Description

modlib: PK/PD Model parameters, compartments, and output variables

Compartments

• EV1, EV2: extravascular dosing compartments

• CENT: central PK compartment

• PERIPH: peripheral PK compartment

• PERIPH2: peripheral PK compartment 2

• RESP: response PD compartment (irm models)

Output variables

• CP: concentration in the central compartment (CENT/VC)

• RESP: response (emax model)

PK parameters

• KA1, KA2: first order absorption rate constants from first and second extravascular compartment (1/time)

• CL: clearance (volume/time)

• VC: volume of distribution, central compartment (volume)

• VP: volume of distribution, peripheral compartment (volume)

• VP2: volume of distribution, peripheral compartment 2 (volume)

• Q: intercompartmental clearance (volume/time)

• Q2: intercompartmental clearance 2 (volume/time)

• VMAX: maximum rate, nonlinear process (mass/time)

• KM: Michaelis constant (mass/volume)

• K10: elimination rate constant (1/time); CL/VC

• K12: rate constant for transfer to peripheral compartment from central (1/time); Q/VC

• K21: rate constant for transfer to central compartment from peripheral (1/time); Q/VP

PD parameters

• E0: baseline effect (emax model)

• EMAX, IMAX: maximum effect (response)

• EC50, IC50: concentration producing 50 percent of effect (mass/volume)

• KIN: zero-order response production rate (irm models) (response/time)

• KOUT: first-order response elimination rate (irm models) (1/time)

• n: sigmoidicity factor

• KEO: rate constant for transfer to effect compartment (1/time)

modlib: Pharmacokinetic models

Description

modlib: Pharmacokinetic models

Arguments

Details

See modlib_details for more detailed descriptions of parameters and compartments.

The pk1cmt model is parameterized in terms of CL, VC, KA1 and KA2 and uses compartments EV1, EV2, and CENT. The pk2cmt model adds a PERIPH compartment and parameters Q and VP to that of the one-compartment model. Likewise, the three-compartment model (pk3cmt) adds PERIPH2 and parameters Q2 and VP2 to that of the two-compartment models. All pk models also have parameters VMAX (defaulting to zero, no non-linear clearance) and KM.

Value

an object of class packmod

Model description

All pk models have two extravascular dosing compartments and potential for linear and nonlinear clearance.

• pk1cmt: one compartment pk model using ODEs

• pk2cmt: two compartment pk model using ODEs

• pk3cmt: three compartment pk model using ODEs

• pk1: one compartment pk model in closed-form

• pk2: two compartment pk model in closed-form

• popex: a simple population pk model

modlib: Pharmacokinetic / pharmacodynamic models

Description

modlib: Pharmacokinetic / pharmacodynamic models

Details

See modlib_details for more detailed descriptions of parameters and compartments.

All PK/PD models include 2-compartment PK model with absorption from 2 extravascular compartments and linear + nonlinear clearance. The PK models are parameterized with CL, VC, Q, VMAX, KM, KA1 and KA2 and implement compartments EV1, EV2, CENT, PERIPH . The indirect response models have compartment RESP and the emax model has output variable RESP. PD parameters include KIN, KOUT, IC50, EC50, IMAX, EMAX, E0, and n.

Also, once the model is loaded, use see method for mrgmod to view the model code.

Model description

• irm1 inhibition of response production

• irm2 inhibition of response loss

• irm3 stimulation of response production

• irm4 stimulation of response loss

• pd_effect effect compartment model

• emax sigmoid emax model

modlib: Target mediated disposition model

Description

modlib: Target mediated disposition model

Arguments

Parameters

• KEL: elimination rate constant

• KTP: tissue to plasma rate constant

• KPT: plasma to tissue rate constant

• VC: volume of distribution

• KA1, KA2: absorption rate constants

• KINT: internalization rate constant

• KON: association rate constant

• KOFF: dissociation rate constant

• KSYN: target synthesis rate

• KDEG: target degredation rate constant

Compartments

• CENT: unbound drug in central compartment

• TISS: unbound drug in tissue compartment

• REC: concentration of target

• RC: concentration of drug-target complex

• EV1, EV2: extravascular dosing compartments

Output variables

• CP: unbound drug in the central compartment

• TOTAL: total concentration of target (complexed and uncomplexed)

modlib: HCV viral dynamics models

Description

modlib: HCV viral dynamics models

Models

• viral1: viral dynamics model with single HCV species

• viral2: viral dynamics model with wild-type and mutant HCV species

Parameters

• s: new hepatocyte synthesis rate (cells/ml/day)

• d: hepatocyte death rate constant (1/day)

• p: viral production rate constant (copies/cell/day)

• beta: new infection rate constant (ml/copy/day)

• delta: infected cell death rate constant (1/day)

• c: viral clearance rate constant (1/day)

• fit: mutant virus fitness

• N: non-target hepatocytes

• mu: forward mutation rate

• Tmax: maximum number of target hepatocytes (cells/ml)

• rho: maximum hepatocyte regeneration rate (1/day)

Compartments

• T: uninfected target hepatocytes (cells/ml)

• I: productively infected hepatocytes (cells/ml)

• V: hepatitis C virus (copies/ml)

• IM: mutant infected hepatocytes (cells/ml)

• VM: mutant hepatitis C virus (copies/ml)

• expos: exposure metric to drive pharmacodynamic model

Read a model specification file

Description

mread() reads and parses the mrgsolve model specification file, builds the model, and returns a model object for simulation. mread_cache() does the same, but caches the compilation result for later use. mread_file() can be used for convenience, taking the model file name as the first argument.

Usage

mread(
  model,
  project = getOption("mrgsolve.project", getwd()),
  code = NULL,
  file = NULL,
  udll = TRUE,
  ignore.stdout = TRUE,
  raw = FALSE,
  compile = TRUE,
  audit = TRUE,
  quiet = getOption("mrgsolve_mread_quiet", FALSE),
  check.bounds = FALSE,
  warn = TRUE,
  soloc = getOption("mrgsolve.soloc", tempdir()),
  capture = NULL,
  preclean = FALSE,
  recover = FALSE,
  ...
)

mread_cache(
  model = NULL,
  project = getOption("mrgsolve.project", getwd()),
  file = paste0(model, ".cpp"),
  code = NULL,
  soloc = getOption("mrgsolve.soloc", tempdir()),
  quiet = FALSE,
  preclean = FALSE,
  capture = NULL,
  ...
)

mread_file(file, ...)

Arguments

Details

The model argument is required. For typical use, the file argument is omitted and the value for file is generated from the value for model. To determine the source file name, mrgsolve will look for a file extension in model. A file extension is assumed when it finds a period followed by one to three alpha-numeric characters at the end of the string (e.g. mymodel.txt but not my.model). If no file extension is found, the extension .cpp is assumed (e.g. file is ⁠<model-name>.cpp⁠). If a file extension is found, file is ⁠<model-name>⁠.

Best practice is to avoid using . in model unless you are using model to point to the model specification file name. Otherwise, use mread_file().

Use the soloc argument to specify a directory location for building the model. This is the location where the model shared object will be stored on disk. The default is a temporary directory, so compilation artifacts are lost when R restarts when the default is used. Changing soloc to a persistent directory location will preserve those artifacts across R restarts. Also, if simulation from a single model is being done in separate processes on separate compute nodes, it might be necessary to store these compilation artifacts in a local directory to make them accessible to the different nodes. If the soloc directory does not exist, mread() will attempt to create it.

Similarly, using mread_cache() will cache results in the temporary directory and the cache cannot be accessed after the R process is restarted.

Model Library

mrgsolve comes bundled with several pre-coded PK, PK/PD, and other systems models that are accessible via the mread() interface.

Models available in the library include:

• PK models: pk1cmt, pk2cmt, pk3cmt, pk1, pk2, popex, tmdd

• PKPD models: irm1, irm2, irm3, irm4, emax, effect

• Other models: viral1, viral2

When the library model is accessed, mrgsolve will compile and load the model as you would for any other model. It is only necessary to reference the correct model name and point the project argument to the mrgsolve model library location via modlib().

For more details, see modlib_pk, modlib_pkpd, modlib_tmdd, modlib_viral, and modlib_details for more information about the state variables and parameters in each model.

See Also

mcode(), mcode_cache()

Examples

## Not run: 
code <- '
$PARAM CL = 1, VC = 5
$CMT CENT
$ODE dxdt_CENT = -(CL/VC)*CENT;
'

mod <- mcode("ex_mread", code)
mod

mod %>% init(CENT=1000) %>% mrgsim() %>% plot()

mod <- mread("irm3", modlib())

# if the model is in the file mymodel.cpp
mod <- mread("mymodel")

# if the model is in the file mymodel.txt
mod <- mread(file = "mymodel.txt")

or

mod <- mread_file("mymodel.txt")

## End(Not run)

Read a model from yaml format

Description

Read back models written to file using mwrite_yaml(). Function yaml_to_cpp() is also provided to convert the yaml file to mrgsolve cpp file format.

Usage

mread_yaml(
  file,
  model = basename(file),
  project = tempdir(),
  update = FALSE,
  ...
)

yaml_to_cpp(file, model = basename(file), project = getwd(), update = TRUE)

Arguments

Details

Note that yaml_to_cpp() by default writes model settings into the cpp file. mread_yaml() does not write model settings into the file but rather update the model object directly with data read back from the yaml file.

Value

A model object.

See Also

mwrite_yaml()

Examples

mod <- house()

temp <- tempfile(fileext = ".yaml")

mwrite_yaml(mod, file = temp)

# Note: this model is not compiled
mod <- mread_yaml(temp, model = "new-house", compile = FALSE)
mod

cppfile <- yaml_to_cpp(temp, project = tempdir())

readLines(cppfile)

S4 class for mrgsolve model object

Description

S4 class for mrgsolve model object

Slots

model

model name <character>

modfile

source model specification file name <character>

package

the shared object file name character>

project

working directory; must be writeable with no spaces <character>

start

simulation start time <numeric>

end

simulation end time <numeric>

delta

simulation time interval <numeric>

add

additional simulation times <numeric-vector>

param

<parameter_list>

fixed

a <parameter_list> of fixed value parameters; these are not updatable from R

init

<cmt_list>

digits

significant digits in simulated output; negative integer means ignore <numeric>

hmin

passed to dlsoda <numeric>

hmax

passed to dlsoda <numeric>

mxhnil

passed to dlsoda <numeric>

ixpr

passed to dlsoda <numeric>

atol

passed to dlsoda <numeric>

rtol

passed to dlsoda <numeric>

ss_rtol

relative tolerance to use when finding PK steady state <numeric>

ss_atol

absolute tolerance to use when finding PK steady state <numeric>

maxsteps

passed to dlsoda <numeric>

preclean

passed to R CMD SHLIB during compilation <logical>

verbose

print run information to screen <logical>

quiet

print various information to screen <logical>

debug

not used

tscale

used to scale time in simulated output <numeric>

omega

matlist for simulating individual-level random effects

sigma

matlist for simulating residual error variates

args

<list> of arguments to be passed to mrgsim

advan

either 2, 4, or 13 <numeric>

trans

either 1, 2, 4, or 11 <numeric>

request

vector of compartments to request <character>

soloc

directory path for storing the model shared object <character>

code

a character vector of the model code

capture

a character vector of variables that are captured from the simulation <character>

mindt

minimum time between simulation records <numeric>

envir

internal model environment <environment>

shlib

a list of data related to build outcome <list>

funs

symbol names for model functions in the shared object

annot

model annotations <list>

plugin

model plugins <character>

Icap

capture indices to recover in the simulation <integer>

capL

labels for Icap; <character>

Icmt

compartment indices to recover in the simulation <integer>

cmtL

labels for Icmt; <character>

ss_cmt

compartments numbers to be considered when advancing the system to steady state <integer>

Notes

• Spaces in paths (project and soloc) are prohibited.

See Also

update, solversettings

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 = NULL, ...)

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,
  etasrc = "omega",
  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

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.

• etasrc: this argument lets you control where ETA(n) come from in the model. When etasrc is set to "omega" (the default), ETAs will be simulated from a multivariate normal distribution defined by the ⁠$OMEGA⁠ blocks in the model. Alternatively, input data or idata sets can be used to pass in fixed ETA(n) by setting etasrc to "data", "idata", "data.all" or "idata.all". When etasrc is set to "data" or "data.all", the input data set will be scanned for columns called ETA1, ETA2, ..., ETAn and those values will be copied into the appropriate slot in the ETA() vector. Only the first record for each individual will be copied into ETA(); all records after the first will be ignored. When there are more than 9 ETAs in a model, NONMEM will start naming the outputs ET10, ET11 etc rather than ETA10 and ETA11. When mrgsolve is looking for these columns, it will first search, for example, ET10 and use that value if it is found. If ET10 isn't found and there are more than 9 ETAs, then it will also search for ETA10. An error will be generated in case mrgsolve finds both the ETA and ET name variant for the tenth and higher ETA (e.g. it is an error to have both ETA10 and ET10 in the data set). When mrgsolve is searching for ETA columns in the data set, it will only look for ETAn up to the number of rows (or columns) in all the model ⁠$OMEGA⁠ blocks. For example, if ⁠$OMEGA⁠ is 5x5, only ETA1 through ETA5 will be searched. An error will be generated in case mrgsolve finds no columns with ETAn names and something other than etasrc = "omega" was passed. When etasrc = "data" and an ETAn column is missing from the data set, the missing ETA() will be set to 0. Alternatively, the user can pass etasrc = "data.all" which causes an error to be generated if any ETAn is missing from the data set. Use this option when you intend to have all ETAs attached to the data set and want an error generated if mrgsolve finds one or more of them is missing. Using etasrc ="idata" or "idata.all", the behavior is identical to "data" (or "data.all"), except mrgsolve will look at the idata set rather than data set.

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

Simulate from a model object with quicker turnaround

Description

Use the function when you would usually use mrgsim_d(), but you need a quicker turnaround time. The timing differences might be difficult to detect for a single simulation run but could become appreciable with repeated simulation. See Details for important differences in how mrgsim_q() is invoked compared to mrgsim() and mrgsim_d(). This function should always be used for benchmarking simulation time with mrgsolve.

Usage

mrgsim_q(
  x,
  data,
  recsort = 1,
  stime = numeric(0),
  output = "mrgsims",
  skip_init_calc = FALSE,
  simcall = 0,
  etasrc = "omega"
)

Arguments

Details

mrgsim_q() mainly cuts some of the overhead from the simulation. So, the primary efficiency gain from using mrgsim_q() comes when the simulation executes very quickly. It is unlikely you will see a big performance difference between mrgsim_q() and mrgsim() when the model is difficult to solve or if there is a large input data set.

This function does not support the piped simulation workflow. All arguments must be passed into the function except for x.

A data set is required for this simulation workflow. The data set can have only dosing records or doses with observations. When the data set only includes doses, a single numeric vector of observation times should be passed in.

This simulation workflow does not support Req (request) functionality. All compartments and captured variables will always be returned in the simulation output.

This simulation workflow does not support carry-out functionality.

This simulation workflow does not accept arguments to be passed to update(). This must be done by a separate call to update().

This simulation workflow does not support use of event objects. If an event object is needed, it should be converted to a data set prior to the simulation run (see as_data_set() or as.data.frame()).

This simulation workflow does not support idata sets or any feature enabled by idata set use. Individual level parameters should be joined onto the data set prior to simulation. Otherwise mrgsim_i() or mrgsim_ei() should be used.

By default, a mrgsims object is returned (as with mrgsim()). Use the output = "df" argument to request a plain data.frame of simulated data on return.

Value

By default, an object of class mrgsims. Use output = "df" to return a data frame.

See Also

mrgsim(), mrgsim_variants, qsim()

Examples

mod <- mrgsolve::house()

data <- expand.ev(amt = c(100, 300, 1000))

out <- mrgsim_q(mod, data)

out

mrgsim variant functions

Description

These functions are called by mrgsim() and have explicit input requirements written into the function name. The motivation behind these variants is to give the user a clear workflow with specific, required inputs as indicated by the function name. Use mrgsim_q() instead to benchmark mrgsolve or to do repeated quick simulation for tasks like parameter optimization, sensitivity analyses, or optimal design.

Usage

mrgsim_e(x, events, idata = NULL, data = NULL, ...)

mrgsim_d(x, data, idata = NULL, events = NULL, ...)

mrgsim_ei(x, events, idata, data = NULL, ...)

mrgsim_di(x, data, idata, events = NULL, ...)

mrgsim_i(x, idata, data = NULL, events = NULL, ...)

mrgsim_0(x, idata = NULL, data = NULL, events = NULL, ...)

Arguments

Details

Important: all of these functions require that data, idata, and/or events be pass directly to the functions. They will not recognize these inputs from a pipeline.

• mrgsim_e simulate using an event object

• mrgsim_ei simulate using an event object and idata_set

• mrgsim_d simulate using a data_set

• mrgsim_di simulate using a data_set and idata_set

• mrgsim_i simulate using a idata_set

• mrgsim_0 simulate using just the model

• mrgsim_q simulate from a data set with quicker turnaround (see mrgsim_q())

See Also

mrgsim(), mrgsim_q(), qsim()

Methods for working with mrgsims objects

Description

These methods help the user view simulation output and extract simulated data to work with further. The methods listed here for the most part have generics defined by R or other R packages. See the See Also section for other methods defined by mrgsolve that have their own documentation pages.

Usage

## S4 method for signature 'mrgsims'
x$name

## S4 method for signature 'mrgsims'
tail(x, ...)

## S4 method for signature 'mrgsims'
head(x, ...)

## S4 method for signature 'mrgsims'
dim(x)

## S4 method for signature 'mrgsims'
names(x)

## S4 method for signature 'mrgsims'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S4 method for signature 'mrgsims'
as.matrix(x, ...)

## S3 method for class 'mrgsims'
summary(object, ...)

## S4 method for signature 'mrgsims'
show(object)

Arguments

Details

Most methods should behave as expected according to other method commonly used in R (e.g. head, tail, as.data.frame, etc ...)

• $ selects a column in the simulated data and returns numeric

• head() see head.matrix(); returns simulated data

• tail() see tail.matrix(); returns simulated data

• dim(), nrow(), ncol() returns dimensions, number of rows, and number of columns in simulated data

• as.data.frame() coerces simulated data to data.frame

• as.matrix() returns matrix of simulated data

• summary() coerces simulated data to data.frame and passes to summary.data.frame()

• plot() plots simulated data; see plot_mrgsims

See Also

stime()

Examples

## example("mrgsims")

mod <- mrgsolve::house() %>% init(GUT=100)

out <- mrgsim(mod)

class(out)

## Not run: 
out

## End(Not run)
head(out)
tail(out)


dim(out)
names(out)

mat <- as.matrix(out)
df <- as.data.frame(out)

## Not run: 
out$CP

## End(Not run)

plot(out)

## Not run: 
plot(out, CP~.)
plot(out, CP+RESP~time, scales="same", xlab="Time", main="Model sims")

## End(Not run)

S4 class for mrgsolve simulation output

Description

S4 class for mrgsolve simulation output

Slots

request

character vector of compartments requested in simulated output

outnames

character vector of column names in simulated output coming from table step

data

data.frame of simulated data

mod

the mrgmod model object

Methods for handling output with dplyr verbs

Description

These methods modify the data in a mrgsims object and return a data frame. Contrast with the functions in mrgsims_modify.

Usage

## S3 method for class 'mrgsims'
pull(.data, ...)

## S3 method for class 'mrgsims'
filter(.data, ...)

## S3 method for class 'mrgsims'
group_by(.data, ..., add = FALSE, .add = FALSE)

## S3 method for class 'mrgsims'
distinct(.data, ..., .keep_all = FALSE)

## S3 method for class 'mrgsims'
mutate(.data, ...)

## S3 method for class 'each'
summarise(.data, funs, ...)

## S3 method for class 'mrgsims'
summarise(.data, ...)

## S3 method for class 'mrgsims'
do(.data, ..., .dots)

## S3 method for class 'mrgsims'
select(.data, ...)

## S3 method for class 'mrgsims'
slice(.data, ...)

as_data_frame.mrgsims(x, ...)

## S3 method for class 'mrgsims'
as_tibble(x, ...)

as.tbl.mrgsims(x, ...)

Arguments

Details

For the select_sims function, the dots ... must be either compartment names or variables in ⁠$CAPTURE⁠. An error will be generated if no valid names are selected or the names for selection are not found in the simulated output.

See Also

mrgsims_modify

Examples

out <- mrgsim(house(), events = ev(amt = 100), end = 5, delta=1)

dplyr::filter(out, time==2)

dplyr::mutate(out, label = "abc")

dplyr::select(out, time, RESP, CP)

Methods for modifying mrgsims objects

Description

These functions modify the simulated data in an mrgsims object and return the modified object. Contrast with the functions in mrgsims_dplyr.

Usage

mutate_sims(.data, ...)

select_sims(.data, ...)

filter_sims(.data, ...)

Arguments

See Also

mrgsims_dplyr

Examples

out <- mrgsim(house(), events = ev(amt = 100))

filter_sims(out, time > 2)

mutate_sims(out, label = "abc")

select_sims(out, RESP, CP)

dplyr verbs for event objects

Description

dplyr verbs for event objects

Usage

## S3 method for class 'ev'
mutate(.data, ...)

## S3 method for class 'ev'
select(.data, ...)

## S3 method for class 'ev'
filter(.data, ...)

Arguments

Simulate from a multivariate normal distribution with mean zero

Description

Simulate from a multivariate normal distribution with mean zero

Usage

mvgauss(mat, n = 10, seed = NULL)

Arguments

Write a model to native mrgsolve format

Description

Model code is written to a file in native mrgsolve format. This can be useful for (1) breaking connection to NONMEM modeling outputs that are imported by ⁠$NMXML⁠ or ⁠$NMEXT⁠ and (2) saving model updates (e.g., an updated parameter list). Models can be read back using mread().

Usage

mwrite_cpp(x, file, update = TRUE)

Arguments

Details

See important details in mwrite_yaml().

Value

A list containing data that was written out to the cpp file, with added item file, is returned invisibly.

See Also

mwrite_yaml(), yaml_to_cpp()

Examples

temp <- tempfile(fileext = ".mod")

mod <- modlib("pk1", compile = FALSE)

x <- mwrite_cpp(mod, file = temp)

mod <- mread(x$file, compile = FALSE)

mod

Write model code to yaml format

Description

Model code is written to a readable, transport format. This transport format can be useful for (1) breaking connection to NONMEM modeling outputs that are imported by ⁠$NMXML⁠ or ⁠$NMEXT⁠ and (2) saving model updates (e.g., an updated parameter list). Models can be read back using mread_yaml() or converted to mrgsolve cpp format with yaml_to_cpp().

Usage

mwrite_yaml(x, file, digits = 8)

Arguments

Details

Parameters and omega and sigma matrices that were imported via ⁠$NMXML⁠ or ⁠$NMEXT⁠ will be written into the yaml file and the NONMEM import blocks will be dropped. This allows the user to load a model based on a NONMEM run without having a connection to that output (e.g., root.xml or root.ext). Given that the connection to the NONMEM modeling outputs is broken when writing to yaml, any update to the NONMEM run will only be propagated to the yaml file when mwrite_yaml() is run again.

The yaml file does not currently have the ability to track other external dependencies, such as user-defined header files or other code that might be sourced in by the user when the model is loaded via mread(). NONMEM xml and ext files imported by ⁠$NMXML⁠ or ⁠$NMEXT⁠ are the only external dependencies that are accounted for in the yaml transport file.

Value

A list containing data that was written out to the yaml file, with added item file, is returned invisibly.

See Also

mread_yaml(), yaml_to_cpp()

Examples

mod <- house()

temp1 <- tempfile(fileext = ".yaml")

x <- mwrite_yaml(mod, temp1)

readLines(temp1)

Get all names from a model object

Description

Get all names from a model object

Usage

## S4 method for signature 'mrgmod'
names(x)

Arguments

Examples

mod <- mrgsolve::house()
names(mod)

Import model estimates from a NONMEM ext file

Description

Import model estimates from a NONMEM ext file

Usage

nmext(
  run = NA_real_,
  project = getwd(),
  file = paste0(run, ".ext"),
  path = NULL,
  root = c("working", "cppfile"),
  index = "last",
  theta = TRUE,
  omega = TRUE,
  sigma = TRUE,
  olabels = NULL,
  slabels = NULL,
  oprefix = "",
  sprefix = "",
  tname = "THETA",
  oname = "...",
  sname = "...",
  read_fun = "data.table",
  env = NULL
)

Arguments

See Also

nmxml(), read_nmext()

Import model estimates from a NONMEM xml file

Description

Import model estimates from a NONMEM xml file

Usage

nmxml(
  run = numeric(0),
  project = character(0),
  file = character(0),
  path = character(0),
  root = c("working", "cppfile"),
  theta = TRUE,
  omega = TRUE,
  sigma = TRUE,
  olabels = NULL,
  slabels = NULL,
  oprefix = "",
  sprefix = "",
  tname = "THETA",
  oname = "...",
  sname = "...",
  index = "last",
  xpath = ".//nm:estimation",
  env = NULL
)

Arguments

Details

If run and project are supplied, the .xml file is assumed to be located in run.xml, in directory run off the project directory. If file is supplied, run and project arguments are ignored.

This function requires that the xml2 package be installed and loadable. If requireNamespace("xml2") fails, an error will be generated.

nmxml usually expects to find run results in the xpath called ⁠.//nm:estimation⁠. Occasionally, the run results are not stored in this namespace but no namespaces are found in the xml file. In this case, the user can specify the xpath containing run results. Consider trying ⁠.//estimation⁠ as an alternative if the default fails.

Value

A list with theta, omega and sigma elements, depending on what was requested.

See Also

nmext

Examples

if(requireNamespace("xml2")) {
  proj <- system.file("nonmem", package = "mrgsolve")
  mrgsolve:::nmxml(run = 1005, project = proj)
}

Create a diagonal numeric matrix from diagonal elements

Description

Create a diagonal numeric matrix from diagonal elements

Usage

numeric2diag(x, context = NULL)

Arguments

Value

a numeric diagonal matrix

Methods for numericlist

Description

These methods can be used to coerce param and init objects into common R data structures, extract elements from numericlists, or get attributes from numericlists.

Usage

## S4 method for signature 'numericlist'
as.list(x, ...)

## S4 method for signature 'numericlist'
as.numeric(x)

## S4 method for signature 'numericlist'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S4 method for signature 'numericlist'
length(x)

## S4 method for signature 'numericlist'
names(x)

## S4 method for signature 'numericlist'
x$name

## S4 method for signature 'numericlist'
x[[i, ..., exact = TRUE]]

## S4 method for signature 'numericlist'
x[i, j, ..., drop = TRUE]

Arguments

S4 class numeric list

Description

S4 class numeric list

Arguments

Prepare data.frame for input to mrgsim()

Description

Prepare data.frame for input to mrgsim()

Usage

numerics_only(x, quiet = FALSE, convert_lgl = FALSE)

Arguments

Augment observations in the simulated output

Description

Augment observations in the simulated output

Usage

obsaug(x, value = TRUE, ...)

Arguments

Collect only observation records in the simulated output

Description

Collect only observation records in the simulated output

Usage

obsonly(x, value = TRUE, ...)

Arguments

Details

There is also an 'obsonly' argument to [mrgsim()] that can be set to accomplish the same thing as a call to 'obsonly()' in the pipeline.

Manipulate OMEGA matrices

Description

The primary function is omat() that can be used to both get the ⁠$OMEGA⁠ matrices out of a model object and to update ⁠$OMEGA⁠ matrices in a model object.

Usage

omat(.x, ...)

## S4 method for signature 'missing'
omat(.x, ...)

## S4 method for signature 'matrix'
omat(.x, ..., labels = list())

## S4 method for signature 'NULL'
omat(.x, ...)

## S4 method for signature 'list'
omat(.x, ...)

## S4 method for signature 'omegalist'
omat(.x, ...)

## S4 method for signature 'mrgmod'
omat(.x, ..., make = FALSE, open = FALSE)

## S4 method for signature 'mrgsims'
omat(.x, make = FALSE, ...)

Arguments

See Also

smat(), dmat(), bmat(), cmat()

Examples

# example("omega")
mat1 <- matrix(1)
mat2 <- diag(c(1,2,3))
mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
mat4 <- dmat(0.1, 0.2, 0.3, 0.4)

omat(mat1)
omat(mat1, mat2, mat3)
omat(A = mat1, B = mat2, C = mat3)

mod <- mrgsolve::house() %>% omat(mat4)

omat(mod)
omat(mod, make = TRUE)
as.matrix(omat(mod))

Show names of current output variables

Description

Outputs can include model compartments or variables defined in the model that have been marked to capture in simulated output.

Usage

outvars(x, unlist = FALSE)

Arguments

Value

When unlist is FALSE (default) : a named list, with cmt showing names of output compartments and capture giving names of output variables in capture. When unlist is TRUE, then a single, unnamed character vector of outvar names is returned.

Examples

mod <- mrgsolve::house()
outvars(mod)

Create and work with parameter objects

Description

See numericlist for methods to deal with parameter_list objects.

Usage

param(.x, ...)

## S4 method for signature 'mrgmod'
param(.x, .y = NULL, ..., .pat = "*", .strict = FALSE)

## S4 method for signature 'mrgsims'
param(.x, ...)

## S4 method for signature 'missing'
param(..., .strict = TRUE)

## S4 method for signature 'list'
param(.x, ...)

## S4 method for signature 'ANY'
param(.x, ...)

allparam(.x)

Arguments

Details

Can be used to either get a parameter list object from a mrgmod model object or to update the parameters in a model object. For both uses, the return value is a parameter_list object. For the former use, param() is usually called to print the parameters to the screen, but the parameter_list object can also be coerced to a list or numeric R object.

Use allparam() to get a parameter_list object including both model parameters and data items listed in ⁠$FIXED⁠.

The update to parameters can be permissive (candidates with names that don't exist in the parameter list are silently ignored) or strict (all candidates must already exist in the parameter list). When passing candidate values via ..., the update is strict and an error is generated if you pass a name that isn't found in the parameter list. When candidate values are passed as a named object via .y, then the update is permissive. Any permissive update can be made strict (error if foreign names are found in the candidates) by passing .strict = TRUE.

An alternative is to assess the incoming names using inventory().

Value

An object of class parameter_list (see numericlist).

See Also

inventory()

Examples

## example("param")

mod <- house()

param(mod)

param(mod, .pat="^(C|F)") ## may be useful when large number of parameters

class(param(mod))

param(mod)$KA

param(mod)[["KA"]]

as.list(param(mod))

as.data.frame(param(mod))

mod <- param(mod, CL = 1.2)

new_values <- list(CL = 1.3, VC = 20.5)

mod <- param(mod, new_values)

Return parameter tags

Description

Use this function if you added the ⁠@covariates⁠ or ⁠@input⁠ attributes or specified a user-defined tag (via ⁠@tag⁠) in one or more parameter blocks and need to extract that information. Also, using the ⁠$INPUT⁠ block to declare parameters will automatically add the input tag (via ⁠@input⁠). Once these attributes / tags are added, you can use check_data_names() to reconcile names of input data sets against tagged model parameters.

Usage

param_tags(x)

Arguments

Value

A data frame listing parameter names and their tags.

Model specification

Note: it is good practice to tag parameters where appropriate with input or covariates as these will automatically be expected on input data when you call check_data_names(). User-defined tags are also possible, but you will need to alert check_data_names() to look for them.

Model Specification Examples

You can use the ⁠$INPUT⁠ block to add the input tag on these parameters

$INPUT 
STUDY = 101, WT = 70, DVID = 1

Tag some covariates in the model

$PARAM @covariates
WT = 70, SEX = 1, EGFR = 110

A user-defined tag

$PARAM @tag flags
FFLAG = 1, DFLAG = 0

See Also

check_data_names()

Examples

mod <- mrgsolve::house()

param_tags(mod)

S4 parameter_list class

Description

S4 parameter_list class

Plot method for mrgsims objects

Description

Plot method for mrgsims objects

Usage

## S4 method for signature 'batch_mrgsims,missing'
plot(x, yval = variables(x), auto.key = list(), mincol = 3, ...)

## S4 method for signature 'batch_mrgsims,formula'
plot(
  x,
  y,
  show.grid = TRUE,
  lwd = 2,
  type = "l",
  yval = variables(x),
  auto.key = list(columns = 1),
  scales = list(y = list(relation = "free")),
  ...
)

Arguments

Generate a quick plot of simulated data

Description

Generate a quick plot of simulated data

Usage

## S4 method for signature 'mrgsims,missing'
plot(x, limit = 16, ...)

## S4 method for signature 'mrgsims,formula'
plot(
  x,
  y,
  limit = 16,
  show.grid = TRUE,
  outer = TRUE,
  type = "l",
  lwd = 2,
  ylab = "value",
  groups = ID,
  scales = list(y = list(relation = "free")),
  logy = FALSE,
  logbr = 1,
  ...
)

## S4 method for signature 'mrgsims,character'
plot(x, y, ...)

Arguments

Examples

mod <- mrgsolve::house(end=48, delta=0.2) %>% init(GUT=1000)

out <- mrgsim(mod)

plot(out)

plot(out, subset=time <=24)

plot(out, GUT+CP~.)

plot(out, CP+RESP~time, col="black", scales="same", lty=2)

## Not run: 
plot(out, "CP RESP, GUT")

## End(Not run)

Plot data as an mrgsims object

Description

Plot data as an mrgsims object

Usage

plot_sims(.data, ..., .f = NULL, .dots = list())

Arguments

Details

This function is only intended for use with data frames that were created by modifying an mrgsims object.

Examples

mod <- mrgsolve::house() %>% ev(amt = 100)

out <- mrgsim(mod) 
out_df <- dplyr::mutate(out, time <= 72)

plot(out)
plot_sims(out, CP, RESP)

## Not run: 
plot_sims(out, .f = ~ CP + RESP)
plot_sims(out, .f = CP + RESP ~ time)

## End(Not run)

Basic, simple simulation from model object

Description

This is just a lighter version of mrgsim(), with fewer options but with better efficiency in certain cases. See Details.

Usage

qsim(
  x,
  data,
  idata = no_idata_set(),
  obsonly = FALSE,
  tgrid = NULL,
  recsort = 1,
  tad = FALSE,
  Req = NULL,
  outvars = Req,
  skip_init_calc = FALSE,
  output = "mrgsims"
)

Arguments

Details

qsim() mainly cuts some of the overhead from the simulation. So, the primary efficiency gain from using qsim() comes when the simulation executes very quickly. It is unlikely you will see a big performance difference between qsim() and mrgsim() when the model is difficult to solve or if there is a large input data set.

There is no pipeline interface for this function; all configuration options (see Arguments) must be passed as formal arguments to the function. You can't carry_out, Request specific columns, or pass items in for update. Some other limitations, but only convenience-related. See Arguments for available options. Specifically, there is no ... argument for this function. Use the update() method to update the model object.

See Also

mrgsim_q(), mrgsim(), mrgsim_variants

Examples

mod <- mrgsolve::house()

dose <- ev(amt = 100)

out <- qsim(mod,dose)

Extract estimates from NONMEM ext file

Description

This function retrieves NONMEM estimates for use in the mrgsolve model when ⁠$NMEXT⁠ is invoked. See nmext().

Usage

read_nmext(
  run = NA_real_,
  project = getwd(),
  file = paste0(run, ".ext"),
  path = NULL,
  read_fun = c("data.table", "read.table"),
  index = "last"
)

Arguments

Value

A list with param, omega, and sigma in a format ready to be used to update a model object.

Examples

project <- system.file("nonmem", package = "mrgsolve")

est <- read_nmext(1005, project = project)

est$param

est$omega

est$sigma

est <- read_nmext(2005, project = project, index = 3)

Make addl doses explicit in an event object or data set

Description

When doses are scheduled with ii and addl, the object is expanded to include one record for every dose. In the result, no record with have ii or addl set to non-zero value.

Usage

realize_addl(x, ...)

## S3 method for class 'data.frame'
realize_addl(
  x,
  warn = FALSE,
  mark_new = FALSE,
  fill = c("inherit", "na", "locf"),
  ...
)

## S3 method for class 'ev'
realize_addl(x, ...)

Arguments

Details

If no addl column is found the data frame is returned and a warning is issued if warn is true. If ii, time, or evid are missing, an error is generated.

If a grouped data.frame (via dplyr::group_by()) is passed, it will be ungrouped.

Use caution when passing in data that has non-dose-related data columns that vary within a subject and pay special attention to the fill argument. By definition, realize_addl() will add new rows to your data frame and it is not obvious how the non-dose-related data should be handled in these new rows. When inherit is chosen, the new records have non-dose-related data that is identical to the originating dose record. This should be fine when these data items are not varying with time, but will present a problem when the data are varying with time. When locf is chosen, the missing data are filled in with NA and an last observation carry forward operation is applied to every column in the data set. This may not be what you want if you already had missing values in the input data set and want to preserve that missingness. When na is chosen, the missing data are filled in with NA and no locf operation is applied. But note that these missing values may be problematic for a mrgsolve simulation run. If you have any time-varying columns or missing data in your data set, be sure to check that the output from this function is what you were expecting.

Value

A data.frame or event object, consistent with the type of x. The ii and addl columns will all be set to zero. The result is always ungrouped.

Examples

e <- ev(amt = 100, ii = 12, addl = 3)

realize_addl(e)

a <- ev(amt = 100, ii = 12, addl = 2, WT = 69)
b <- ev(amt = 200, ii = 24, addl = 2, WT = 70)
c <- ev(amt =  50, ii =  6, addl = 2, WT = 71) 

e <- ev_seq(a,b,c)
realize_addl(e, mark_new = TRUE)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

filter

Render a model to a document

Description

Render a model to a document

Usage

render(x, ...)

## S4 method for signature 'character'
render(x, project = NULL, ...)

## S4 method for signature 'mrgmod'
render(x, ...)

dorender(model, project, template = NULL, compile = TRUE, ...)

Arguments

Examples

## Not run: 
mod <- mrgsolve::house()
mrgsolve:::render(mod)
mrgsolve:::render("irm2", modlib())

## End(Not run)

Reserved words

Description

Reserved words

Usage

reserved()

Details

Note: this function is not exported; you must go into the mrgsolve namespace by using the mrgsolve::: prefix.

Examples

mrgsolve:::reserved()

Get model random effect variances and covariances

Description

Use this function to extract both OMEGA and SIGMA matrices from a model object. Typical use is for display on the R console.

Usage

revar(x, ...)

## S4 method for signature 'mrgmod'
revar(x, ...)

Arguments

Value

A named list containing omega and sigma matrices.

Examples

mod <- mrgsolve::house()
revar(mod)

Scrape options and pass to function

Description

Scrape options and pass to function

Usage

scrape_and_call(x, env, pass, ...)

Arguments

Details

Attributes of x are also scraped and merged with options.

Scrape options from a code block

Description

Scrape options from a code block

Usage

scrape_opts(
  x,
  envir = list(),
  def = list(),
  all = TRUE,
  marker = "=",
  allow_multiple = FALSE,
  narrow = TRUE
)

Arguments

Value

list with elements x (the data without options) and named options as specified in the block.

Print model code to the console

Description

This is a simple way to display the model code on the R console using the model object. The raw argument will return the model code as a character vector.

Usage

see(x, ...)

## S4 method for signature 'mrgmod'
see(x, raw = FALSE, ...)

Arguments

Value

NULL is returned invisibly when raw is FALSE; when raw is set to TRUE, the model code is returned as a character vector.

Show the compartment list

Description

Show the compartment list

Usage

## S4 method for signature 'cmt_list'
show(object)

Arguments

Print model details

Description

Print model details

Usage

## S4 method for signature 'mrgmod'
show(object)

Arguments

Show the parameter list

Description

Show the parameter list

Usage

## S4 method for signature 'parameter_list'
show(object)

Arguments

Manipulate SIGMA matrices

Description

The primary function is smat() which can be used to both get the ⁠$SIGMA⁠ matrices out of a model object and to update ⁠$SIGMA⁠ matrices in a model object.

Usage

smat(.x, ...)

## S4 method for signature 'missing'
smat(.x, ...)

## S4 method for signature 'matrix'
smat(.x, ..., labels = list())

## S4 method for signature 'list'
smat(.x, ...)

## S4 method for signature 'sigmalist'
smat(.x, ...)

## S4 method for signature 'mrgmod'
smat(.x, ..., make = FALSE, open = FALSE)

## S4 method for signature 'NULL'
smat(.x, ...)

## S4 method for signature 'mrgsims'
smat(.x, make = FALSE, ...)

Arguments

See Also

dmat(), bmat(), cmat()

Examples

## example("sigma")
mat1 <- matrix(1)
mat2 <- diag(c(1,2))
mat3 <- matrix(c(0.1, 0.002, 0.002, 0.5), 2,2)
mat4 <- dmat(0.1, 0.2, 0.3, 0.4)

smat(mat1)
smat(mat1, mat2, mat3)
smat(A=mat1, B=mat2, C=mat3)

mod <- mrgsolve::house() %>% smat(mat1)

smat(mod)
smat(mod, make=TRUE)

Access or clear arguments for calls to mrgsim()

Description

As a model object navigates a pipeline prior to simulation, arguments are collected to eventually be passed to mrgsim(). simargs() lets you intercept and possibly clear those arguments.

Usage

simargs(x, which = NULL, clear = FALSE, ...)

Arguments

Value

If clear is TRUE, the argument list is cleared and the model object is returned. Otherwise, the argument list is returned.

Examples

mod <- mrgsolve::house()
mod %>% Req(CP, RESP) %>% carry_out(evid, WT, FLAG) %>% simargs()

Return the location of the model shared object

Description

This is also the directory where the model is built, which could be the value of tempdir().

Usage

soloc(x, short = FALSE)

Arguments

Value

A string containing the full path to the model shared object.

Examples

mod <- mrgsolve::house()
soloc(mod)

Optional inputs for lsoda

Description

These are settings for the differential equation solver (lsoda) that can be accessed via the R interface. The code listing below is taken directly from the lsoda source code.

Details

The following items can be set

• hmax (HMAX below); decrease hmax when you want to limit how big of a step the solver can take when integrating from one time to the next time. However be aware that smaller hmax will result in longer run times.

• hmin (HMIN below); don't fiddle with this unless you know what you're doing.

• ixpr (IXPR below)

• maxsteps (MXSTEP below); increase this number when the solver has a long interval between two integration times (e.g. when observation records are far apart).

• mxhnil (MXHNIL below); don't usually modify this one

• atol - the absolute solver tolerance; decrease this number (e.g. to 1E-10 or 1E-20 or 1E-50) when the value in a compartment can get extremely small; without this extra (lower) tolerance, the value can get so low that the number can randomly become negative. However be aware that more precision here will result in longer run times.

• rtol - the relative solver tolerances; decrease this number when you want a more precise solution. However be aware that more precision here will result in longer run times.

See Also

aboutsolver, update

Get the times at which the model will be evaluated

Description

Get the times at which the model will be evaluated

Usage

stime(x, ...)

Arguments

Details

Simulation times include the sequence of times created from start, end, and delta and the vector of times found in add.

Making end negative (e.g. -1) will omit the start-end-delta sequence. Negative values are discarded from the result.

Value

A sorted vector of unique simulation times from the time grid in the model object.

Examples

## example("stime", package="mrgsolve")

mod <- mrgsolve::house(end = 12, delta = 2, add = c(11,13,15))

stime(mod)

update(mod, end = -1) %>% stime()

Print summary of a mrgmod object

Description

Print summary of a mrgmod object

Usage

## S3 method for class 'mrgmod'
summary(object, ...)

Arguments

Create a simtime object

Description

simtime objects allow the user to specify simulation start and end times, along with the simulation time step.

Usage

tgrid(
  start = 0,
  end = 24,
  delta = 1,
  add = numeric(0),
  .offset = 0,
  .scale = 1,
  ...
)

## S4 method for signature 'tgrid'
stime(x, ...)

## S4 method for signature 'tgrids'
stime(x, ...)

## S4 method for signature 'numeric'
stime(x, ...)

## S4 method for signature 'tgrid'
show(object)

## S4 method for signature 'tgrids'
show(object)

## S4 method for signature 'mrgmod'
stime(x, ...)

Arguments

Examples

peak <- tgrid(0, 6, 0.2)
sparse <- tgrid(0, 24, 4)

day1 <- c(peak, sparse)

design <- c(day1, day1+72, day1+240)

## Not run: 
mod <- mrgsolve::house()

out <- mod %>% ev(amt=1000, ii=24, addl=10) %>% mrgsim(tgrid=design)

plot(out, CP ~ time, type = 'b')

## End(Not run)

Get inits from compiled function

Description

This function is usually for internal use.

Usage

touch_funs(x, keep_pointers = TRUE)

Arguments

Re-scale time in the simulated output

Description

Re-scale time in the simulated output

Usage

tscale(x, value = 1, ...)

Arguments

Details

There is also a tscale argument to mrgsim() that can be set to accomplish the same thing as a call to tscale in the pipeline.

Examples

# The model is in hours:
mod <- mrgsolve::house()

# The output is in days:
mod %>% tscale(1/24) %>% mrgsim()

Update the model object

Description

After the model object is created, update various attributes.

Usage

## S4 method for signature 'mrgmod'
update(object, ..., merge = TRUE, open = FALSE, data = NULL, strict = TRUE)

## S4 method for signature 'omegalist'
update(object, y, ...)

## S4 method for signature 'sigmalist'
update(object, y, ...)

## S4 method for signature 'parameter_list'
update(object, .y, ...)

Arguments

Details

Slots that can be updated:

• verbose

• debug

• preclean

• mindt

• digits

• atol - absolute solver tolerance; see solversettings

• rtol - relative solver tolerance; see solversettings

• ss_rtol - relative tolerance when finding steady state

• ss_atol - absolute tolerance when finding steady state

• ixpr - see IXPR in solversettings

• mxhnil - see MXHNIL in solversettings

• hmin - see HMIN in solversettings

• hmax - see HMAX in solversettings

• maxsteps - see MXSTEP in solversettings

• start, end, delta, add

• tscale

• request

• param

• init

• omega

• sigma

• outvars

Value

The updated model object is returned.

See Also

update, mrgmod-class, within

Examples

## Not run: 
 mod <- house()

 mod <- update(mod, end = 120, delta = 4, param = list(CL = 19.1))

## End(Not run)
 

Validate and prepare data sets for simulation

Description

This function is called by mrgsim() and friends to check and prepare input data sets for simulation. Users may also call this function to pre-validate data when the same data set is used for repeated simulation.

Usage

valid_data_set(x, m = NULL, verbose = FALSE, quiet = FALSE)

valid_data_set.matrix(x, verbose = FALSE)

Arguments

Details

An error will be issued when

• non-numeric data is found in columns sharing names with model parameters

• non-numeric data is found in reserved data items related to dosing (see mrgsolve:::GLOBALS$CARRY_TRAN)

• a column is found that is "internally classed", including columns that inherit from integer64 (see is.object())

Value

A matrix with non-numeric columns dropped; if x is a data.frame with character cmt column comprised of valid compartment names and m is a model object, the cmt column will be converted to the corresponding compartment number.

See Also

valid_idata_set(), idata_set(), data_set()

Examples

mod <- mrgsolve::house()

data(exTheoph)

d <- valid_data_set(exTheoph, mod)

Validate and prepare idata data sets for simulation

Description

This function is called by mrgsim() and friends to check and prepare input data sets for simulation. Users may also call this function to pre-validate data when the same data set is used for repeated simulation.

Usage

valid_idata_set(x, m, verbose = FALSE, quiet = FALSE)

Arguments

Details

An error will be issued when

• non-numeric data is found in columns sharing names with model parameters

• a column is found that is internally classed, including columns that inherit from integer64 (see is.object())

Value

A numeric matrix with class valid_idata_set.

See Also

valid_data_set(), idata_set(), data_set()

Simulate a sequence of parameters

Description

This function is experimental and may change or go away at any time without notice.

Usage

wf_sweep(mod, ..., n = 10, cv = 30, nsd = 2)

Arguments

Value

A mrgsims object with a character columns named .name indicating the parameter name and .value indicating the sweep value.

Examples

mod <- mrgsolve::house() %>% zero_re()

mod %>% 
  ev(amt = 100) %>% 
  wf_sweep(CL, VC) %>% 
  plot(CP~time|.name)

Update parameters, initials, and settings within a model object

Description

The main use case for using within rather than update or param or init is when you want to update to a new value that is calculated from the existing value. See the example in details

Usage

## S3 method for class 'mrgmod'
within(data, expr, ...)

Arguments

Details

Other model object slots that can be updated: start, end, delta, add, rtol, atol, hmax, maxsteps. These are include for convenience, but we expect that most of the time these will get updated through the update method.

See Also

update

Examples

mod <- mrgsolve::house()

mod2 <- within(mod, {CL <- CL * 1.5})

mod$CL
mod2$CL

Zero out random effects in a model object

Description

Sets all elements of the OMEGA or SIGMA matrix to zero.

Usage

zero_re(.x, ...)

## S4 method for signature 'mrgmod'
zero_re(.x, ...)

Arguments

Value

An updated object with elements of OMEGA and/or SIGMA set to zero.

Examples

mod <- house()
revar(mod)
mod <- zero_re(mod)
revar(mod)

## Not run: 
mod <- modlib("popex", compile = FALSE)
mod <- zero_re(mod, omega)
revar(mod)

## End(Not run)