foceiLikLoad: Load a general FOCE-family likelihood into memory

In nlmixr2est: Nonlinear Mixed Effects Models in Population PK/PD, Estimation Routines

Load a general FOCE-family likelihood into memory

Description

Compiles the inner (FOCEi sensitivity) model from an rxode2 UI model, preprocesses the data, and sets up the FOCEi inner problem in memory so that individual log-likelihoods can be evaluated repeatedly (in parallel per subject) at supplied etas without recompiling – the setup used internally by 'est="emvi"'/'est="fbvi"', 'est="vae"' and the f-SAEM fast kernel, exposed here for MCMC/SAMBA-style callers (issue #414).

Usage

foceiLikLoad(
  object,
  data,
  likelihood = c("focei", "focep", "foce"),
  rxControl = rxode2::rxControl(),
  scale = c("focei", "natural"),
  thetaSens = FALSE,
  combSens = FALSE,
  iovXform = c("sd", "var", "logsd", "logvar"),
  est = "focei",
  ...
)

Arguments

object	An 'rxode2'/'nlmixr2' UI model (a model function or its compiled UI).
data	The estimation data (a data frame with the usual nlmixr2 columns).
likelihood	The individual likelihood type: '"focei"' (FOCE with interaction), '"focep"' (FOCE+, interaction off with the residual variance at the conditional eta) or '"foce"' (NONMEM-style FOCE, residual variance frozen at eta=0).
rxControl	An [rxode2::rxControl()] object for the ODE solving options.
scale	The parameter scale [foceiLikRun()]'s 'theta' is on: '"focei"' (default) is the FOCEi estimation scale (the historical behavior); '"natural"' pins the scaling to the identity ('scaleType="mult"', 'scaleTo=0'), so the population thetas in 'theta' (and in the handle's 'initPar') are the natural-scale values directly comparable with 'ui$iniDf$est' – no unscaling step for external callers (#939). With either choice the trailing omega-block entries of the parameter vector remain in the internal 'diagXform' parameterization of 'chol(Omega^-1)'; '"natural"' leaves them unscaled but does not change that parameterization.
thetaSens	When 'TRUE', also build and wire the theta-sensitivity model ('d(f)/d(theta)', 'd(V)/d(theta)' forward sensitivities for the estimated non-mu structural and residual-error thetas), the model the imp/advi engines use for their outer population gradient. Off by default: building it costs compile and solve time a value-only caller should not pay (#939). The handle's 'thetaSensIdx' reports which 'ntheta' indices carry sensitivities ('integer(0)' when none do, e.g. when every theta is mu-referenced).
combSens	When 'TRUE', use the combined eta+theta sensitivity build (#958): the INNER model itself carries the theta-sensitivity columns (appended after the FOCEi block), so one ODE integration per subject serves the value, 'd/d(eta)' AND 'd/d(theta)' – the fused batch entry 'nlmixr2FoceiCondBatchThetaGrad' reads all three from a single solve (~2x cheaper per evaluation than the two-model path). Implies a theta-sensitivity request; the separate theta-sensitivity model is neither built nor compiled.
iovXform	Transformation carrying the IOV magnitude theta (the '.uiApplyIov' hook): '"sd"' (default), '"var"', '"logsd"', '"logvar"'. The presence of this argument also marks the loaded nlmixr2est as carrying the exact IOV magnitude sensitivity (#952)
est	Estimation-method name the standard pre-process hooks run against (default ‘"focei"'). The hooks read the named method’s capability attributes (for example whether a bounded-transform reparameterization is wanted), so a caller preparing the problem for a different consumer can name it here and get that consumer's preprocessing guarantees instead of focei's (#939). The inner engine itself is unaffected.
...	Additional solving/model options passed to '.foceiLikControl' (e.g. 'optExpression', 'addProp', 'eventSens').

Details

Only one likelihood system may be loaded at a time; loading errors if one is already loaded. Use [foceiLikRun()] to evaluate and [foceiLikUnload()] to free.

Value

Invisibly, a handle list with the loaded system's dimensions: ‘initPar' (the parameter vector at the model’s initial estimates on the requested 'scale', a ready 'theta' for [foceiLikRun()]), 'npars', 'ntheta', 'neta', 'nid', 'thetaNames', 'etaNames', 'idLvl', 'likelihood', 'scale', 'thetaSens' (theta sensitivities wired, by either build), 'combSens' (the #958 combined build) and 'thetaSensIdx'.

Author(s)

Matthew L. Fidler

See Also

[foceiLikRun()], [foceiLikUnload()]

Examples

one.cmt <- function() {
  ini({
    tka <- 0.45
    tcl <- 1
    tv <- 3.45
    add.sd <- 0.7
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    linCmt() ~ add(add.sd)
  })
}

# Set the likelihood up in memory once; only one may be loaded at a time
h <- foceiLikLoad(one.cmt, theo_sd, "focei")

# The handle carries the dimensions and a ready starting parameter vector
h$nid
h$neta
h$initPar

# Individual joint log-likelihood at eta = 0, one value per subject
eta <- matrix(0, h$nid, h$neta)
foceiLikRun(h$initPar, eta)

# Free it when done (loading again before this errors)
foceiLikUnload()

nlmixr2est documentation built on Sept. 20, 2026, 9:08 a.m.