Skip to main content

Method chaining, optimizers, and advanced fit options

FeRx supports running multiple estimation methods in sequence (method chains), switching outer optimizers, and fine-tuning convergence settings via the settings argument. This page covers these options with working code.

Method chains

Pass a character vector to method to run stages in sequence. Each stage is seeded with the previous stage’s converged parameters; only the final stage produces the reported covariance and diagnostics.

library(ferx)
ex <- ferx_example("warfarin")

# SAEM warm-up followed by FOCEI refinement
fit <- ferx_fit(ex$model, ex$data, method = c("saem", "focei"))
fit$method_chain
#> [1] "saem"   "focei"

Common chains

Chain Use case
c("saem", "focei") SAEM provides robust starting values; FOCEI refines the likelihood
c("gn", "focei") Fast Gauss-Newton warm-up then FOCEI
c("focei", "imp") FOCEI then importance sampling for a more accurate marginal log-likelihood
c("saem", "imp") SAEM then importance sampling

Importance sampling stage

The "imp" stage is a terminal diagnostic: it computes the marginal log-likelihood via Monte Carlo importance sampling without updating the parameters. It must always be last in the chain.

fit_imp <- ferx_fit(
  ex$model, ex$data,
  method   = c("focei", "imp"),
  settings = list(
    is_samples           = 2000L,
    is_proposal_df       = 4,        # t-distribution; smaller = heavier tails
    is_seed              = 1L,
    is_low_ess_threshold = 0.10
  )
)

# Marginal -2LL and Monte Carlo SE
fit_imp$importance_sampling$minus2_log_likelihood
fit_imp$importance_sampling$mc_standard_error

# Per-subject ESS diagnostics (fraction of is_samples)
fit_imp$importance_sampling$ess_min
fit_imp$importance_sampling$ess_median
fit_imp$importance_sampling$low_ess_subject_ids

The marginal log-likelihood from IMP is comparable across models in the same nesting family and does not depend on the Laplace approximation used by FOCE/FOCEI.

Outer optimizers

FeRx supports several outer optimizers for the population parameter loop. The default is auto: it picks NLopt L-BFGS when the exact analytic gradient is available and BOBYQA (derivative-free) when only finite differences are, with two overrides — more than 64 free parameters always takes L-BFGS, mixture models always take BOBYQA. Name an optimizer to pin it.

# BOBYQA (derivative-free)
fit_bobyqa <- ferx_fit(ex$model, ex$data, settings = list(optimizer = "bobyqa"))

# SLSQP (gradient-based NLopt)
fit_slsqp  <- ferx_fit(ex$model, ex$data, settings = list(optimizer = "slsqp"))

# L-BFGS
fit_lbfgs  <- ferx_fit(ex$model, ex$data, settings = list(optimizer = "nlopt_lbfgs"))

# MMA (NLopt Method of Moving Asymptotes)
fit_mma    <- ferx_fit(ex$model, ex$data, settings = list(optimizer = "mma"))

# Trust-region (Steihaug CG)
fit_tr <- ferx_fit(
  ex$model, ex$data,
  settings = list(optimizer = "trust_region", steihaug_max_iters = 100L)
)

# Compare OFV — all should land at the same minimum
sapply(
  list(bobyqa = fit_bobyqa, slsqp = fit_slsqp, lbfgs = fit_lbfgs,
       mma = fit_mma, trust_region = fit_tr),
  function(f) f$ofv
)

Optimizer guidance

Optimizer Best for
auto Default; picks nlopt_lbfgs or bobyqa per model
bobyqa Robust on rough surfaces and FD-only models
slsqp Well-conditioned analytical PK; fastest when gradients are accurate
nlopt_lbfgs Analytic-gradient models; moderate-sized parameter spaces (lbfgs is a deprecated alias)
mma Problems where SLSQP stalls
trust_region Ill-conditioned problems; guarantees descent each step
bfgs Small parameter spaces

If gradient-based optimizers stall above the BOBYQA optimum, enable the reconverged gradient (see below).

Convergence tuning

# Tighter inner (EBE) loop — useful for ill-conditioned problems
fit_tight <- ferx_fit(
  ex$model, ex$data,
  settings = list(
    maxiter       = 500L,
    inner_maxiter = 100L,
    inner_tol     = 1e-6
  )
)

# Reconverged gradient: re-solve EBEs at every outer gradient evaluation
# Costs ~5–6x more per outer iteration but can recover the full OFV surface
# when SLSQP stalls.  0 = fixed-EBE gradient (default); 1 = always reconverge;
# N = every N-th evaluation.
fit_reconv <- ferx_fit(
  ex$model, ex$data,
  settings = list(optimizer = "slsqp", reconverge_gradient_interval = 1L)
)

# Global pre-search: runs a derivative-free global optimizer before local
# refinement. Useful when starting values are far from the optimum.
fit_global <- ferx_fit(
  ex$model, ex$data,
  settings = list(global_search = TRUE, global_maxeval = 1000L)
)

Optimizer trace

Pass optimizer_trace = TRUE to record per-iteration OFV and parameter values. Use plot() to visualise convergence:

fit_trace <- ferx_fit(ex$model, ex$data, optimizer_trace = TRUE)
plot(fit_trace)   # two-panel: OFV and convergence metric vs iteration
ferx_trace(fit_trace)        # returns the raw data frame

Gauss-Newton

method = "gn" takes trust-region steps on the BHHH approximation of the Hessian. The step size is set by the trust radius, which ferx grows or shrinks from how well each step’s predicted OFV reduction matched the actual one. There is no step-size setting to tune:

fit_gn <- ferx_fit(ex$model, ex$data, method = "gn")

With optimizer_trace = TRUE, the lm_lambda column of ferx_trace() holds the trust radius: the radius a rejected step was tried with, or the radius after the update on an accepted step (details). The column name is kept from the Levenberg-Marquardt loop that GN replaced in 0.1.0.

gn_lambda, the damping factor of that older loop, has no effect. Remove it from your settings: depending on the ferx version it is ignored, with or without a notice in fit$warnings, or rejected. See Gauss-Newton (BHHH) in the ferx-core docs for the algorithm.

See also