Package {babelmixr2}

parameter to evaluate

Observation times vector (unused; kept for formula compatibility – the solver uses the resident per-subject event data)

Individual-level parameter vectors (one per param in saemParamsToEstimate)

environment in poped environment

poped DB with babelmixr2 issue

environment with setup information for popEd

global environment for poped info

setup the full model

parameters (includes covariates and modeling times)

unique times sampled

original unsorted time (to match the f/w against)

model switch parameter integer starting with 1 (related to dvid in rxode2)

specifies the number of endpoints in this model

this is the design identifier

This is the total number of design points tested

poped DB with babelmixr2 issue

parameter to evaluate

rxode2 ui function

babelmixr2 design data

PopED control

Object to convert

Other arguments

is the nlmixr2est::tableControl() options

is the rxode2::rxControl() options, which is generally needed for how addl doses are handled in the translation

is the confidence interval of the residual differences calculated (by default 0.95)

The babelmixr2 generated PopED database

other parameters sent to PopED::create.poped.database()

boolean to indicate if the global time indexer inside of babelmixr2 is reset if the times are different. By default this is TRUE. If FALSE you can get slightly better run times and possibly slightly different results. When optTime is FALSE the global indexer is reset every time the PopED rxode2 is setup for a problem or when a poped dataset is created. You can manually reset with popedMultipleEndpointResetTimeIndex()

The babelmixr2 created database

variable to query

rxode2 model for conversion

Input dataset.

is the table control; this is mostly to figure out if there are additional columns to keep.

is the rxode2 control options; This is to figure out how to handle the addl dosing information.

When NULL (default) nothing is done. When an environment, the function nlmixr2est::.foceiPreProcessData(data, env, model, rxControl) is called on the provided environment.

jump length, either a number, a vector with length equal to the total number of parameters, a covariance matrix, or a function that takes as input the current values of the parameters and produces as output the perturbed parameters. See details.

-2 * log(prior parameter probability), either a function called as prior(p) with the parameter vector FME::modMCMC() samples (which is the scaled space when scaleType rescales the parameters), or NULL for a non-informative prior. When the model declares priors in its ini({}) block (for example prior(tka) ~ dnorm(0, 10)) this function is generated from them, evaluated on the natural (unscaled) parameter scale, and prior must be left NULL; supplying both is an error.

number of iterations for the MCMC.

number of iterations kept in the output; should be smaller or equal to niter.

number of initial iterations to be removed from output.

number of iterations after which the parameter covariance matrix is (re)evaluated based on the parameters kept thus far, and used to update the MCMC jumps.

scale factor for the parameter covariance matrix, used to perform the MCMC jumps.

maximal number of tries for the delayed rejection procedure. It is generally not a good idea to set this to a too large value.

for each try during delayed rejection, the cholesky decomposition of the proposal matrix is scaled with this amount; if NULL, it is assumed to be c(0.2,0.25, 0.333, 0.333, ...)

if TRUE or 1: prints extra output, if numeric value i > 1, prints status information every i iterations.

an integer seed used for the mcmc chain. The chain is fully determined by this seed, so a fixed value makes the fit reproducible. The run is wrapped in rxode2::rxWithSeed(), which restores the prior random number generator state afterward, so seeding the fit does not disturb the calling session's stream. Vary this to explore different chains.

return the fmeMcmc output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

when TRUE (default) a subject whose ODE solve had to be retried with a relaxed tolerance keeps that relaxed tolerance for the rest of the fit instead of resetting it every evaluation

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

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)'.

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).

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.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

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.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

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).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r,s" (the default) is the sandwich estimator (see below). "analytic" uses the exact analytic observed-information R-matrix (reported as R^{-1}) and additionally returns the residual and Omega standard errors; it covers FOCEI/FOCE fits with additive, proportional, or combined error, mu-referenced/covariate/other structural parameters (and non-mu-referenced etas), and SD-scale inter-occasion variability, and emits a message and falls back to the finite-difference Hessian for anything out of scope (FO, nAGQ > 1, censoring, DV-transformed error, bounded-parameter transforms, a structural theta shared by two etas, non-SD iovXform, or a pure-proportional variance that vanishes at a near-zero prediction). The finite-difference methods use R (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 (solve(R)), "s" cross-product-based (solve(S)), or "" to skip the covariance step. "sa" (SAEM Louis stochastic-approximation FIM) and "imp" (importance-sampling Monte-Carlo observed information) are also accepted for any method; they are computed post-fit at the converged estimates by the decoupled recompute engine.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.

method used for the dosing-parameter (alag/F/rate/dur) sensitivities: "jump" routes them through rxode2's analytic event jumps; "fd" falls back to Shi2021 finite differences. See nlmixr2est::nlmControl().

Ignored parameters

A data.frame as the source for column names

The units for the DV, AMT, and TIME columns in the data

The units for the volume parameters in the model

Number of steady state doses (default 7)

Use linearization for log likelihood and fim.

boolean for using the stiff ODE solver

How a linCmt() model is written for Monolix: "pkmodel" uses Monolix's closed-form pkmodel() macro when the model allows it and otherwise translates the model to ODEs; "ode" always translates the model to ODEs (with rxode2::linToOde())

How if/⁠else⁠ statements are written for Monolix: "auto" (default) writes if/elseif/⁠else⁠ statements as Monolix if blocks and prunes the if/⁠else⁠ branches only when the model uses ifelse() (which Monolix cannot write); TRUE always prunes a model with if/⁠else⁠ statements and FALSE never prunes. Pruning uses rxode2's branch pruning, which writes each branch as an arithmetic expression. A pruned fit contains the pruned model.

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).

logical to turn on or off exploratory phase auto-stop of SAEM (default 250)

Boolean indicating if the smoothing should automatically stop (default FALSE)

Number of burn in iterations

Number of smoothing iterations

Number of iterations for exploratory phase (default 250)

Number of simulating annealing iterations

Minimum number of iterations in the exploratory phase (default 200)

Convergence memory in the exploratory phase (only used when exploratoryAutoStop is TRUE)

Proportional rate on variance for simulated annealing

Proportional rate on error model for simulated annealing

This describes the methodology for parameters without variability. It could be: - Fixed throughout (none) - Variability in the first stage (firstStage) - Decreasing until it reaches the fixed value (decreasing)

is a shell command or function to run monolix; You can specify the default by options("babelmixr2.monolix"="runMonolix"). If it is empty and 'lixoftConnectors' is available, use lixoftConnectors to run monolix. See details for function usage.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

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.

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.

Boolean indicating if the absolute path should be used for the monolix runs

Model name used to generate the NONMEM output. If NULL try to infer from the model name (could be x if not clear). Otherwise use this character for outputs.

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".

Should monolix be run and the results be imported to nlmixr2? (Default is TRUE)

Ignored parameters

Environment for the nlmixr2 estimation routines.

This needs to have:

- rxode2 ui object in '$ui'

- data to fit in the estimation routine in '$data'

- control for the estimation routine's control options in '$ui'

Other arguments provided to 'nlmixr2Est()' provided for flexibility but not currently used inside nlmixr

Environment for the nlmixr2 estimation routines.

This needs to have:

- rxode2 ui object in '$ui'

- data to fit in the estimation routine in '$data'

- control for the estimation routine's control options in '$ui'

Other arguments provided to 'nlmixr2Est()' provided for flexibility but not currently used inside nlmixr

passed to lme4::nlmerControl(): optimizer to use

passed to lme4::nlmerControl(): tolerance for the penalized, weighted residual sum-of-squares (PWRSS) inner iterations. When NULL (the default) it is derived from sigdig, keeping the lme4 default of 1e-7 at the default sigdig = 4 and tightening/loosening it one order of magnitude per significant digit

a list of additional control parameters passed to the nonlinear optimizer via lme4::nlmerControl()

logical; when TRUE return the raw lme4 nlmerMod object instead of the nlmixr2 fit

logical; when TRUE apply mu2 covariate referencing algebraic transformation (same as saem)

method used for the dosing-parameter (alag/F/rate/dur) sensitivities in the analytic gradient model: "jump" routes them through rxode2's analytic event jumps; "fd" falls back to Shi2021 finite differences. See nlmixr2est::nlmControl().

finite-difference type ("central" or "forward") used for event-related parameters when eventSens = "fd"

epsilon used when optimizing the ideal finite-difference step size with the Shi2021 method

maximum number of Shi2021 step-size optimization iterations for the gradient

number of bad ODE solves tolerated before the per-subject tolerance is stickily relaxed

maximum number of times to retry a bad ODE solve with a relaxed tolerance

factor by which atol/rtol are relaxed on an ODE solve retry

when TRUE (default) a subject whose ODE solve had to be retried with a relaxed tolerance keeps that relaxed tolerance for the rest of the fit instead of resetting it every evaluation

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

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)'.

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

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.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.

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).

Ignored parameters

Parsed rxode2 model environment

Parsed rxode2 model environment

NONMEM estimation method: "focei" (METHOD=1 INTER), "imp" (importance sampling, METHOD=IMP INTERACTION), "its" (iterative two stage, METHOD=ITS INTERACTION) or "posthoc" (METHOD=0 MAXEVALS=0 POSTHOC)

The ODE solving method for NONMEM

How a linCmt() model is written for NONMEM: "advan" uses NONMEM's closed-form solutions (ADVAN1-ADVAN4, ADVAN11 or ADVAN12 with TRANS1 micro-constants) when the model allows it and otherwise translates the model to ODEs; "ode" always translates the model to ODEs (with rxode2::linToOde()) and solves it with advanOde

How if/⁠else⁠ statements are written for NONMEM: "auto" (default) writes a model whose if blocks are simple (no ⁠else⁠, ⁠else if⁠, nesting or ifelse()) as NONMEM IF blocks, and otherwise prunes the if/⁠else⁠ branches; TRUE always prunes a model with if/⁠else⁠ statements and FALSE never prunes (so NONMEM can only use simple if blocks). Pruning uses rxode2's branch pruning (the same pruning nlmixr2 uses for its symbolic derivatives), which writes each branch as an arithmetic expression; this allows the nested if/⁠else if⁠/⁠else⁠ statements NONMEM models cannot otherwise use. A pruned fit contains the pruned model.

The NONMEM covariance method; "" skips the covariance step

NONMEM's maxeval (for non posthoc methods)

NONMEM tolerance for ODE solving advan

NONMEM absolute tolerance for ODE solving

NONMEM tolerance for steady state ODE solving

NONMEM absolute tolerance for steady state ODE solving

NONMEM sigl estimation option

the significant digits for NONMEM

The print number for NONMEM

NONMEM file extensions

Extension to use for the NONMEM output listing

Command to run NONMEM (typically the path to "nmfe75") or a function. See the details for more information.

How many significant digits are printed in $THETA and $OMEGA when the estimate is zero. Also controls the zero protection numbers

Add babelmixr2's own code to protect divide by zero (and the domains of log(), sqrt() and similar functions) in the control stream. This is only used when protect=FALSE (for example with NONMEM before 7.4); with protect=TRUE, NONMEM's ⁠$ABBR PROTECT⁠ protects these instead

Add ⁠$ABBR PROTECT⁠ to the control stream so NM-TRAN replaces LOG, EXP, SQRT, division and powers with NONMEM's protected functions (PLOG, PEXP, PSQRT, PDZ); this requires NONMEM 7.4 or later. The default comes from the babelmixr2.nmProtect option, which is TRUE when unset

Automatically mu-reference the control stream

Passed to nlmixr2est::foceiControl

Options to pass to rxode2::rxControl for simulations

Try to read NONMEM output when NONMEM terminated due to rounding errors

Try to read NONMEM output when NONMEM terminated due to an apparent failed optimization

number of iterations in NONMEM estimation methods

Isample argument for NONMEM IMP estimation method

Iaccept for NONMEM IMP estimation method

parameter for IMP NONMEM method (ISCALE_MIN)

parameter for IMP NONMEM method (ISCALE_MAX)

degrees of freedom for IMP method

is the seed for NONMEM methods

the number of map iterations for IMP method

is the MAPINTER parameter for the IMP method

Add the NOABORT option for ⁠$EST⁠

Model name used to generate the NONMEM output. If NULL try to infer from the model name (could be x if not clear). Otherwise use this character for outputs.

This controls if algebraic expressions that can be mu-referenced are treated as mu-referenced covariates by:

1. Creating a internal data-variable 'nlmixrMuDerCov#' for each algebraic mu-referenced expression

2. Change the algebraic expression to 'nlmixrMuDerCov# * mu_cov_theta'

3. Use the internal mu-referenced covariate for saem

4. After optimization is completed, replace 'model()' with old 'model()' expression

5. Remove 'nlmixrMuDerCov#' from nlmix2 output

In general, these covariates should be more accurate since it changes the system to a linear compartment model. Therefore, by default this is 'TRUE'.

Should NONMEM be run (and the files imported to nlmixr2); default is TRUE, but FALSE will simply create the NONMEM control stream and data file.

optional genRxControl argument controlling automatic rxControl generation.

concentration, dose, and time units from the source data (passed to PKNCA::pknca_units_table()).

compartment volume for the model (if NULL, simplified units from source data will be used)

Multipliers for vc and cl to provide initial estimates for vp, q, vp2, and q2

The parameter name in the model that should be modified for concentration unit conversions. It must be assigned on a line by itself, separate from the residual error model line.

Grouping columns for NCA summaries by group (required if sparse = TRUE)

Are the concentration-time data sparse PK (commonly used in small nonclinical species or with terminal or difficult sampling) or dense PK (commonly used in clinical studies or larger nonclinical species)?

Data to use for calculating NCA parameters. Typical use is when a subset of the original data are informative for NCA.

Already computed NCA results (a PKNCAresults object) to bypass automatic calculations. At least the following parameters must be calculated in the NCA: cmax.dn, cl.last, and tmax (without tmax, ka is not updated)

Control options sent to rxode2::rxControl()

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

Maximum number of design points for optimization; By default this is declared by the maximum number of design points in the babelmixr2 dataset (when NULL)

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Significant digits used to derive the ODE solver tolerances when rxControl is not supplied. The tolerances are fixed here rather than taken from rxode2::rxControl(sigdig=) so they do not change with the rxode2 version: atol/rtol are 0.5*10^(-sigdig-2), the sensitivity tolerances are 0.5*10^(-sigdig-1.5), the steady-state tolerances are 0.5*10^(-sigdig) and the steady-state sensitivity tolerances are 0.5*10^(-sigdig+0.625). PopED computes the FIM by finite differences (see hm1 and hm2), so the ODE solve must be much more accurate than those step sizes.

character vector of important parameters or NULL for default. This is used with Ds-optimality

character vector of unimportant parameters or NULL for default. This is used with Ds-optimality

can be either an integer or a named value of the Fisher Information Matrix type:

• 0/"full" = Full FIM

• 1/"reduced" = Reduced FIM

• 2/"weighted" = weighted models

• 3/"loc" = Loc models

• 4/"reducedPFIM" = reduced FIM with derivative of SD of sigma as in PFIM

• 5/"fullABC" = FULL FIM parameterized with A,B,C matrices & derivative of variance

• 6/"largeMat" = Calculate one model switch at a time, good for large matrices

• 7/"reducedFIMABC" = =Reduced FIM parameterized with A,B,C matrices & derivative of variance

Approximation method for model, 0=FO, 1=FOCE, 2=FOCEI, 3=FOI

integer; number of individuals in focei solve

matrix; prior FIM

integer or character option:

• 0/"ed" = ED design

• 1/"d" = D design

objective calculation type:

• 1/"d" = D-optimality". Determinant of the FIM: det(FIM)

• 2/"a" = "A-optimality". Inverse of the sum of the expected parameter variances: 1/trace_matrix(inv(FIM))

• 4/"lnD" = "lnD-optimality". Natural logarithm of the determinant of the FIM: log(det(FIM))

• 6/"Ds" = "Ds-optimality". Ratio of the Determinant of the FIM and the Determinant of the uninteresting rows and columns of the FIM: det(FIM)/det(FIM_u)

• 7/"inverse" = Inverse of the sum of the expected parameter RSE: 1/sum(get_rse(FIM,poped.db,use_percent=FALSE))

Penalty function name or path and filename, empty string means no penalty. User defined criterion can be defined this way.

User defined function used to compute the objective function. The function must have a poped database object as its first argument and have "..." in its argument list. Can be referenced as a function or as a file name where the function defined in the file has the same name as the file. e.g. "cost.txt" has a function named "cost" in it.

ED Integral Calculation type:

• 0/"mc" = Monte-Carlo-Integration

• 1/"laplace" = Laplace Approximation

• 2/"bfgs-laplace" = BFGS Laplace Approximation

Sample size for E-family sampling

How to sample from distributions in E-family calculations. 0=Random Sampling, 1=LatinHyperCube –

• ******START OF Optimization algorithm SPECIFICATION OPTIONS**********

Use random search (1=TRUE, 0=FALSE)

Use Stochastic Gradient search (1=TRUE, 0=FALSE)

Use Line search (1=TRUE, 0=FALSE)

Use Exchange algorithm (1=TRUE, 0=FALSE)

Use BFGS Minimizer (1=TRUE, 0=FALSE)

Use grouped time points (1=TRUE, 0=FALSE).

Exchange Algorithm Criteria:

• 1/"modified" = Modified

• 2/"fedorov" = Fedorov

Filename and path, or function name, for a run file that is used instead of the regular PopED call.

• ******START OF Labeling and file names SPECIFICATION OPTIONS**********

The current PopED version

The model title

Filename and path of the output file during search

Filename suffix of the result function file

Filename and path for storage of current optimal design

• ******START OF Miscellaneous SPECIFICATION OPTIONS**********

User defined data structure that, for example could be used to send in data to the model

Value to interpret as zero in design

The seed number used for optimization and sampling – integer or -1 which creates a random seed as.integer(Sys.time()) or NULL.

Vector for line search on continuous design variables (1=TRUE,0=FALSE)

Vector for line search on discrete design variables (1=TRUE,0=FALSE)

Use graph output during search

If a log file should be used (0=FALSE, 1=TRUE)

Method used to calculate M1:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

• 20/"analytic" = Analytic derivative

• 30/"ad" = Automatic differentiation

Method used to calculate M2:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

• 20/"analytic" = Analytic derivative

• 30/"ad" = Automatic differentiation

Method used to calculate linearization of residual error:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

• 30/"ad" = Automatic differentiation

Method used to calculate the gradient of the model:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

• 20/"analytic" = Analytic derivative

• 30/"ad" = Automatic differentiation

Method used to calculate the gradient of the parameter vector g:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

• 20/"analytic" = Analytic derivative

• 30/"ad" = Automatic differentiation

Method used to calculate all the gradients:

• 1/"central" = Central difference

• 0/"complex" = Complex difference

Number of iterations in random search between screen output

Number of iterations in stochastic gradient search between screen output

Step length of derivative of linearized model w.r.t. typical values

Step length of derivative of model w.r.t. g

Step length of derivative of g w.r.t. b

Step length of derivative of variance w.r.t. typical values

Step length of derivative of OFV w.r.t. time

Step length of derivative of model w.r.t. sigma

The absolute tolerance for the diff equation solver

The relative tolerance for the diff equation solver

The diff equation solver method, NULL as default.

If the differential equation results should be stored in memory (1) or not (0)

Number of Random search iterations

Number of stochastic gradient iterations

Number of Random search iterations with discrete optimization.

Number of Stochastic Gradient search iterations with discrete optimization

Iterations until adaptive narrowing in random search

Stochastic Gradient convergence value, (difference in OFV for D-optimal, difference in gradient for ED-optimal)

Random search locality factor for sample times

Random search locality factor for covariates

Stochastic Gradient search first step factor for sample times

Stochastic Gradient search first step factor for covariates

Use greedy algorithm for group assignment optimization

Exchange Algorithm StepSize

Exchange Algorithm NumPoints

Exchange Algorithm Convergence Limit/Criteria

Avoid replicate samples when using Exchange Algorithm

BFGS Minimizer Convergence Criteria Normalized Projected Gradient Tolerance

BFGS Minimizer Line Search Tolerance f

BFGS Minimizer Line Search Tolerance g

BFGS Minimizer Line Search Tolerance x

Number of iterations in ED-optimal design to calculate convergence criteria

ED-optimal design convergence criteria in percent

Number of grid points in the line search

Number of iterations of full Random search and full Stochastic Gradient if line search is not used

Compile options for PopED

• "none"/-1 = No compilation

• "full/0 or 3 = Full compilation

• "mcc"/1 or 4 = Only using MCC (shared lib)

• "mpi"/2 or 5 = Only MPI,

When using numbers, option 0,1,2 runs PopED and option 3,4,5 stops after compilation.

When using characters, the option compileOnly determines if the model is only compiled (and PopED is not run).

logical; only compile the model, do not run PopED (in conjunction with iCompileOption)

Parallel method to use

• 0/"matlab"= Matlab PCT

• 1/"mpi" = MPI

Additional dependencies used in MCC compilation (mat-files), if several space separated

Compilation output executable name

Number of processes to use when running in parallel (e.g. 3 = 2 workers, 1 job manager)

Number of design evaluations that should be evaluated in each process before getting new work from job manager

The prefix of the output mat file to communicate with the executable

Extra options send to e$g. the MPI executable or a batch script, see execute_parallel$m for more information and options

Polling time to check if the parallel execution is finished

The file containing the popedInput structure that should be used to evaluate the designs

If the random search is going to be executed in parallel

If the stochastic gradient search is going to be executed in parallel

If the modified exchange algorithm is going to be executed in parallel

If the line search is going to be executed in parallel

Vector defining the size of the different groups (num individuals in each group). If only one number then the number will be the same in every group.

string that represents the time in the dataset (ie xt)

string that represents the lower design time (ie minxt)

string that represents the upper design time (ie maxmt)

The id variable

Number of groups in the study. Each individual in a group will have the same design.

A matrix defining the initial discrete values for the model Each row is a group/individual.

Vector defining the number of samples for each group.

• ******START OF DESIGN SPACE OPTIONS**********

Max number of samples per group/individual

Min number of samples per group/individual

Number defining the maximum number of samples allowed in the experiment.

Number defining the minimum number of samples allowed in the experiment.

Vector defining the max size of the different groups (max number of individuals in each group)

Vector defining the min size of the different groups (min num individuals in each group) –

The total maximal groupsize over all groups

The total minimal groupsize over all groups

Cell array cell defining the discrete variables allowed for each xt value. Can also be a vector of values c(1:10) (same values allowed for all xt), or a list of lists list(1:10, 2:23, 4:6) (one for each value in xt in row major order or just for one row in xt, and all other rows will be duplicated).

Matrix defining the initial continuous covariate values. n_rows=number of groups, n_cols=number of covariates. If the number of rows is one and the number of groups > 1 then all groups are assigned the same values.

Vector defining the max value for each covariate. If a single value is supplied then all a values are given the same max value

Vector defining the min value for each covariate. If a single value is supplied then all a values are given the same max value

Cell array cell defining the discrete variables allowed for each a value. Can also be a list of values list(1:10) (same values allowed for all a), or a list of lists list(1:10, 2:23, 4:6) (one for each value in a).

Cell array cell defining the discrete variables for each x value.

Group sampling times between groups so that each group has the same values (TRUE or FALSE).

Matrix defining the grouping of sample points. Matching integers mean that the points are matched. Allows for finer control than use_grouped_xt

Group continuous design variables between groups so that each group has the same values (TRUE or FALSE).

Matrix defining the grouping of continuous design variables. Matching integers mean that the values are matched. Allows for finer control than use_grouped_a.

Group discrete design variables between groups so that each group has the same values (TRUE or FALSE).

Matrix defining the grouping of discrete design variables. Matching integers mean that the values are matched. Allows for finer control than use_grouped_x.

Value to interpret as zero in design.

Filename and path, or function name, for the Autocorrelation function, empty string means no autocorrelation

Filename and path, or function name, for user defined distributions for E-family designs

Matrix or single value defining the minimum value for each xt sample. If a single value is supplied then all xt values are given the same minimum value

Matrix or single value defining the maximum value for each xt sample. If a single value is supplied then all xt values are given the same maximum value.

Cell array cell defining the discrete variables allowed for each xt value. Can also be a list of values list(1:10) (same values allowed for all xt), or a list of lists list(1:10, 2:23, 4:6) (one for each value in xt). See examples in create_design_space.

Cell array cell defining the discrete variables allowed for each a value. Can also be a list of values list(1:10) (same values allowed for all a), or a list of lists list(1:10, 2:23, 4:6) (one for each value in a). See examples in create_design_space.

boolean; Fix the residuals to what is specified by the model

write a PopED/rxode2 script that can be modified for more fine control. The default is NULL.

When script is TRUE, the script is returned as a lines that would be written to a file and with the class babelmixr2popedScript. This allows it to be printed as the script on screen.

When script is a file name (with an R extension), the script is written to that file.

[logical(1)]
If TRUE, an existing file in place is allowed if it it is both readable and writable. Default is FALSE.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean to indicate if this is meant for optimizing times

boolean to indicate if this is meant for optimizing covariates

boolean to indicate if the discrete design variables be optimized

boolean to indicate if the sample optimizer is used (not implemented yet in PopED)

boolean to indicate if the global time indexer inside of babelmixr2 is reset if the times are different. By default this is TRUE. If FALSE you can get slightly better run times and possibly slightly different results. When optTime is FALSE the global indexer is reset every time the PopED rxode2 is setup for a problem or when a poped dataset is created. You can manually reset with popedMultipleEndpointResetTimeIndex()

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

other parameters for PopED control

A numeric vector of times.

An integer vector of model switch indicator corresponding to the times

A boolean indicating if the returned times should be sorted

boolean for popedMultipleEndpointIndexDataFrame() when TRUE show each id/index per time even though it may not reflect in the returned data.frame

A numeric vector of parameters

A numeric vector of times

An integer vector indicating model switches from PopED

An integer specifying the maximum number of time points in the mtimes model

Number of elements in the population. Defaults to max(5*length(p),50) which is calculated from the number of parameters in the model

Number of iterations to run the optimization. Defaults to 10000. The algorithm either stops when numiter iterations has been performed or when the remaining variation is less than varleft.

Number of elements from which to estimate a new parameter vector. The default is 3.

relative variation remaining; if below this value, the algorithm stops. When NULL (the default) it is derived from sigdig, keeping the FME::pseudoOptim() default of 1e-8 at the default sigdig = 4 and tightening/loosening it one order of magnitude per significant digit.

If TRUE, print information about the optimization from FME::pseudoOptim. Default is FALSE.

return the pseudoOptim output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

when TRUE (default) a subject whose ODE solve had to be retried with a relaxed tolerance keeps that relaxed tolerance for the rest of the fit instead of resetting it every evaluation

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

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)'.

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).

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.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

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.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

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).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r,s" (the default) is the sandwich estimator (see below). "analytic" uses the exact analytic observed-information R-matrix (reported as R^{-1}) and additionally returns the residual and Omega standard errors; it covers FOCEI/FOCE fits with additive, proportional, or combined error, mu-referenced/covariate/other structural parameters (and non-mu-referenced etas), and SD-scale inter-occasion variability, and emits a message and falls back to the finite-difference Hessian for anything out of scope (FO, nAGQ > 1, censoring, DV-transformed error, bounded-parameter transforms, a structural theta shared by two etas, non-SD iovXform, or a pure-proportional variance that vanishes at a near-zero prediction). The finite-difference methods use R (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 (solve(R)), "s" cross-product-based (solve(S)), or "" to skip the covariance step. "sa" (SAEM Louis stochastic-approximation FIM) and "imp" (importance-sampling Monte-Carlo observed information) are also accepted for any method; they are computed post-fit at the converged estimates by the decoupled recompute engine.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.

method used for the dosing-parameter (alag/F/rate/dur) sensitivities: "jump" routes them through rxode2's analytic event jumps; "fd" falls back to Shi2021 finite differences. See nlmixr2est::nlmControl().

Ignored parameters

Expression

rxode2 ui

Expression

rxode2 ui

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

rxUiGet list(ui)

additional arguments (currently ignored)

logical, whether to compute MAP estimates (default TRUE)

logical, whether to compute FIM (default TRUE)

logical, whether to compute log-likelihood by Importance Sampling (default TRUE)

logical, whether to compute log-likelihood by Gaussian Quadrature (default FALSE)

integer vector of length 2, number of iterations for phase 1 (exploratory) and phase 2 (smoothing) of SAEM (default c(300, 100))

number of iterations for simulated annealing (default NA)

number of iterations for burn-in (default 5)

number of iterations for MAP estimation (default 5)

number of chains (default 1)

logical, whether to fix the random seed (default TRUE)

random seed (default 23456)

number of Monte Carlo samples for Importance Sampling (default 5000)

number of degrees of freedom for the student distribution in Importance Sampling (default 4)

logical, whether to print progress during Importance Sampling (default FALSE)

number of iterations between progress displays (default 100)

logical, whether to display graphical progress (default FALSE)

whether saemix prints algorithm progress (default FALSE). Accepts the legacy logical/integer scalar or a pre-built nlmixr2est::iterPrintControl() object; internally the control stores a single iterPrintControl sub-list (matching the nlmixr2est iteration-print unification), and any nonzero every enables the saemix progress output

logical, whether to save results to files (default TRUE)

logical, whether to save graphs (default TRUE)

directory where results and graphs are saved (default "newdir")

logical, whether to show warnings (default FALSE)

integer vector of length 4, number of iterations for MCMC kernel updates (default c(2, 2, 2, 0))

probability for MCMC kernel selection (default 0.4)

stepsize for random walk kernel (default 0.4)

initial standard deviation for random walk kernel (default 0.5)

parameter for simulated annealing (default 0.97)

number of nodes for Gaussian Quadrature (default 12)

number of standard deviations for Gaussian Quadrature (default 4)

maximum number of iterations for maximization step (default 100)

number of simulations for visual predictive check (default 1000)

number of simulations for predictions (default 100)

parameter for L-MCMC (default 50)

parameter for R-MCMC (default 0.05)

'rxode2' ODE solving options during fitting, created with 'rxControl()'

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

when TRUE (default) a subject whose ODE solve had to be retried with a relaxed tolerance keeps that relaxed tolerance for the rest of the fit instead of resetting it every evaluation

method used for the dosing-parameter (alag/F/rate/dur) sensitivities when the final tables are built: "jump" routes them through rxode2's analytic event jumps; "fd" falls back to Shi2021 finite differences. See nlmixr2est::foceiControl().

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

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).

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.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

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.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

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).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Ignored parameters

The numerator of the units (or the whole unit specification)

The denominator of the units (or NULL if numerator is the whole unit specification)