nlmixrSim: Simulate a nlmixr solved system

Description Usage Arguments

View source: R/simulate.R

Description

This takes the uncertainty in the model parameter estimates and to simulate a number of theoretical studies. Each study simulates a realization of the parameters from the uncertainty in the fixed parameter estimates. In addition the omega and sigma matrices are simulated from the uncertainty in the Omega/Sigma matrices based on the number of subjects and observations the model was based on.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
nlmixrSim(object, ...)

## S3 method for class 'nlmixrFitData'
rxSolve(object, params = NULL, events = NULL,
  inits = NULL, scale = NULL, covs = NULL, method = c("liblsoda",
  "lsoda", "dop853"), transitAbs = NULL, atol = 1e-06, rtol = 1e-04,
  maxsteps = 5000L, hmin = 0L, hmax = NULL, hini = 0L,
  maxordn = 12L, maxords = 5L, ..., cores,
  covsInterpolation = c("linear", "locf", "nocb", "midpoint"),
  addCov = FALSE, matrix = FALSE, sigma = NULL, sigmaDf = NULL,
  nCoresRV = 1L, sigmaIsChol = FALSE, nDisplayProgress = 10000L,
  amountUnits = NA_character_, timeUnits = "hours", stiff,
  theta = NULL, eta = NULL, addDosing = FALSE,
  updateObject = FALSE, doSolve = TRUE, omega = NULL,
  omegaDf = NULL, omegaIsChol = FALSE, nSub = 1L, thetaMat = NULL,
  thetaDf = NULL, thetaIsChol = FALSE, nStud = 1L, dfSub = 0,
  dfObs = 0, returnType = c("rxSolve", "matrix", "data.frame"),
  seed = NULL, nsim = NULL)

## S3 method for class 'nlmixrFitData'
simulate(object, nsim = 1, seed = NULL, ...)

## S3 method for class 'nlmixrFitData'
solve(a, b, ...)

Arguments

object

nlmixr object

...

Other arguments sent to rxSolve

params

a numeric named vector with values for every parameter in the ODE system; the names must correspond to the parameter identifiers used in the ODE specification;

events

an eventTable object describing the input (e.g., doses) to the dynamic system and observation sampling time points (see eventTable);

inits

a vector of initial values of the state variables (e.g., amounts in each compartment), and the order in this vector must be the same as the state variables (e.g., PK/PD compartments);

scale

a numeric named vector with scaling for ode parameters of the system. The names must correstond to the parameter identifiers in the ODE specification. Each of the ODE variables will be divided by the scaling factor. For example scale=(center=2) will divide the center ODE variable by 2.

covs

a matrix or dataframe the same number of rows as the sampling points defined in the events eventTable. This is for time-varying covariates.

method

The method for solving ODEs. Currently this supports:

  • "liblsoda" thread safe lsoda. This supports parallel thread-based solving, and ignores user Jacobian specification.

  • "lsoda" – LSODA solver. Does not support parallel thread-based solving, but allows user Jacobian specification.

  • "dop853" – DOP853 solver. Does not support parallel thread-based solving nor user Jacobain specification

transitAbs

boolean indicating if this is a transit compartment absorption

atol

a numeric absolute tolerance (1e-8 by default) used by the ODE solver to determine if a good solution has been achieved; This is also used in the solved linear model to check if prior doses do not add anything to the solution.

rtol

a numeric relative tolerance (1e-6 by default) used by the ODE solver to determine if a good solution has been achieved. This is also used in the solved linear model to check if prior doses do not add anything to the solution.

maxsteps

maximum number of (internally defined) steps allowed during one call to the solver. (5000 by default)

hmin

The minimum absolute step size allowed. The default value is 0.

hmax

The maximum absolute step size allowed. The default checks for the maximum difference in times in your sampling and events, and uses this value. The value 0 is equivalent to infinite maximum absolute step size.

hini

The step size to be attempted on the first step. The default value is determined by the solver (when hini = 0)

maxordn

The maximum order to be allowed for the nonstiff (Adams) method. The default is 12. It can be between 1 and 12.

maxords

The maximum order to be allowed for the stiff (BDF) method. The default value is 5. This can be between 1 and 5.

cores

Number of cores used in parallel ODE solving. This defaults to the number or system cores determined by rxCores for methods that support parallel solving (ie thread-safe methods like "liblsoda").

covsInterpolation

specifies the interpolation method for time-varying covariates. When solving ODEs it often samples times outside the sampling time specified in events. When this happens, the time varying covariates are interpolated. Currently this can be:

  • "linear" interpolation (the default), which interpolates the covariate by solving the line between the observed covariates and extrapolating the new covariate value.

  • "constant" – Last observation carried forward.

  • "NOCB" – Next Observation Carried Backward. This is the same method that NONMEM uses.

  • "midpoint" Last observation carried forward to midpoint; Next observation carried backward to midpoint.

addCov

A boolean indicating if covariates should be added to the output matrix or data frame. By default this is disabled.

matrix

A boolean inticating if a matrix should be returned instead of the RxODE's solved object.

sigma

Named sigma covariance or Cholesky decomposition of a covariance matrix. The names of the columns indicate parameters that are simulated. These are simulated for every observation in the solved system.

sigmaDf

Degrees of freedom of the sigma t-distribution. By default it is equivalent to Inf, or a normal distribution.

nCoresRV

Number of cores used for the simulation of the sigma variables. By default this is 1. This uses the package rmvn and rmvt. To reproduce the results you need to run on the same platform with the same number of cores. This is the reason this is set to be one, regardless of what the number of cores are used in threaded ODE solving.

sigmaIsChol

Boolean indicating if the sigma is in the Cholesky decomposition instead of a symmetric covariance

nDisplayProgress

An integer indicating the minimum number of c-based solves before a progress bar is shown. By default this is 10,000.

amountUnits

This supplies the dose units of a data frame supplied instead of an event table. This is for importing the data as an RxODE event table.

timeUnits

This supplies the time units of a data frame supplied instead of an event table. This is for importing the data as an RxODE event table.

stiff

a logical (TRUE by default) indicating whether the ODE system is stiff or not.

For stiff ODE sytems (stiff = TRUE), RxODE uses the LSODA (Livermore Solver for Ordinary Differential Equations) Fortran package, which implements an automatic method switching for stiff and non-stiff problems along the integration interval, authored by Hindmarsh and Petzold (2003).

For non-stiff systems (stiff = FALSE), RxODE uses DOP853, an explicit Runge-Kutta method of order 8(5, 3) of Dormand and Prince as implemented in C by Hairer and Wanner (1993).

theta

A vector of parameters that will be named THETA[#] and added to parameters

eta

A vector of parameters that will be named ETA[#] and added to parameters

addDosing

Boolean indicating if the solve should add RxODE evid and amt columns. This will also include dosing information and estimates at the doses. Be default, RxODE only includes estimates at the observations. (default FALSE).

updateObject

This is an internally used flag to update the RxODE solved object (when supplying an RxODE solved object) as well as returning a new object. You probably should not modify it's FALSE default unless you are willing to have unexpected results.

doSolve

Internal flag. By default this is TRUE, when FALSE a list of solving options is returned.

omega

Named omega matrix.

omegaDf

The degrees of freedom of a t-distribution for simulation. By default this is NULL which is equivalent to Inf degrees, or to simulate from a normal distribution instead of a t-distribution.

omegaIsChol

Indicates if the omega supplied is a Cholesky decomposed matrix instead of the traditional symmetric matrix.

nSub

Number between subject variabilities (ETAs) simulated for every realization of the parameters.

thetaMat

Named theta matrix.

thetaDf

The degrees of freedom of a t-distribution for simulation. By default this is NULL which is equivalent to Inf degrees, or to simulate from a normal distribution instead of a t-distribution.

thetaIsChol

Indicates if the theta supplied is a Cholesky decomposed matrix instead of the traditional symmetric matrix.

nStud

Number virtual studies to characterize uncertainty in estimated parameters.

dfSub

Degrees of freedom to sample the between subject variaiblity matrix from the inverse Wishart distribution (scaled) or scaled inverse chi squared distribution.

dfObs

Degrees of freedom to sample the unexplained variaiblity matrix from the inverse Wishart distribution (scaled) or scaled inverse chi squared distribution.

returnType

This tells what type of object is returned. The currently supported types are:

  • "rxSolve" (default) will return a reactive data frame that can change easily change different pieces of the solve and update the data frame. This is the currently standard solving method in RxODE, is used for rxSolve(object, ...), solve(object,...),

  • "data.frame" – returns a plain, non-reactive data frame; Currently very slightly Faster than returnType="matrix"

  • "matrix" – returns a plain matrix with column names attached to the solved object. This is what is used object$run as well as object$solve

seed

an object specifying if and how the random number generator should be initialized

nsim

represents the number of simulations. For RxODE, if you supply single subject event tables (created with eventTable)

a

when using solve, this is equivalent to the object argument. If you specify object later in the argument list it overwrites this parameter.

b

when using solve, this is equivalent to the params argument. If you specify params as a named argument, this overwrites the output


nlmixr documentation built on Sept. 23, 2018, 5:04 p.m.