Package 'nlmixr2est'

Augment Prediction for Ipred Model

Description

This function augments the prediction for an individual prediction (Ipred) model. It retrieves the simulation model from the fit object and evaluates the model variables.

Usage

.augPredIpredModel(fit)

Arguments

fit	The fitted model object from which to retrieve the simulation model.

Details

The function performs the following steps:

- Retrieves the simulation model from the provided 'fit' object using '.getSimModel' with 'hideIpred' and 'tad' set to 'FALSE'.

- Evaluates the model variables using 'rxModelVars'.

Value

The evaluated model variables for the Ipred model.

---

Preprocess Covariates needed (or other data items)

Description

Preprocess Covariates needed (or other data items)

Usage

.nlmixr0preProcessCovariatesPresent(ui, est, data, control)

Arguments

ui	rxode2 ui
est	estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools
data	nlmixr data
control	The estimation control object. These are expected to be different for each type of estimation method

Value

list with the ui (possibly modified)

Author(s)

Matthew L. Fidler

---

This literally fixes parameters in the model

Description

Whenever there is a fixed parameter in the model, the parameter is replaced with the literal value inside of the model and dropped from the 'ini' block. This only occurs when the 'control$literalFix=TRUE'.

Usage

.nlmixrPreprocessLiteralFix(ui, est, data, control)

Arguments

ui	model function/object
est	estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools
data	nlmixr data
control	The estimation control object. These are expected to be different for each type of estimation method

Value

list with possibly updated ui

Author(s)

Matthew L. Fidler

---

Preprocess the zero omegas

Description

Preprocess the zero omegas

Usage

.preProcessDataUi(ui, est, data, control)

Arguments

ui	rxode2 ui
est	estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools
data	nlmixr data
control	The estimation control object. These are expected to be different for each type of estimation method

Value

list with the ui (possibly modified)

Author(s)

Matthew L. Fidler

---

Preprocess the zero omegas

Description

Preprocess the zero omegas

Usage

.preProcessZeroOmega(ui, est, data, control)

Arguments

ui	rxode2 ui model
est	estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools
data	nlmixr data
control	The estimation control object. These are expected to be different for each type of estimation method

Value

list with the ui (possibly modified)

Author(s)

Matthew L. Fidler

---

This function is to set the number of threads to 2

Description

In general it is a CRAN requirement that packages not use more than 2 threads. This function is to set the number of threads to 2 for CRAN testing. It is not intended for general use.

Usage

aaaCranNlmixrThreads()

Details

When testing with devtools::test() or testthat::test_package(), the NOT_CRAN environment variable is set to "true", so the number of threads will not be limited to 2.

Value

nothing, called for side effect of setting the number of threads to 2 for CRAN testing

Author(s)

Matthew L. Fidler

Examples

# Set the number of threads to 2 for CRAN testing
aaaCranNlmixrThreads()

---

Add CWRES

Description

This returns a new fit object with CWRES attached

Usage

addCwres(fit, focei = TRUE, updateObject = TRUE, envir = parent.frame(1))

Arguments

fit	nlmixr2 fit without WRES/CWRES
focei	Boolean indicating if the focei objective function is added. If not the foce objective function is added.
updateObject	Boolean indicating if the original fit object should be updated. By default this is true.
envir	Environment that should be checked for object to update. By default this is the global environment.

Value

fit with CWRES

Author(s)

Matthew L. Fidler

Examples

one.cmt <- function() {
  ini({
    ## You may label each parameter with a comment
    tka <- 0.45 # Log Ka
    tcl <- log(c(0, 2.7, 100)) # Log Cl
    ## This works with interactive models
    ## You may also label the preceding line with label("label text")
    tv <- 3.45; label("log V")
    ## the label("Label name") works with all models
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    linCmt() ~ add(add.sd)
  })
}

f <- try(nlmixr2(one.cmt, theo_sd, "saem"))

print(f)

# even though you may have forgotten to add the cwres, you can add it to the data.frame:

if (!inherits(f, "try-error")) {
  f <- try(addCwres(f))
  print(f)
}

# Note this also adds the FOCEi objective function

---

NPDE calculation for nlmixr2

Description

NPDE calculation for nlmixr2

Usage

addNpde(
  object,
  updateObject = TRUE,
  table = tableControl(),
  ...,
  envir = parent.frame(1)
)

Arguments

object	nlmixr2 fit object
updateObject	Boolean indicating if original object should be updated. By default this is TRUE.
table	'tableControl()' list of options
...	Other ignored parameters.
envir	Environment that should be checked for object to update. By default this is the global environment.

Value

New nlmixr2 fit object

Author(s)

Matthew L. Fidler

Examples

one.cmt <- function() {
  ini({
    ## You may label each parameter with a comment
    tka <- 0.45 # Log Ka
    tcl <- log(c(0, 2.7, 100)) # Log Cl
    ## This works with interactive models
    ## You may also label the preceding line with label("label text")
    tv <- 3.45; label("log V")
    ## the label("Label name") works with all models
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    linCmt() ~ add(add.sd)
  })
}

f <- nlmixr2(one.cmt, theo_sd, "saem")

# even though you may have forgotten to add the NPDE, you can add it to the data.frame:

f <- addNpde(f)

---

Add table information to nlmixr2 fit object without tables

Description

Add table information to nlmixr2 fit object without tables

Usage

addTable(
  object,
  updateObject = FALSE,
  data = object$dataSav,
  thetaEtaParameters = object$foceiThetaEtaParameters,
  table = tableControl(),
  keep = NULL,
  drop = NULL,
  envir = parent.frame(1)
)

Arguments

object	nlmixr2 family of objects
updateObject	Update the object (default FALSE)
data	Saved data from
thetaEtaParameters	Internal theta/eta parameters
table	a 'tableControl()' list of options
keep	Character Vector of items to keep
drop	Character Vector of items to drop or NULL
envir	Environment to search for updating

Value

Fit with table information attached

Author(s)

Matthew Fidler

Examples

one.cmt <- function() {
  ini({
    ## You may label each parameter with a comment
    tka <- 0.45 # Log Ka
    tcl <- log(c(0, 2.7, 100)) # Log Cl
    ## This works with interactive models
    ## You may also label the preceding line with label("label text")
    tv <- 3.45; label("log V")
    ## the label("Label name") works with all models
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    linCmt() ~ add(add.sd)
  })
}

# run without tables step
f <- nlmixr2(one.cmt, theo_sd, "saem", control=list(calcTables=FALSE))

print(f)

# Now add the tables

f <- addTable(f)

print(f)

---

Control options for the agq estimation method

Description

This is the control options for the adaptive Gauss-Hermite quadrature for the likelihood. Note that nAGQ=1 is the same as the Laplace method.

Usage

agqControl(
  sigdig = 3,
  nAGQ = 2,
  ...,
  interaction = TRUE,
  agqLow = -Inf,
  agqHi = Inf
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
...	Parameters used in the default 'foceiControl()'
interaction	boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation
agqLow	The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.
agqHi	The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.

Value

agqControl object

Author(s)

Matthew L. Fidler

Examples

agqControl()

# Use adaptive quadrature

# x =  Litter size after 21 days, and the modeled value

r <- rats
r$dv <- r$x

# Time is not used in this model, but it is required in nlmixr2
# currently, add a dummy value

r$time <- 0

f <- function() {
  ini({
    t1 <- 1
    t2 <- 1
    t3 <- 1
    eta1 ~ 1
  })
  model({
    lp <- t1 * x1 + t2 * x2 + (x1 + x2*t3) * eta1
    p <- pnorm(lp)
    m1 <- m # need to add outside of model specification
    x ~ dbinom(m1, p)
  })
}

fit <- nlmixr(f, r, est="agq")


p <- pump

p$dv <- p$y
p$time <- 0 # dummy time

f <- function() {
  ini({
    t1 <- 1
    t2 <- 1
    t3 <- 1
    t4 <- 1
    eta1 ~ 1
  })
  model({
    if (group == 1) {
       lp <- t1 + t2 * logtstd
    } else {
       lp <- t3 + t4 * logtstd
    }
    lp <- lp + eta1
    lam <- exp(lp)
    y ~ dpois(lam)
  })
}

fit <- nlmixr(f, p, est="agq", control=agqControl(nAGQ=5))

one.cmt <- function() {
  ini({
    ## You may label each parameter with a comment
    tka <- 0.45 # Log Ka
    tcl <- log(c(0, 2.7, 100)) # Log Cl
    ## This works with interactive models
    ## You may also label the preceding line with label("label text")
    tv <- 3.45; label("log V")
    ## the label("Label name") works with all models
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
 })
 model({
   ka <- exp(tka + eta.ka)
   cl <- exp(tcl + eta.cl)
   v <- exp(tv + eta.v)
   linCmt() ~ add(add.sd)
 })
}

fit <- nlmixr(one.cmt, theo_sd, est="agq")

---

Assert that this is a nlmixr2 fit object

Description

Will error without nlmixr2 fit object

Usage

assertNlmixrFit(fit)

Arguments

fit	Fit object

Value

Nothing

Author(s)

Matthew L. Fidler

Examples

## Not run: 

f <- 4
assertNlmixrFit(f) # throw error


## End(Not run)

---

Assert that this is a nlmixr2 fit data object

Description

Will error without nlmixr2 fit data object

Usage

assertNlmixrFitData(fit)

Arguments

fit	Fit object

Value

Nothing

Author(s)

Matthew L. Fidler

Examples

## Not run: 

f <- 4
assertNlmixrFitData(f) # throw errors


## End(Not run)

---

Control for bobyqa estimation method in nlmixr2

Description

Control for bobyqa estimation method in nlmixr2

Usage

bobyqaControl(
  npt = NULL,
  rhobeg = NULL,
  rhoend = NULL,
  iprint = 0L,
  maxfun = 100000L,
  returnBobyqa = FALSE,
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  addProp = c("combined2", "combined1"),
  calcTables = TRUE,
  compress = FALSE,
  covMethod = c("r", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  eventSens = c("jump", "fd"),
  ...
)

Arguments

npt	Number of points for the quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to 'min(n*2, n+2)'.
rhobeg	Initial trust region radius (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Defaults to 'min(0.95, 0.2*max(abs(par)))'; adjusted upward if smaller than 'abs(upper-lower)/2'.
rhoend	Final trust region radius. Defaults to '1e-6*rhobeg'.
iprint	Controls amount of printing ('0'=none, '1'=start/end only, '2'=each new rho, '3'=every function evaluation, '>3'=every 'iprint' evaluations). Default '0'.
maxfun	The maximum allowed number of function evaluations. If this is exceeded, the method will terminate.
returnBobyqa	return the bobyqa output instead of the nlmixr2 fit
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
...	Ignored parameters

Value

bobqya control structure

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="bobyqa")

print(fit2)

# you can also get the bobyqa output with

fit2$bobyqa

---

Cox Box, Yeo Johnson and inverse transformation

Description

Cox Box, Yeo Johnson and inverse transformation

Usage

boxCox(x, lambda = 1)

iBoxCox(x, lambda = 1)

yeoJohnson(x, lambda = 1)

iYeoJohnson(x, lambda = 1)

Arguments

x	data to transform
lambda	Cox-box lambda parameter

Value

Cox-Box Transformed Data

Author(s)

Matthew L. Fidler

Examples

boxCox(1:3,1) ## Normal
iBoxCox(boxCox(1:3,1))

boxCox(1:3,0) ## Log-Normal
iBoxCox(boxCox(1:3,0),0)

boxCox(1:3,0.5) ## lambda=0.5
iBoxCox(boxCox(1:3,0.5),0.5)

yeoJohnson(seq(-3,3),1) ## Normal
iYeoJohnson(yeoJohnson(seq(-3,3),1))

yeoJohnson(seq(-3,3),0)
iYeoJohnson(yeoJohnson(seq(-3,3),0),0)

---

Generalized Cholesky Matrix Decomposition

Description

Performs a (modified) Cholesky factorization of the form

Usage

cholSE(matrix, tol = (.Machine$double.eps)^(1/3))

Arguments

matrix	Matrix to be Factorized.
tol	Tolerance; Algorithm suggests (.Machine$double.eps) ^ (1 / 3), default

Details

t(P) %*% A %*% P + E = t(R) %*% R

As detailed in Schnabel/Eskow (1990)

Value

Generalized Cholesky decomposed matrix.

Note

This version does not pivot or return the E matrix

Author(s)

Matthew L. Fidler (translation), Johannes Pfeifer, Robert B. Schnabel and Elizabeth Eskow

References

matlab source: http://www.dynare.org/dynare-matlab-m2html/matlab/chol_SE.html; Slightly different return values

Robert B. Schnabel and Elizabeth Eskow. 1990. "A New Modified Cholesky Factorization," SIAM Journal of Scientific Statistical Computing, 11, 6: 1136-58.

Elizabeth Eskow and Robert B. Schnabel 1991. "Algorithm 695 - Software for a New Modified Cholesky Factorization," ACM Transactions on Mathematical Software, Vol 17, No 3: 306-312

---

Control options for the foce estimation method

Description

This is the first order option without the interaction between residuals and etas.

Usage

foceControl(sigdig = 3, ..., interaction = FALSE)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
interaction	Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'focei' instead

Value

foceControl object

Author(s)

Matthew L. Fidler

Examples

foceControl()

---

Control Options for FOCEi

Description

Control Options for FOCEi

Usage

foceiControl(
  sigdig = 4,
  ...,
  epsilon = NULL,
  maxInnerIterations = 1000,
  maxOuterIterations = 5000,
  n1qn1nsim = NULL,
  print = 1L,
  printNcol = NULL,
  scaleTo = 1,
  scaleObjective = 0,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleC0 = 1e+05,
  derivEps = rep(20 * sqrt(.Machine$double.eps), 2),
  derivMethod = c("switch", "forward", "central"),
  derivSwitchTol = NULL,
  covDerivMethod = c("central", "forward"),
  covMethod = c("r,s", "r", "s", ""),
  hessEps = (.Machine$double.eps)^(1/3),
  hessEpsLlik = (.Machine$double.eps)^(1/3),
  optimHessType = c("central", "forward"),
  optimHessCovType = c("central", "forward"),
  eventType = c("central", "forward"),
  centralDerivEps = rep(20 * sqrt(.Machine$double.eps), 2),
  lbfgsLmm = 7L,
  lbfgsPgtol = 0,
  lbfgsFactr = NULL,
  eigen = TRUE,
  diagXform = c("sqrt", "log", "identity"),
  iovXform = c("sd", "var", "logsd", "logvar"),
  sumProd = FALSE,
  optExpression = TRUE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  ci = 0.95,
  useColor = NULL,
  boundTol = NULL,
  calcTables = TRUE,
  noAbort = TRUE,
  interaction = TRUE,
  cholSEtol = (.Machine$double.eps)^(1/3),
  cholAccept = 0.001,
  resetEtaP = 0.15,
  resetThetaP = 0.05,
  resetThetaFinalP = 0.15,
  diagOmegaBoundUpper = 5,
  diagOmegaBoundLower = 100,
  cholSEOpt = FALSE,
  cholSECov = FALSE,
  fo = FALSE,
  covTryHarder = FALSE,
  outerOpt = c("lbfgsb3c", "nlminb", "bobyqa", "L-BFGS-B", "mma", "lbfgsbLG", "slsqp",
    "Rvmmin", "uobyqa", "newuoa"),
  innerOpt = c("n1qn1", "BFGS"),
  rhobeg = 0.2,
  rhoend = NULL,
  npt = NULL,
  rel.tol = NULL,
  x.tol = NULL,
  eval.max = 4000,
  iter.max = 2000,
  abstol = NULL,
  reltol = NULL,
  resetHessianAndEta = FALSE,
  muModel = c("none", "irls", "lin"),
  muRefCovAlg = TRUE,
  muModelTol = 0.001,
  muModelMaxCycles = 10L,
  stateTrim = Inf,
  shi21maxOuter = 0L,
  shi21maxInner = 20L,
  shi21maxInnerCov = 20L,
  shi21maxFD = 20L,
  gillK = 10L,
  gillStep = 4,
  gillFtol = 0,
  gillRtol = sqrt(.Machine$double.eps),
  gillKcov = 10L,
  gillKcovLlik = 10L,
  gillStepCovLlik = 4.5,
  gillStepCov = 2,
  gillFtolCov = 0,
  gillFtolCovLlik = 0,
  rmatNorm = TRUE,
  rmatNormLlik = TRUE,
  smatNorm = TRUE,
  smatNormLlik = TRUE,
  covGillF = TRUE,
  optGillF = TRUE,
  covSmall = 1e-05,
  adjLik = TRUE,
  gradTrim = Inf,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  gradCalcCentralSmall = 1e-04,
  gradCalcCentralLarge = 10000,
  etaNudge = qnorm(1 - 0.05/2)/sqrt(3),
  etaNudge2 = qnorm(1 - 0.05/2) * sqrt(3/5),
  nRetries = 3,
  seed = 42,
  resetThetaCheckPer = 0.1,
  etaMat = NULL,
  repeatGillMax = 1,
  stickyRecalcN = 4,
  indTolRelax = TRUE,
  gradProgressOfvTime = 10,
  addProp = c("combined2", "combined1"),
  badSolveObjfAdj = 100,
  compress = FALSE,
  rxControl = NULL,
  sigdigTable = NULL,
  fallbackFD = FALSE,
  smatPer = 0.6,
  sdLowerFact = 0.001,
  zeroGradFirstReset = TRUE,
  zeroGradRunReset = TRUE,
  zeroGradBobyqa = TRUE,
  mceta = -1L,
  nAGQ = 0,
  agqLow = -Inf,
  agqHi = Inf,
  eventSens = c("jump", "fd"),
  boundedTransform = TRUE
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Ignored parameters
epsilon	Precision of estimate for n1qn1 optimization.
maxInnerIterations	Number of iterations for n1qn1 optimization.
maxOuterIterations	Maximum number of L-BFGS-B optimization for outer problem.
n1qn1nsim	Number of function evaluations for n1qn1 optimization.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
scaleObjective	Scale the initial objective function to this value. By default this is 0 (meaning do not scale)
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleC0	Number to adjust the scaling factor by if the initial gradient is zero.
derivEps	Forward difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].
derivMethod	Derivative method for the outer problem: "switch", "central", or "forward". "switch" starts forward and toggles to central when abs(delta(OFV)) <= derivSwitchTol.
derivSwitchTol	The tolerance to switch forward to central differences.
covDerivMethod	indicates the method for calculating the derivatives while calculating the covariance components (Hessian and S).
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
hessEps	is a double value representing the epsilon for the Hessian calculation. This is used for the R matrix calculation.
hessEpsLlik	is a double value representing the epsilon for the Hessian calculation when doing focei generalized log-likelihood estimation. This is used for the R matrix calculation.
optimHessType	Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).
optimHessCovType	Hessian type for numeric-difference individual Hessians used for the covariance step/final likelihood: "central" (more accurate, used here) or "forward".
eventType	Event gradient type for dosing events; Can be "central" or "forward"
centralDerivEps	Central difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].
lbfgsLmm	An integer giving the number of BFGS updates retained in the "L-BFGS-B" method, It defaults to 7.
lbfgsPgtol	Projected-gradient convergence tolerance for "L-BFGS-B": iteration stops when max(| proj g_i |) <= lbfgsPgtol. Defaults to '0' (check suppressed).
lbfgsFactr	Convergence factor for "L-BFGS-B": converges when the objective reduction is within lbfgsFactr * .Machine$double.eps. Default '1e10' (~4 sigdigs, 2e-6).
eigen	A boolean indicating if eigenvectors are calculated to include a condition number calculation.
diagXform	Transformation used on the diagonal of chol(solve(omega)) (the FOCEi-estimated parameters): one of "sqrt" (default), "log", or "identity".
iovXform	Transformation used on the diagonal of the IOV: one of "sd", "var", "logsd", or "logvar".
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
boundTol	Tolerance for boundary issues.
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
noAbort	Boolean to indicate if you should abort the FOCEi evaluation if it runs into troubles. (default TRUE)
interaction	Boolean indicate FOCEi should be used (TRUE) instead of FOCE (FALSE)
cholSEtol	tolerance for Generalized Cholesky Decomposition. Defaults to suggested (.Machine$double.eps)^(1/3)
cholAccept	Tolerance to accept a Generalized Cholesky Decomposition for a R or S matrix.
resetEtaP	P-value for resetting an individual ETA to 0 during optimization, based on a z-test of chol(omega^-1) %*% eta or eta/sd(allEtas). '0' = never reset, '1' = always reset.
resetThetaP	P-value for resetting mu-referenced THETAs based on ETA drift, checked at the start and near a local minimum (see resetThetaCheckPer). '0' = never reset; '1' is not allowed.
resetThetaFinalP	represents the p-value for reseting the population mu-referenced THETA parameters based on ETA drift during optimization, and resetting the optimization one final time.
diagOmegaBoundUpper	Upper bound of the diagonal omega matrix, as diag(omega)*diagOmegaBoundUpper. '1' = no upper bound.
diagOmegaBoundLower	Lower bound of the diagonal omega matrix, as diag(omega)/diagOmegaBoundLower. '1' = no lower bound.
cholSEOpt	Boolean indicating if the generalized Cholesky should be used while optimizing.
cholSECov	Boolean indicating if the generalized Cholesky should be used while calculating the Covariance Matrix.
fo	is a boolean indicating if this is a FO approximation routine.
covTryHarder	If the R matrix is non-positive definite and cannot be corrected to be non-positive definite try estimating the Hessian on the unscaled parameter space.
outerOpt	optimization method for the outer problem
innerOpt	optimization method for the inner problem (not implemented yet.)
rhobeg	Initial trust region radius for the bobyqa outer optimizer (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Default '0.2' (20 'abs(upper-lower)/2'. (bobyqa)
rhoend	Final trust region radius. If not defined, '10^(-sigdig-1)' is used. (bobyqa)
npt	Number of points for bobyqa's quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to '2*n + 1'. (bobyqa)
rel.tol	Relative tolerance before nlminb stops (nlmimb).
x.tol	X tolerance for nlmixr2 optimizer
eval.max	Number of maximum evaluations of the objective function (nlmimb)
iter.max	Maximum number of iterations allowed (nlmimb)
abstol	Absolute tolerance for nlmixr2 optimizer (BFGS)
reltol	tolerance for nlmixr2 (BFGS)
resetHessianAndEta	is a boolean representing if the individual Hessian is reset when ETAs are reset using the option resetEtaP.
muModel	Selects the mu-referenced-FOCEI-family regression variant for theta/eta in a mu-ref covariate relationship (see muRefCovAlg): "none" (default, ordinary FOCEI); "lin" (mufocei/mufoce/muagq/ mulaplace: population theta and covariate coefficient(s) per mu-ref-covariate group are excluded from the outer optimizer and re-derived in C++ by closed-form OLS regression of each subject's back-calculated value on the covariate(s), residual becomes that subject's eta; repeats until convergence, see muModelTol/ muModelMaxCycles); or "irls" (irlsfocei/irlsfoce/irlsagq/irlslaplace: same mechanism, reweighted by inner-optimization curvature). A mu-ref-covariate theta with a finite bound falls back to ordinary bounded outer-optimizer handling with a warning (a bound on the group's population theta excludes the whole group; a bound on one covariate coefficient excludes only that covariate).
muRefCovAlg	When 'TRUE' (default), algebraic expressions that can be mu-referenced are internally rewritten as mu-referenced covariates and restored after optimization. Mirrors saemControl(muRefCovAlg=)/nlmeControl(muRefCovAlg=); for foceiControl() only takes effect when muModel != "none".
muModelTol	Convergence tolerance for the mu-referenced-FOCEI-family "re-optimize etas, then regress" cycle (muModel != "none"): repeats until the max mu-group theta change drops below this value or muModelMaxCycles is reached.
muModelMaxCycles	Maximum number of "re-optimize etas, regress" cycles per outer iteration (see muModel, muModelTol).
stateTrim	Trim state amounts/concentrations to this value.
shi21maxOuter	The maximum number of steps for the optimization of the forward-difference step size. When not zero, use this instead of Gill differences.
shi21maxInner	The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem. When 0, un-optimized finite differences are used.
shi21maxInnerCov	The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem for the covariance step. When 0, un-optimized finite differences are used.
shi21maxFD	The maximum number of steps for the optimization of the forward difference step size when using dosing events (lag time, modeled duration/rate and bioavailability)
gillK	Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983). '0' = no optimal step size determined.
gillStep	When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration the new step size = (prior step size)*gillStep
gillFtol	The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates.
gillRtol	The relative tolerance used for Gill 1983 determination of optimal step size.
gillKcov	Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983) during the covariance step. '0' = no optimal step size determined.
gillKcovLlik	Same as gillK but for the generalized focei log-likelihood method (Gill 1986).
gillStepCovLlik	Same as above but during generalized focei log-likelihood
gillStepCov	When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration during the covariance step is equal to the new step size = (prior step size)*gillStepCov
gillFtolCov	The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates during the covariance step.
gillFtolCovLlik	Same as above but applied during generalized log-likelihood estimation.
rmatNorm	A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix
rmatNormLlik	A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix if you are using generalized log-likelihood Hessian matrix.
smatNorm	A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix
smatNormLlik	A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix if you are using the generalized log-likelihood.
covGillF	Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central difference gradient calculation.
optGillF	Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central differences for optimization.
covSmall	Small number used to compare covariance estimates (sandwich vs R/S matrix) before rejecting one as too small to be the final covariance estimate.
adjLik	When 'TRUE', adjusts the likelihood by the 2*pi constant nlmixr2's objective function otherwise omits (to match NONMEM), more closely matching nlme/SAS likelihood approximations. The objective function itself always matches NONMEM regardless.
gradTrim	The parameter to adjust the gradient to if the |gradient| is very large.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
gradCalcCentralSmall	A small number that represents the value where |grad| < gradCalcCentralSmall where forward differences switch to central differences.
gradCalcCentralLarge	A large number that represents the value where |grad| > gradCalcCentralLarge where forward differences switch to central differences.
etaNudge	When n1qn1 optimization of an ETA (starting at zero) misbehaves, reset the Hessian and nudge the ETA up by this value, then down if it still doesn't move. Defaults to 'qnorm(1-0.05/2)*1/sqrt(3)'. Falls back to etaNudge2, then to zero (stop optimizing) if unsuccessful.
etaNudge2	This is the second eta nudge. By default it is qnorm(1-0.05/2)*sqrt(3/5), which is the n=3 quadrature point (excluding zero) times by the 0.95% normal region
nRetries	If FOCEi doesn't fit with the current parameter estimates, randomly sample new parameter estimates and restart the problem. This is similar to 'PsN' resampling.
seed	an object specifying if and how the random number generator should be initialized
resetThetaCheckPer	represents objective function % percentage below which resetThetaP is checked.
etaMat	Initial (or final) ETA estimates; can also be a prior fit, whose final ETAs are then used as initial values. By default, uses the last fit's ETAs if supplied, else all ETAs start at zero ('NULL'). 'NA' disables reuse from a prior fit.
repeatGillMax	If the tolerances were reduced when calculating the initial Gill differences, the Gill difference is repeated up to a maximum number of times defined by this parameter.
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
gradProgressOfvTime	This is the time for a single objective function evaluation (in seconds) to start progress bars on gradient evaluations
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
badSolveObjfAdj	The objective function adjustment when the ODE system cannot be solved. It is based on each individual bad solve.
compress	Should the object have compressed items
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
fallbackFD	Fallback to the finite differences if the sensitivity equations do not solve.
smatPer	Percentage of failed per-individual parameter gradients (replaced with the overall parameter gradient) out of the total ('ntheta*nsub') above which the S matrix is considered bad.
sdLowerFact	Factor multiplying the estimate when the lower bound is zero for a standard-deviation error parameter (add.sd, prop.sd, etc); e.g. estimate 0.15 with lower bound 0 assumes a lower bound of 0.00015. '0' disables this.
zeroGradFirstReset	When 'TRUE' (default), reset a zero first gradient to 'sqrt(.Machine$double.eps)' instead of erroring; 'FALSE' errors; 'NA' ignores it only on the last reset attempt.
zeroGradRunReset	When 'TRUE' (default), reset a zero gradient encountered mid-run to 'sqrt(.Machine$double.eps)' instead of erroring.
zeroGradBobyqa	When 'TRUE' (default), a zero-gradient reset switches to the gradient-free bobyqa method; 'NA' only does so for the first zero gradient.
mceta	Monte Carlo sampling for the best initial ETA estimate (based on 'omega'): '-1' (default) uses the last eta; '0' uses eta=0 for each inner optimization; for 'n>0', the last eta, eta=0, and n-1 etas sampled from omega are each evaluated and the best (by inner objective) is used.
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
agqLow	The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.
agqHi	The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
boundedTransform	When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

Details

Uses R's L-BFGS-B (optim) for the outer problem and BFGS n1qn1 (restoring the prior individual Hessian) for the inner problem, which is left unscaled since eta estimates start near zero. The covariance step is performed on the unscaled problem, so its condition number may differ from the scaled problem's.

Value

The control object that changes the options for the FOCEi family of estimation methods

Author(s)

Matthew L. Fidler

References

Gill, P.E., Murray, W., Saunders, M.A., & Wright, M.H. (1983). Computing Forward-Difference Intervals for Numerical Optimization. Siam Journal on Scientific and Statistical Computing, 4, 310-321.

Shi, H.M., Xie, Y., Xuan, M.Q., & Nocedal, J. (2021). Adaptive Finite-Difference Interval Estimation for Noisy Derivative-Free Optimization.

See Also

optim

n1qn1

rxSolve

Other Estimation control: nlmixr2NlmeControl(), saemControl()

---

Control options for the FO estimation method

Description

This is related to the focei methods and uses most of their control options. Some are ignored, 'posthoc' is an extra parameter

Usage

foControl(sigdig = 3, ..., posthoc = TRUE, interaction = NULL, fo = NULL)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiConrol()'
posthoc	Logical indicating if the estimation method should calculate 'foce' posthoc predicted parameters.
interaction	Interaction term for the model; ignored by fo
fo	Logical indicating if the estimation method is FO (first order), but this is controlled by the estimation method so this is ignored.

Value

foControl object

Author(s)

Matthew L. Fidler

Examples

foControl()

---

Control options foir the FOI estimation method

Description

This is related to the focei methods and uses most of their control options. Some are ignored, 'posthoc' is an extra parameter

Usage

foiControl(sigdig = 3, ..., posthoc = TRUE, interaction = NULL, fo = NULL)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiConrol()'
posthoc	Logical indicating if the estimation method should calculate 'foce' posthoc predicted parameters.
interaction	Interaction term for the model; ignored by fo
fo	Logical indicating if the estimation method is FO (first order), but this is controlled by the estimation method so this is ignored.

Value

foiControl object

Author(s)

Matthew L. Fidler

Examples

foiControl()

---

Get valid nlmixr control object

Description

Get valid nlmixr control object

Usage

## S3 method for class 'agq'
getValidNlmixrCtl(control)

## S3 method for class 'bobyqa'
getValidNlmixrCtl(control)

## S3 method for class 'fo'
getValidNlmixrCtl(control)

## S3 method for class 'foce'
getValidNlmixrCtl(control)

## S3 method for class 'foi'
getValidNlmixrCtl(control)

## S3 method for class 'laplace'
getValidNlmixrCtl(control)

## S3 method for class 'lbfgsb3c'
getValidNlmixrCtl(control)

## S3 method for class 'mufocei'
getValidNlmixrCtl(control)

## S3 method for class 'irlsfocei'
getValidNlmixrCtl(control)

## S3 method for class 'mufoce'
getValidNlmixrCtl(control)

## S3 method for class 'irlsfoce'
getValidNlmixrCtl(control)

## S3 method for class 'muagq'
getValidNlmixrCtl(control)

## S3 method for class 'irlsagq'
getValidNlmixrCtl(control)

## S3 method for class 'mulaplace'
getValidNlmixrCtl(control)

## S3 method for class 'irlslaplace'
getValidNlmixrCtl(control)

## S3 method for class 'n1qn1'
getValidNlmixrCtl(control)

## S3 method for class 'newuoa'
getValidNlmixrCtl(control)

## S3 method for class 'nlm'
getValidNlmixrCtl(control)

## S3 method for class 'nlminb'
getValidNlmixrCtl(control)

## S3 method for class 'nls'
getValidNlmixrCtl(control)

## S3 method for class 'optim'
getValidNlmixrCtl(control)

## S3 method for class 'posthoc'
getValidNlmixrCtl(control)

getValidNlmixrControl(control, est)

getValidNlmixrCtl(control)

## S3 method for class 'focei'
getValidNlmixrCtl(control)

## S3 method for class 'nlme'
getValidNlmixrCtl(control)

## S3 method for class 'saem'
getValidNlmixrCtl(control)

## S3 method for class 'rxSolve'
getValidNlmixrCtl(control)

## S3 method for class 'simulate'
getValidNlmixrCtl(control)

## S3 method for class 'simulation'
getValidNlmixrCtl(control)

## S3 method for class 'predict'
getValidNlmixrCtl(control)

## S3 method for class 'tableControl'
getValidNlmixrCtl(control)

## Default S3 method:
getValidNlmixrCtl(control)

## S3 method for class 'uobyqa'
getValidNlmixrCtl(control)

Arguments

control	nlmixr control object
est	Estimation routine

Details

This is based on running the S3 method 'getValidNlmixrCtl()' the 'control' object is put into a list and the class of this new list is 'c(est, "getValidNlmixrControl")'

Value

Valid control object based on estimation method run.

---

Control options for the irlsagq estimation method

Description

Mu-referenced-FOCEI-family reweighted-regression ('"irls"') variant of adaptive Gauss-Hermite quadrature; see 'foceiControl(muModel=)'.

Usage

irlsagqControl(
  sigdig = 3,
  nAGQ = 2,
  ...,
  interaction = TRUE,
  agqLow = -Inf,
  agqHi = Inf,
  muModel = c("irls", "lin", "none")
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
...	Parameters used in the default 'foceiControl()'
interaction	boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation
agqLow	The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.
agqHi	The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.
muModel	Selects the regression variant; for 'irlsagqControl()' this is always '"irls"' and cannot be changed – use 'muagqControl()' for the closed-form OLS variant.

Value

irlsagqControl object

Author(s)

Matthew L. Fidler

Examples

irlsagqControl()

---

Control options for the irlsfoce estimation method

Description

Mu-referenced-FOCEI-family reweighted-regression ('"irls"') variant of FOCE (no interaction); see 'foceiControl(muModel=)'.

Usage

irlsfoceControl(
  sigdig = 3,
  ...,
  interaction = FALSE,
  muModel = c("irls", "lin", "none")
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
interaction	Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'irlsfocei' instead
muModel	Selects the regression variant; for 'irlsfoceControl()' this is always '"irls"' and cannot be changed – use 'mufoceControl()' for the closed-form OLS variant.

Value

irlsfoceControl object

Author(s)

Matthew L. Fidler

Examples

irlsfoceControl()

---

Control options for the irlsfocei estimation method

Description

Mu-referenced-FOCEI-family reweighted-regression ('"irls"') variant of FOCEI; see 'foceiControl(muModel=)'.

Usage

irlsfoceiControl(sigdig = 3, ..., muModel = c("irls", "lin", "none"))

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
muModel	Selects the regression variant; for 'irlsfoceiControl()' this is always '"irls"' and cannot be changed – use 'mufoceiControl()' for the closed-form OLS variant.

Value

irlsfoceiControl object

Author(s)

Matthew L. Fidler

Examples

irlsfoceiControl()

---

Control options for the irlslaplace estimation method

Description

Mu-referenced-FOCEI-family reweighted-regression ('"irls"') variant of the Laplace method ('nAGQ=1'); see 'foceiControl(muModel=)'.

Usage

irlslaplaceControl(
  sigdig = 3,
  ...,
  nAGQ = 1,
  muModel = c("irls", "lin", "none")
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
muModel	Selects the regression variant; for 'irlslaplaceControl()' this is always '"irls"' and cannot be changed – use 'mulaplaceControl()' for the closed-form OLS variant.

Value

irlslaplaceControl object

Author(s)

Matthew L. Fidler

Examples

irlslaplaceControl()

---

Control iteration-time print formatting

Description

Bundles the options controlling the iteration progress output emitted by 'nlmixr2' estimators. Pass as the 'print' argument to any '*Control()' function; the scalar form ('print = N') still works and is wrapped into an 'iterPrintControl()' internally.

Usage

iterPrintControl(
  every = 1L,
  ncol = NULL,
  headerEvery = NULL,
  useColor = NULL,
  simple = FALSE
)

Arguments

every	Integer. Print one iteration row every 'every' parameter evaluations; '0' suppresses output. Defaults to '1L'.
ncol	Integer or 'NULL'. Parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
headerEvery	Integer or 'NULL'. Re-emit the column header every 'headerEvery' parameter-print events; '0' prints it once at fit start. 'NULL' (default) uses '10L'.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
simple	Logical. When 'TRUE', print a single row per iteration, suppressing the unscaled ('U') / back-transformed ('X') rows. Defaults to 'FALSE'.

Value

A list with the validated, defaulted iteration-print options. Has class '"iterPrintControl"' so the outer '*Control()' functions can distinguish a pre-built object from a scalar 'print = N'.

Author(s)

Bill Denney, Matthew L. Fidler

Examples

iterPrintControl()
iterPrintControl(every = 5, headerEvery = 0)

---

Control options for the Laplace estimation method

Description

This is the control options for the adaptive Gauss-Hermite quadrature for the likelihood. Note that nAGQ=1 is the same as the Laplace method.

Usage

laplaceControl(sigdig = 3, ..., nAGQ = 1)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Details

This method can be made to more closely matches NONMEM-style Laplace estimation by requesting the log-likelihood from STAN as well as numerically calculated Hessian matrix. This is done with adding '+dnorm()' to the model for any normal end-points.

Value

laplaceControl object

Author(s)

Matthew L. Fidler

Examples

laplaceControl()

# Use adaptive quadrature

# x =  Litter size after 21 days, and the modeled value

r <- rats
r$dv <- r$x

# Time is not used in this model, but it is required in nlmixr2
# currently, add a dummy value

r$time <- 0

f <- function() {
  ini({
    t1 <- 1
    t2 <- 1
    t3 <- 1
    eta1 ~ 1
  })
  model({
    lp <- t1 * x1 + t2 * x2 + (x1 + x2*t3) * eta1
    p <- pnorm(lp)
    m1 <- m # need to add outside of model specification
    x ~ dbinom(m1, p)
  })
}

fit <- nlmixr(f, r, est="laplace")


p <- pump

p$dv <- p$y
p$time <- 0 # dummy time

f <- function() {
  ini({
    t1 <- 1
    t2 <- 1
    t3 <- 1
    t4 <- 1
    eta1 ~ 1
  })
  model({
    if (group == 1) {
       lp <- t1 + t2 * logtstd
    } else {
       lp <- t3 + t4 * logtstd
    }
    lp <- lp + eta1
    lam <- exp(lp)
    y ~ dpois(lam)
  })
}

fit <- nlmixr(f, p, est="laplace")

---

Control for lbfgsb3c estimation method in nlmixr2

Description

Control for lbfgsb3c estimation method in nlmixr2

Usage

lbfgsb3cControl(
  trace = 0,
  factr = 1e+07,
  pgtol = 0,
  abstol = 0,
  reltol = 0,
  lmm = 5L,
  maxit = 10000L,
  returnLbfgsb3c = FALSE,
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  gradTo = 1,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  addProp = c("combined2", "combined1"),
  eventSens = c("jump", "fd"),
  calcTables = TRUE,
  compress = FALSE,
  covMethod = c("r", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  ...
)

Arguments

trace	If positive, print tracing information; higher values give more detail (see source for "L-BFGS-B" trace levels).
factr	Convergence tolerance factor for "L-BFGS-B"; converges when the objective reduction is within this factor of machine tolerance (default 1e7, i.e. ~1e-8).
pgtol	Tolerance on the projected gradient for "L-BFGS-B"; 0 (default) suppresses the check.
abstol	Absolute x-value tolerance for "L-BFGS-B"; 0 (default) suppresses the check.
reltol	Relative x-value tolerance for "L-BFGS-B"; 0 (default) suppresses the check.
lmm	Number of BFGS updates retained in "L-BFGS-B" (default 5).
maxit	maximum number of iterations.
returnLbfgsb3c	return the lbfgsb3c output instead of the nlmixr2 fit
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
gradTo	this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
...	Ignored parameters

Value

bobqya control structure

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="lbfgsb3c")

print(fit2)

# you can also get the nlm output with fit2$lbfgsb3c

fit2$lbfgsb3c

# The nlm control has been modified slightly to include
# extra components and name the parameters

---

Control options for the muagq estimation method

Description

Mu-referenced-FOCEI-family closed-form-regression ('"lin"') variant of adaptive Gauss-Hermite quadrature; see 'foceiControl(muModel=)'.

Usage

muagqControl(
  sigdig = 3,
  nAGQ = 2,
  ...,
  interaction = TRUE,
  agqLow = -Inf,
  agqHi = Inf,
  muModel = c("lin", "irls", "none")
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
...	Parameters used in the default 'foceiControl()'
interaction	boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation
agqLow	The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.
agqHi	The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.
muModel	Selects the regression variant; for 'muagqControl()' this is always '"lin"' and cannot be changed – use 'irlsagqControl()' for the IRLS variant.

Value

muagqControl object

Author(s)

Matthew L. Fidler

Examples

muagqControl()

---

Control options for the mufoce estimation method

Description

Mu-referenced-FOCEI-family closed-form-regression ('"lin"') variant of FOCE (no interaction); see 'foceiControl(muModel=)'.

Usage

mufoceControl(
  sigdig = 3,
  ...,
  interaction = FALSE,
  muModel = c("lin", "irls", "none")
)

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
interaction	Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'mufocei' instead
muModel	Selects the regression variant; for 'mufoceControl()' this is always '"lin"' and cannot be changed – use 'irlsfoceControl()' for the IRLS variant.

Value

mufoceControl object

Author(s)

Matthew L. Fidler

Examples

mufoceControl()

---

Control options for the mufocei estimation method

Description

Mu-referenced-FOCEI-family closed-form-regression ('"lin"') variant of FOCEI; see 'foceiControl(muModel=)'.

Usage

mufoceiControl(sigdig = 3, ..., muModel = c("lin", "irls", "none"))

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
muModel	Selects the regression variant; for 'mufoceiControl()' this is always '"lin"' and cannot be changed – use 'irlsfoceiControl()' for the IRLS variant.

Value

mufoceiControl object

Author(s)

Matthew L. Fidler

Examples

mufoceiControl()

---

Control options for the mulaplace estimation method

Description

Mu-referenced-FOCEI-family closed-form-regression ('"lin"') variant of the Laplace method ('nAGQ=1'); see 'foceiControl(muModel=)'.

Usage

mulaplaceControl(sigdig = 3, ..., nAGQ = 1, muModel = c("lin", "irls", "none"))

Arguments

sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
...	Parameters used in the default 'foceiControl()'
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
muModel	Selects the regression variant; for 'mulaplaceControl()' this is always '"lin"' and cannot be changed – use 'irlslaplaceControl()' for the IRLS variant.

Value

mulaplaceControl object

Author(s)

Matthew L. Fidler

Examples

mulaplaceControl()

---

Control for n1qn1 estimation method in nlmixr2

Description

Control for n1qn1 estimation method in nlmixr2

Usage

n1qn1Control(
  epsilon = (.Machine$double.eps)^0.25,
  max_iterations = 10000,
  nsim = 10000,
  imp = 0,
  print.functions = FALSE,
  returnN1qn1 = FALSE,
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  gradTo = 1,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  addProp = c("combined2", "combined1"),
  eventSens = c("jump", "fd"),
  calcTables = TRUE,
  compress = FALSE,
  covMethod = c("r", "n1qn1", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  boundedTransform = TRUE,
  ...
)

Arguments

epsilon	Precision of estimate for n1qn1 optimization.
max_iterations	Number of iterations
nsim	Number of function evaluations
imp	Verbosity of messages.
print.functions	Boolean to control if the function value and parameter estimates are echoed every time a function is called.
returnN1qn1	return the n1qn1 output instead of the nlmixr2 fit
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
gradTo	this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
boundedTransform	When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.
...	Ignored parameters

Value

bobqya control structure

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="n1qn1")

print(fit2)

# you can also get the nlm output with fit2$n1qn1

fit2$n1qn1

# The nlm control has been modified slightly to include
# extra components and name the parameters

---

Control for newuoa estimation method in nlmixr2

Description

Control for newuoa estimation method in nlmixr2

Usage

newuoaControl(
  npt = NULL,
  rhobeg = NULL,
  rhoend = NULL,
  iprint = 0L,
  maxfun = 100000L,
  returnNewuoa = FALSE,
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  addProp = c("combined2", "combined1"),
  calcTables = TRUE,
  compress = FALSE,
  covMethod = c("r", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  boundedTransform = TRUE,
  eventSens = c("jump", "fd"),
  ...
)

Arguments

npt	Number of points for bobyqa's quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to '2*n + 1'. (bobyqa)
rhobeg	Initial trust region radius for the bobyqa outer optimizer (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Default '0.2' (20 'abs(upper-lower)/2'. (bobyqa)
rhoend	Final trust region radius. If not defined, '10^(-sigdig-1)' is used. (bobyqa)
iprint	Controls amount of printing ('0'=none, '1'=start/end only, '2'=each new rho, '3'=every function evaluation, '>3'=every 'iprint' evaluations). Default '0'.
maxfun	The maximum allowed number of function evaluations. If this is exceeded, the method will terminate.
returnNewuoa	return the newuoa output instead of the nlmixr2 fit
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
boundedTransform	When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
...	Ignored parameters

Value

newuoa control structure

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="newuoa")

print(fit2)

# you can also get the nlm output with

fit2$newuoa

# The nlm control has been modified slightly to include
# extra components and name the parameters

---

nlmixr2 defaults controls for nlm

Description

nlmixr2 defaults controls for nlm

Usage

nlmControl(
  typsize = NULL,
  fscale = 1,
  print.level = 0,
  ndigit = NULL,
  gradtol = 1e-06,
  stepmax = NULL,
  steptol = 1e-06,
  iterlim = 10000,
  check.analyticals = FALSE,
  returnNlm = FALSE,
  solveType = c("hessian", "grad", "fun"),
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  eventType = c("central", "forward"),
  shiErr = (.Machine$double.eps)^(1/3),
  shi21maxFD = 20L,
  optimHessType = c("central", "forward"),
  hessErr = (.Machine$double.eps)^(1/3),
  shi21maxHess = 20L,
  eventSens = c("jump", "fd"),
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  gradTo = 1,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  addProp = c("combined2", "combined1"),
  calcTables = TRUE,
  compress = FALSE,
  covMethod = c("r", "nlm", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  boundedTransform = TRUE,
  ...
)

Arguments

typsize	an estimate of the size of each parameter at the minimum.
fscale	an estimate of the size of f at the minimum.
print.level	this argument determines the level of printing which is done during the minimization process. The default value of 0 means that no printing occurs, a value of 1 means that initial and final details are printed and a value of 2 means that full tracing information is printed.
ndigit	the number of significant digits in the function f.
gradtol	a positive scalar giving the tolerance at which the scaled gradient is considered close enough to zero to terminate the algorithm. The scaled gradient is a measure of the relative change in f in each direction p[i] divided by the relative change in p[i].
stepmax	a positive scalar which gives the maximum allowable scaled step length. stepmax is used to prevent steps which would cause the optimization function to overflow, to prevent the algorithm from leaving the area of interest in parameter space, or to detect divergence in the algorithm. stepmax would be chosen small enough to prevent the first two of these occurrences, but should be larger than any anticipated reasonable step.
steptol	A positive scalar providing the minimum allowable relative step length.
iterlim	a positive integer specifying the maximum number of iterations to be performed before the program is terminated.
check.analyticals	a logical scalar specifying whether the analytic gradients and Hessians, if they are supplied, should be checked against numerical derivatives at the initial parameter values. This can help detect incorrectly formulated gradients or Hessians.
returnNlm	is a logical that allows a return of the 'nlm' object
solveType	controls whether ‘nlm' uses nlmixr2’s analytical gradients (event-related parameters like lag time/duration/rate/F use Shi2021 finite differences instead): '"hessian"' builds a Hessian from the analytical gradient via finite differences, '"gradient"' supplies the gradient and lets 'nlm' compute the finite-difference Hessian, and '"fun"' lets 'nlm' compute both by finite differences.
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
eventType	Event gradient type for dosing events; Can be "central" or "forward"
shiErr	This represents the epsilon when optimizing the ideal step size for numeric differentiation using the Shi2021 method
shi21maxFD	The maximum number of steps for the optimization of the forward difference step size when using dosing events (lag time, modeled duration/rate and bioavailability)
optimHessType	Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).
hessErr	This represents the epsilon when optimizing the Hessian step size using the Shi2021 method.
shi21maxHess	Maximum number of times to optimize the best step size for the hessian calculation
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
gradTo	this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	"r" uses nlmixr2's 'nlmixr2Hess()' for the hessian, or "nlm" uses the hessian from 'stats::nlm(.., hessian=TRUE)'; defaults to "nlm" when using nlmixr2's hessian/gradient for solving.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
boundedTransform	When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.
...	additional arguments to be passed to f.

Value

nlm control object

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="nlm")

print(fit2)

# you can also get the nlm output with fit2$nlm

fit2$nlm

# The nlm control has been modified slightly to include
# extra components and name the parameters

---

nlmixr2 nlminb defaults

Description

nlmixr2 nlminb defaults

Usage

nlminbControl(
  eval.max = 200,
  iter.max = 150,
  trace = 0,
  abs.tol = 0,
  rel.tol = 1e-10,
  x.tol = 1.5e-08,
  xf.tol = 2.2e-14,
  step.min = 1,
  step.max = 1,
  sing.tol = rel.tol,
  scale = 1,
  scale.init = NULL,
  diff.g = NULL,
  rxControl = NULL,
  optExpression = TRUE,
  sumProd = FALSE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  returnNlminb = FALSE,
  solveType = c("hessian", "grad", "fun"),
  stickyRecalcN = 4,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  indTolRelax = TRUE,
  eventType = c("central", "forward"),
  shiErr = (.Machine$double.eps)^(1/3),
  shi21maxFD = 20L,
  optimHessType = c("central", "forward"),
  hessErr = (.Machine$double.eps)^(1/3),
  shi21maxHess = 20L,
  useColor = NULL,
  printNcol = NULL,
  print = 1L,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleC = NULL,
  scaleTo = 1,
  gradTo = 1,
  addProp = c("combined2", "combined1"),
  eventSens = c("jump", "fd"),
  calcTables = TRUE,
  compress = TRUE,
  covMethod = c("r", "nlminb", ""),
  adjObf = TRUE,
  ci = 0.95,
  sigdig = 4,
  sigdigTable = NULL,
  ...
)

Arguments

eval.max	Maximum number of evaluations of the objective function allowed. Defaults to 200.
iter.max	Maximum number of iterations allowed. Defaults to 150.
trace	The value of the objective function and the parameters is printed every trace'th iteration. When 0 no trace information is to be printed
abs.tol	Absolute tolerance. Defaults to 0 so the absolute convergence test is not used. If the objective function is known to be non-negative, the previous default of '1e-20' would be more appropriate
rel.tol	Relative tolerance. Defaults to '1e-10'.
x.tol	X tolerance. Defaults to '1.5e-8'.
xf.tol	false convergence tolerance. Defaults to '2.2e-14'.
step.min	Minimum step size. Default to '1.'.
step.max	Maximum step size. Default to '1.'.
sing.tol	singular convergence tolerance; defaults to 'rel.tol;.
scale	See PORT documentation (or leave alone).
scale.init	... probably need to check PORT documentation
diff.g	an estimated bound on the relative error in the objective function value
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
returnNlminb	logical; when TRUE this will return the nlminb result instead of the nlmixr2 fit object
solveType	controls whether ‘nlm' uses nlmixr2’s analytical gradients (event-related parameters like lag time/duration/rate/F use Shi2021 finite differences instead): '"hessian"' builds a Hessian from the analytical gradient via finite differences, '"gradient"' supplies the gradient and lets 'nlm' compute the finite-difference Hessian, and '"fun"' lets 'nlm' compute both by finite differences.
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
eventType	Event gradient type for dosing events; Can be "central" or "forward"
shiErr	This represents the epsilon when optimizing the ideal step size for numeric differentiation using the Shi2021 method
shi21maxFD	The maximum number of steps for the optimization of the forward difference step size when using dosing events (lag time, modeled duration/rate and bioavailability)
optimHessType	Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).
hessErr	This represents the epsilon when optimizing the Hessian step size using the Shi2021 method.
shi21maxHess	Maximum number of times to optimize the best step size for the hessian calculation
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
gradTo	this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: $y = f + (a + b\times f^c) \times \varepsilon$ ; or '"combined2"', where variances add: $y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$ . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
compress	Should the object have compressed items
covMethod	Method for calculating covariance, where R is the Hessian and S the sum of individual gradient cross-products (at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (2%*%solve(R)), "s" cross-product-based (4%*%solve(S)), or "" to skip the covariance step.
adjObf	is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is TRUE
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
sigdig	Optimization significant digits; controls the inner/outer optimization tolerance (10^-sigdig), ODE solver tolerance (0.5*10^(-sigdig-2), or 0.5*10^(-sigdig-1.5) for sensitivity/steady-state with liblsoda), and boundary check tolerance (5*10^(-sigdig+1)).
sigdigTable	Significant digits in the final output table. If not specified, then it matches the significant digits in the 'sigdig' optimization algorithm. If 'sigdig' is NULL, use 3.
...	Further arguments to be supplied to objective.

Author(s)

Matthew L. Fidler

Examples

# A logit regression example with emax model

dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))

mod <- function() {
 ini({
   E0 <- 0.5
   Em <- 0.5
   E50 <- 2
   g <- fix(2)
 })
 model({
   v <- E0+Em*time^g/(E50^g+time^g)
   ll(bin) ~ DV * v - log(1 + exp(v))
 })
}

fit2 <- nlmixr(mod, dsn, est="nlminb")

print(fit2)

# you can also get the nlm output with fit2$nlminb

fit2$nlminb

---

nlmixr2 fits population PK and PKPD non-linear mixed effects models.

Description

nlmixr2 is an R package for fitting population pharmacokinetic (PK) and pharmacokinetic-pharmacodynamic (PKPD) models.

Usage

nlmixr2(
  object,
  data,
  est = NULL,
  control = list(),
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

nlmixr(
  object,
  data,
  est = NULL,
  control = list(),
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

## S3 method for class ''function''
nlmixr2(
  object,
  data = NULL,
  est = NULL,
  control = NULL,
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

## S3 method for class 'rxUi'
nlmixr2(
  object,
  data = NULL,
  est = NULL,
  control = NULL,
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

## S3 method for class 'nlmixr2FitCore'
nlmixr2(
  object,
  data = NULL,
  est = NULL,
  control = NULL,
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

## S3 method for class 'nlmixr2FitData'
nlmixr2(
  object,
  data = NULL,
  est = NULL,
  control = NULL,
  table = tableControl(),
  ...,
  save = NULL,
  envir = parent.frame()
)

Arguments

object	Fitted object or function specifying the model.
data	nlmixr data
est	estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools
control	The estimation control object. These are expected to be different for each type of estimation method
table	The output table control object (like 'tableControl()')
...	Other parameters
save	Boolean to save a nlmixr2 object in a rds file in the working directory. If NULL, uses option "nlmixr2.save"
envir	Environment where the nlmixr object/function is evaluated before running the estimation routine.

Details

The nlmixr2 generalized function allows common access to the nlmixr2 estimation routines.

The nlmixr object has the following fields:

Field	Note	Description
censInfo		Gives the censorng information abot the fit (the type of censoring that was seend and handled in the dataset)
conditionNumber		Condition number, that is the highest divided by the lowest eigenvalue in the population covariance matrix
cor		Correlation matrix
cov		Variance-covariance matrix
covMethod		Method used to calculate covariance of the fixed effects
dataLloq		Gives the lloq from the dataset (average) when cesoring has occured; Requires the fit to have a table step
dataMergeFull		Full data merge with the fit output and the original dataset; Also includes nlmixrLlikObs which includes the individual observation contribution to the likelihood
dataMergeInner		Inner data merge with the fit output and the original dataset; Also includes nlmixrLlikObs which includes the individual observation contribution to the likelihood
dataMergeLeft		Left data merge with the fit output and the original dataset; Also includes nlmixrLlikObs which includes the individual observation contribution to the likelihood
dataMergeRight		Right data merge with the fit output and the original dataset; Also includes nlmixrLlikObs which includes the individual observation contribution to the likelihood
dataUloq		Gives the uloq from the dataset (average) when censoring has occured; requires the fit to have a table step
env		This is the environment where all the information for the fit is stored outside of the data-frame. It is an R environment hence $env
runInfo		This returns a list of all the warnings or fit information
rxControl		Integration options used to control rxode2
scaleInfo		The scaling factors used for nlmixr2 estimation in focei; The can be changed by foceiControl(scaleC=...) if you think these are unreasonable. It also tells the Gill83 outcome of trying to find the best step size (High gradient error, bad gradient etc)
seed		This is the initial seed used for saem
shrink		This is a table of shrinkages for all the individual ETAs as well as the variance shrinkage as well as summary statistics for the ETAs and Residual Error
simInfo		This returns a list of all the fit information used for a traditional rxode2 simulation, which you can tweak yourself if you wish
table		These are the table options that were used when generating the table output (were CWRES included, etc
theta		Estimates for eta for each individual
time		Duration of different parts of the analysis (e.g. setup, optimization, calculation of covariance, etc.)
ui		Final estimates for the model
atol	n2r	Absolute tolerance that NONMEM specified; will be used when solving
dfObs	n2r	Degrees of freedom by observation
dfSub	n2r	Degrees of freedom by subject
etaData	n2r	Subject level IIV values
ipredAtol	n2r	Absolute tolerance difference between NONMEM and rxode2 individual predictions
ipredCompare	n2r	Data frame with ipred values
ipredRtol	n2r	Relative tolerance difference between NONMEM and rxode2 individual predictions
nonmemData	n2r	Original dataset used for NONMEM analysis
predAtol	n2r	Absolute tolerance difference between NONMEM and rxode2 population predictions
predCompare	n2r	Data frame with pred values
predRtol	n2r	Relative tolerance difference between NONMEM and rxode2 population predictions
rtol	n2r	Relative tolerance that NONMEM specified; will be used when solving
sigma	n2r	Error model matrix
ssAtol	n2r	Steady state absolute tolerance that NONMEM specified; will be used for solving.
ssRtol	n2r	Steady state relative tolerance that NONMEM specified will be used for solving
thetaMat	n2r	Covariance Matrix (matches rxSolve(thetaMat=)

n2r - These fields are added when a NONMEM model is imported using nonmem2rx()

Value

Either a nlmixr2 model or a nlmixr2 fit object

nlmixr modeling mini-language

Rationale

nlmixr estimation routines each have their own way of specifying models. Often the models are specified in ways that are most intuitive for one estimation routine, but do not make sense for another estimation routine. Sometimes, legacy estimation routines like nlme have their own syntax that is outside of the control of the nlmixr package.

The unique syntax of each routine makes the routines themselves easier to maintain and expand, and allows interfacing with existing packages that are outside of nlmixr (like nlme). However, a model definition language that is common between estimation methods, and an output object that is uniform, will make it easier to switch between estimation routines and will facilitate interfacing output with external packages like Xpose.

The nlmixr mini-modeling language, attempts to address this issue by incorporating a common language. This language is inspired by both R and NONMEM, since these languages are familiar to many pharmacometricians.

Initial Estimates and boundaries for population parameters

nlmixr models are contained in a R function with two blocks: ini and model. This R function can be named anything, but is not meant to be called directly from R. In fact if you try you will likely get an error such as Error: could not find function "ini".

The ini model block is meant to hold the initial estimates for the model, and the boundaries of the parameters for estimation routines that support boundaries (note nlmixr's saem and nlme do not currently support parameter boundaries).

To explain how these initial estimates are specified we will start with an annotated example:

f <- function(){ ## Note the arguments to the function are currently
                 ## ignored by nlmixr
    ini({
        ## Initial conditions for population parameters (sometimes
        ## called theta parameters) are defined by either `<-` or '='
        lCl <- 1.6      #log Cl (L/hr)
        ## Note that simple expressions that evaluate to a number are
        ## OK for defining initial conditions (like in R)
        lVc = log(90)  #log V (L)
        ## Also a comment on a parameter is captured as a parameter label
        lKa <- 1 #log Ka (1/hr)
        ## Bounds may be specified by c(lower, est, upper), like NONMEM:
        ## Residuals errors are assumed to be population parameters
        prop.err <- c(0, 0.2, 1)
    })
    ## The model block will be discussed later
    model({})
}

As shown in the above examples:

• Simple parameter values are specified as a R-compatible assignment

• Boundaries my be specified by c(lower, est, upper).

• Like NONMEM, c(lower,est) is equivalent to c(lower,est,Inf)

• Also like NONMEM, c(est) does not specify a lower bound, and is equivalent to specifying the parameter without R's 'c' function.

• The initial estimates are specified on the variance scale, and in analogy with NONMEM, the square roots of the diagonal elements correspond to coefficients of variation when used in the exponential IIV implementation

These parameters can be named almost any R compatible name. Please note that:

• Residual error estimates should be coded as population estimates (i.e. using an '=' or '<-' statement, not a '~').

• Naming variables that start with "_" are not supported. Note that R does not allow variable starting with "_" to be assigned without quoting them.

• Naming variables that start with "rx_" or "nlmixr_" is not supported since rxode2 and nlmixr2 use these prefixes internally for certain estimation routines and calculating residuals.

• Variable names are case sensitive, just like they are in R. "CL" is not the same as "Cl".

Initial Estimates for between subject error distribution (NONMEM's $OMEGA)

In mixture models, multivariate normal individual deviations from the population parameters are estimated (in NONMEM these are called eta parameters). Additionally the variance/covariance matrix of these deviations is also estimated (in NONMEM this is the OMEGA matrix). These also have initial estimates. In nlmixr these are specified by the '~' operator that is typically used in R for "modeled by", and was chosen to distinguish these estimates from the population and residual error parameters.

Continuing the prior example, we can annotate the estimates for the between subject error distribution

f <- function(){
    ini({
        lCl <- 1.6      #log Cl (L/hr)
        lVc = log(90)  #log V (L)
        lKa <- 1 #log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        ## Initial estimate for ka IIV variance
        ## Labels work for single parameters
        eta.ka ~ 0.1 # BSV Ka

        ## For correlated parameters, you specify the names of each
        ## correlated parameter separated by a addition operator `+`
        ## and the left handed side specifies the lower triangular
        ## matrix initial of the covariance matrix.
        eta.cl + eta.vc ~ c(0.1,
                            0.005, 0.1)
        ## Note that labels do not currently work for correlated
        ## parameters.  Also do not put comments inside the lower
        ## triangular matrix as this will currently break the model.
    })
    ## The model block will be discussed later
    model({})
}

As shown in the above examples:

• Simple variances are specified by the variable name and the estimate separated by '~'.

• Correlated parameters are specified by the sum of the variable labels and then the lower triangular matrix of the covariance is specified on the left handed side of the equation. This is also separated by '~'.

Currently the model syntax does not allow comments inside the lower triangular matrix.

Model Syntax for ODE based models (NONMEM's $PK, $PRED, $DES and $ERROR)

Once the initialization block has been defined, you can define a model in terms of the defined variables in the ini block. You can also mix in RxODE blocks into the model.

The current method of defining a nlmixr model is to specify the parameters, and then possibly the RxODE lines:

Continuing describing the syntax with an annotated example:

f <- function(){
    ini({
        lCl <- 1.6      #log Cl (L/hr)
        lVc <- log(90)   #log Vc (L)
        lKA <- 0.1      #log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        eta.Cl ~ 0.1 ## BSV Cl
        eta.Vc ~ 0.1 ## BSV Vc
        eta.KA ~ 0.1 ## BSV Ka
    })
    model({
        ## First parameters are defined in terms of the initial estimates
        ## parameter names.
        Cl <- exp(lCl + eta.Cl)
        Vc = exp(lVc + eta.Vc)
        KA <- exp(lKA + eta.KA)
        ## After the differential equations are defined
        kel <- Cl / Vc;
        d/dt(depot)    = -KA*depot;
        d/dt(centr)  =  KA*depot-kel*centr;
        ## And the concentration is then calculated
        cp = centr / Vc;
        ## Last, nlmixr is told that the plasma concentration follows
        ## a proportional error (estimated by the parameter prop.err)
        cp ~ prop(prop.err)
    })
}

A few points to note:

• Parameters are often defined before the differential equations.

• The differential equations, parameters and error terms are in a single block, instead of multiple sections.

• State names, calculated variables cannot start with either "rx_" or "nlmixr_" since these are used internally in some estimation routines.

• Errors are specified using the '~'. Currently you can use either add(parameter) for additive error, prop(parameter) for proportional error or add(parameter1) + prop(parameter2) for additive plus proportional error. You can also specify norm(parameter) for the additive error, since it follows a normal distribution.

• Some routines, like saem require parameters in terms of Pop.Parameter + Individual.Deviation.Parameter + Covariate*Covariate.Parameter. The order of these parameters do not matter. This is similar to NONMEM's mu-referencing, though not quite so restrictive.

• The type of parameter in the model is determined by the initial block; Covariates used in the model are missing in the ini block. These variables need to be present in the modeling dataset for the model to run.

Model Syntax for solved PK systems

Solved PK systems are also currently supported by nlmixr with the 'linCmt()' pseudo-function. An annotated example of a solved system is below:

##'

f <- function(){
    ini({
        lCl <- 1.6      #log Cl (L/hr)
        lVc <- log(90)   #log Vc (L)
        lKA <- 0.1      #log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        eta.Cl ~ 0.1 ## BSV Cl
        eta.Vc ~ 0.1 ## BSV Vc
        eta.KA ~ 0.1 ## BSV Ka
    })
    model({
        Cl <- exp(lCl + eta.Cl)
        Vc = exp(lVc + eta.Vc)
        KA <- exp(lKA + eta.KA)
        ## Instead of specifying the ODEs, you can use
        ## the linCmt() function to use the solved system.
        ##
        ## This function determines the type of PK solved system
        ## to use by the parameters that are defined.  In this case
        ## it knows that this is a one-compartment model with first-order
        ## absorption.
        linCmt() ~ prop(prop.err)
    })
}

A few things to keep in mind:

• While RxODE allows mixing of solved systems and ODEs, this has not been implemented in nlmixr yet.

• The solved systems implemented are the one, two and three compartment models with or without first-order absorption. Each of the models support a lag time with a tlag parameter.

• In general the linear compartment model figures out the model by the parameter names. nlmixr currently knows about numbered volumes, Vc/Vp, Clearances in terms of both Cl and Q/CLD. Additionally nlmixr knows about elimination micro-constants (ie K12). Mixing of these parameters for these models is currently not supported.

Checking model syntax

After specifying the model syntax you can check that nlmixr is interpreting it correctly by using the nlmixr function on it.

Using the above function we can get:

> nlmixr(f)
## 1-compartment model with first-order absorption in terms of Cl
## Initialization:
################################################################################
Fixed Effects ($theta):
    lCl     lVc     lKA
1.60000 4.49981 0.10000

Omega ($omega):
     [,1] [,2] [,3]
[1,]  0.1  0.0  0.0
[2,]  0.0  0.1  0.0
[3,]  0.0  0.0  0.1

## Model:
################################################################################
Cl <- exp(lCl + eta.Cl)
Vc = exp(lVc + eta.Vc)
KA <- exp(lKA + eta.KA)
## Instead of specifying the ODEs, you can use
## the linCmt() function to use the solved system.
##
## This function determines the type of PK solved system
## to use by the parameters that are defined.  In this case
## it knows that this is a one-compartment model with first-order
## absorption.
linCmt() ~ prop(prop.err)

In general this gives you information about the model (what type of solved system/RxODE), initial estimates as well as the code for the model block.

Using the model syntax for estimating a model

Once the model function has been created, you can use it and a dataset to estimate the parameters for a model given a dataset.

This dataset has to have RxODE compatible events IDs. Both Monolix and NONMEM use a a very similar standard to what nlmixr can support.

Once the data has been converted to the appropriate format, you can use the nlmixr function to run the appropriate code.

The method to estimate the model is:

fit <- nlmixr(model.function, dataset, est="est", control=estControl(options))

Currently nlme and saem are implemented. For example, to run the above model with saem, we could have the following:

> f <- function(){
    ini({
        lCl <- 1.6      #log Cl (L/hr)
        lVc <- log(90)   #log Vc (L)
        lKA <- 0.1      #log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        eta.Cl ~ 0.1 ## BSV Cl
        eta.Vc ~ 0.1 ## BSV Vc
        eta.KA ~ 0.1 ## BSV Ka
    })
    model({
        ## First parameters are defined in terms of the initial estimates
        ## parameter names.
        Cl <- exp(lCl + eta.Cl)
        Vc = exp(lVc + eta.Vc)
        KA <- exp(lKA + eta.KA)
        ## After the differential equations are defined
        kel <- Cl / Vc;
        d/dt(depot)    = -KA*depot;
        d/dt(centr)  =  KA*depot-kel*centr;
        ## And the concentration is then calculated
        cp = centr / Vc;
        ## Last, nlmixr is told that the plasma concentration follows
        ## a proportional error (estimated by the parameter prop.err)
        cp ~ prop(prop.err)
    })
}
> fit.s <- nlmixr(f,d,est="saem",control=saemControl(n.burn=50,n.em=100,print=50));
Compiling RxODE differential equations...done.
c:/Rtools/mingw_64/bin/g++  -I"c:/R/R-34~1.1/include" -DNDEBUG     -I"d:/Compiler/gcc-4.9.3/local330/include"  -Ic:/nlmixr/inst/include -Ic:/R/R-34~1.1/library/STANHE~1/include -Ic:/R/R-34~1.1/library/Rcpp/include -Ic:/R/R-34~1.1/library/RCPPAR~1/include -Ic:/R/R-34~1.1/library/RCPPEI~1/include -Ic:/R/R-34~1.1/library/BH/include   -O2 -Wall  -mtune=core2 -c saem3090757b4bd1x64.cpp -o saem3090757b4bd1x64.o
In file included from c:/R/R-34~1.1/library/RCPPAR~1/include/armadillo:52:0,
                 from c:/R/R-34~1.1/library/RCPPAR~1/include/RcppArmadilloForward.h:46,
                 from c:/R/R-34~1.1/library/RCPPAR~1/include/RcppArmadillo.h:31,
                 from saem3090757b4bd1x64.cpp:1:
c:/R/R-34~1.1/library/RCPPAR~1/include/armadillo_bits/compiler_setup.hpp:474:96: note: #pragma message: WARNING: use of OpenMP disabled; this compiler doesn't support OpenMP 3.0+
   #pragma message ("WARNING: use of OpenMP disabled; this compiler doesn't support OpenMP 3.0+")
                                                                                                ^
c:/Rtools/mingw_64/bin/g++ -shared -s -static-libgcc -o saem3090757b4bd1x64.dll tmp.def saem3090757b4bd1x64.o c:/nlmixr/R/rx_855815def56a50f0e7a80e48811d947c_x64.dll -Lc:/R/R-34~1.1/bin/x64 -lRblas -Lc:/R/R-34~1.1/bin/x64 -lRlapack -lgfortran -lm -lquadmath -Ld:/Compiler/gcc-4.9.3/local330/lib/x64 -Ld:/Compiler/gcc-4.9.3/local330/lib -Lc:/R/R-34~1.1/bin/x64 -lR
done.
1:    1.8174   4.6328   0.0553   0.0950   0.0950   0.0950   0.6357
50:    1.3900   4.2039   0.0001   0.0679   0.0784   0.1082   0.1992
100:    1.3894   4.2054   0.0107   0.0686   0.0777   0.1111   0.1981
150:    1.3885   4.2041   0.0089   0.0683   0.0778   0.1117   0.1980
Using sympy via SnakeCharmR
## Calculate ETA-based prediction and error derivatives:
Calculate Jacobian...................done.
Calculate sensitivities.......
done.
## Calculate d(f)/d(eta)
## ...
## done
## ...
## done
The model-based sensitivities have been calculated
Calculating Table Variables...
done

The options for saem are controlled by saemControl. You may wish to make sure the minimization is complete in the case of saem. You can do that with traceplot which shows the iteration history with the divided by burn-in and EM phases. In this case, the burn in seems reasonable; you may wish to increase the number of iterations in the EM phase of the estimation. Overall it is probably a semi-reasonable solution.

nlmixr output objects

In addition to unifying the modeling language sent to each of the estimation routines, the outputs currently have a unified structure.

You can see the fit object by typing the object name:

> fit.s
 -- nlmixr SAEM fit (ODE); OBJF calculated from FOCEi approximation -------------
      OBJF      AIC      BIC Log-likelihood Condition Number
  62337.09 62351.09 62399.01      -31168.55          82.6086

 -- Time (sec; fit.s$time): -----------------------------------------------------
           saem setup Likelihood Calculation covariance table
 elapsed 430.25 31.64                   1.19          0  3.44

 -- Parameters (fit.s$par.fixed): -----------------------------------------------
              Parameter Estimate     SE  
 lCl      log Cl (L/hr)     1.39 0.0240  1.73       4.01 (3.83, 4.20)    26.6
 lVc         log Vc (L)     4.20 0.0256 0.608       67.0 (63.7, 70.4)    28.5
 lKA      log Ka (1/hr)  0.00924 0.0323  349.      1.01 (0.947, 1.08)    34.3
 prop.err      prop.err    0.198                             19.8
          Shrink(SD)
 lCl          0.248
 lVc           1.09
 lKA           4.19
 prop.err      1.81

   No correlations in between subject variability (BSV) matrix
   Full BSV covariance (fit.s$omega) or correlation (fit.s$omega.R; diagonals=SDs)
   Distribution stats (mean/skewness/kurtosis/p-value) available in fit.s$shrink

 -- Fit Data (object fit.s is a modified data.frame): ---------------------------
 # A tibble: 6,947 x 22
   ID     TIME    DV  PRED    RES    WRES IPRED  IRES  IWRES CPRED   CRES
 * <fct> <dbl> <dbl> <dbl>  <dbl>   <dbl> <dbl> <dbl>  <dbl> <dbl>  <dbl>
 1 1      0.25  205.  198.   6.60  0.0741  189.  16.2  0.434  198.   6.78
 2 1      0.5   311.  349. -38.7  -0.261   330. -19.0 -0.291  349. -38.3
 3 1      0.75  389.  464. -74.5  -0.398   434. -45.2 -0.526  463. -73.9
 # ... with 6,944 more rows, and 11 more variables: CWRES <dbl>, eta.Cl <dbl>,
 #   eta.Vc <dbl>, eta.KA <dbl>, depot <dbl>, centr <dbl>, Cl <dbl>, Vc <dbl>,
 #   KA <dbl>, kel <dbl>, cp <dbl>

This example shows what is typical printout of a nlmixr fit object. The elements of the fit are:

• The type of fit (nlme, saem, etc)

• Metrics of goodness of fit (AIC, BIC, and logLik).

  • To align the comparison between methods, the FOCEi likelihood objective is calculated regardless of the method used and used for goodness of fit metrics.

  • This FOCEi likelihood has been compared to NONMEM's objective function and gives the same values (based on the data in Wang 2007)

  • Also note that saem does not calculate an objective function, and the FOCEi is used as the only objective function for the fit.

  • Even though the objective functions are calculated in the same manner, caution should be used when comparing fits from various estimation routines.

• The next item is the timing of each of the steps of the fit.

  • These can be also accessed by (fit.s$time).

  • As a mnemonic, the access for this item is shown in the printout. This is true for almost all of the other items in the printout.

• After the timing of the fit, the parameter estimates are displayed (can be accessed by fit.s$par.fixed)

  • While the items are rounded for R printing, each estimate without rounding is still accessible by the '$' syntax. For example, the '$Untransformed' gives the untransformed parameter values.

  • The Untransformed parameter takes log-space parameters and back-transforms them to normal parameters. Not the CIs are listed on the back-transformed parameter space.

  • Proportional Errors are converted to

• Omega block (accessed by fit.s$omega)

• The table of fit data. Please note:

  • A nlmixr fit object is actually a data frame. Saving it as a Rdata object and then loading it without nlmixr will just show the data by itself. Don't worry; the fit information has not vanished, you can bring it back by simply loading nlmixr, and then accessing the data.

  • Special access to fit information (like the $omega) needs nlmixr to extract the information.

  • If you use the $ to access information, the order of precedence is:

    • Fit data from the overall data.frame

    • Information about the parsed nlmixr model (via $uif)

    • Parameter history if available (via $par.hist and $par.hist.stacked)

    • Fixed effects table (via $par.fixed)

    • Individual differences from the typical population parameters (via $eta)

    • Fit information from the list of information generated during the post-hoc residual calculation.

    • Fit information from the environment where the post-hoc residual were calculated

    • Fit information about how the data and options interacted with the specified model (such as estimation options or if the solved system is for an infusion or an IV bolus).

  • While the printout may displays the data as a data.table object or tbl object, the data is NOT any of these objects, but rather a derived data frame.

  • Since the object is a data.frame, you can treat it like one.

In addition to the above properties of the fit object, there are a few additional that may be helpful for the modeler:

• $theta gives the fixed effects parameter estimates (in NONMEM the thetas). This can also be accessed in fixed.effects function. Note that the residual variability is treated as a fixed effect parameter and is included in this list.

• $eta gives the random effects parameter estimates, or in NONMEM the etas. This can also be accessed in using the random.effects function.

Author(s)

Matthew L. Fidler

Examples

one.cmt <- function() {
 ini({
   ## You may label each parameter with a comment
   tka <- 0.45 # Ka
   tcl <- log(c(0, 2.7, 100)) # Log Cl
   ## This works with interactive models
   ## You may also label the preceding line with label("label text")
   tv <- 3.45; label("log V")
   ## the label("Label name") works with all models
   eta.ka ~ 0.6
   eta.cl ~ 0.3
   eta.v ~ 0.1
   add.sd <- 0.7
   prop.sd <- 0.01
 })
 model({
   ka <- exp(tka + eta.ka)
   cl <- exp(tcl + eta.cl)
   v <- exp(tv + eta.v)
   linCmt() ~ add(add.sd) + prop(prop.sd)
 })
}

# fitF <- nlmixr(one.cmt, theo_sd, "focei")

fitS <- nlmixr(one.cmt, theo_sd, "saem")

---