Quick convergence check with an optimizer trace

Description

Runs a short pilot fit (5 or 20 outer iterations depending on the method) with optimizer_trace = TRUE so you can inspect how the optimizer moves from the initial parameter values before committing to a full fit. Useful for diagnosing poor starting values, ill-scaled parameters, or structural model issues.

Usage

ferx_check_init(model, data = NULL, method = "focei", maxiter = NULL, ...)

Arguments

  • model: Path to a .ferx model file, or a ferx_model object created by [ferx_model](ferx_model.qmd). When a ferx_model is passed and data is not supplied, the data path on the object is used.
  • data: Path to a NONMEM-format CSV file. Optional when model is a ferx_model that already carries a data path.
  • method: Estimation method string, passed to [ferx_fit](ferx_fit.qmd). Default "focei".
  • maxiter: Maximum iterations for the pilot fit. Default: 5 for gradient-based methods, 20 for SAEM (to get a meaningful accept-rate trajectory).
  • ...: Additional arguments forwarded verbatim to [ferx_fit](ferx_fit.qmd) (e.g. threads, settings).

Seealso

Other fitting: [ferx_collect](ferx_collect.qmd)(), [ferx_fit](ferx_fit.qmd)(), [ferx_fit_async](ferx_fit_async.qmd)(), [ferx_inits_from_nca](ferx_inits_from_nca.qmd)(), [ferx_sir](ferx_sir.qmd)()

Concept

fitting

Value

A named list with:

Examples

ex  <- ferx_example("warfarin")

# Check initial values before committing to a full FOCEI fit
chk <- ferx_check_init(ex$model, ex$data)

# OFV drop confirms the gradient is pointing in the right direction
chk$summary   # ofv_start, ofv_end, ofv_drop

# Inspect per-iteration trace to spot early divergence or slow descent
ferx_plot_trace(chk$fit)

# Pipe style: data flows in from the ferx_model object
ex$data |>
  ferx_model(ex$model) |>
  ferx_check_init(method = "focei")