Derive NCA-based starting values without fitting

Description

ferx_inits_from_nca() estimates population starting values directly from the data using non-compartmental analysis (NCA), optionally refining parameters NCA cannot estimate with a grid sweep. It runs the same estimation that the inits_from_nca argument to [ferx_fit](ferx_fit.qmd) performs, but returns the suggested values for inspection instead of running a fit. This is useful for sanity-checking starting values, or for feeding them back into a model file before fitting.

Usage

ferx_inits_from_nca(
  model,
  data = NULL,
  method = c("nca_sweep", "nca", "nca_ebe")
)

# S3 method for ferx_inits
print(x, ...)

Arguments

  • model: A path to a .ferx model file, or a ferx_model object created with [ferx_model](ferx_model.qmd).
  • data: Path to a NONMEM-format CSV file. When model is a ferx_model object that already carries a data path, this may be left NULL.
  • method: One of "nca_sweep" (default), "nca", or "nca_ebe". See Details.
  • x: A ferx_inits object returned by ferx_inits_from_nca().
  • ...: Ignored.

Details

All three methods are NCA-based; they differ only in how much refinement runs on top of the NCA estimates:

  • "nca": Non-compartmental analysis only (fastest). Leaves parameters NCA cannot reach (peripheral Q/V2, all ODE/PD thetas) at the model default.
  • "nca_sweep": NCA, then a log-space rRMSE grid sweep (population predictions, etas = 0) over the remaining non-fixed thetas. Model-agnostic: also covers ODE/PD models. This is the default.
  • "nca_ebe": Like "nca_sweep" but evaluates the grid with empirical Bayes estimates (etas != 0); more accurate under large between-subject variability. Falls back to "nca_sweep" for ODE models.

Note

The method argument always wins: a [fit_options] inits_from_nca key in the model file is not consulted by this function. To preview the strategy a model file declares, pass that value explicitly via method.

References

The "nca" and "nca_sweep" strategies were inspired by the automated initial-estimate pipeline described in: Huang Z., Fidler M., Lan M., Cheng I.L., Kloprogge F., Standing J.F. (2025). An automated pipeline to generate initial estimates for population Pharmacokinetic base models. Journal of Pharmacokinetics and Pharmacodynamics, 52(6), 60. . Reference implementation: https://github.com/ucl-pharmacometrics/nlmixr2autoinit. The "nca_ebe" method is a ferx-specific extension that evaluates the rRMSE grid using empirical Bayes estimates rather than population predictions.

Seealso

[ferx_fit](ferx_fit.qmd), whose inits_from_nca argument applies these values automatically before the optimizer runs. Other fitting: [ferx_check_init](ferx_check_init.qmd)(), [ferx_collect](ferx_collect.qmd)(), [ferx_fit](ferx_fit.qmd)(), [ferx_fit_async](ferx_fit_async.qmd)(), [ferx_sir](ferx_sir.qmd)()

Concept

fitting

Value

An object of class ferx_inits: a list with elements

  • theta: Named numeric vector of suggested theta starting values.
  • omega: Suggested omega matrix (with eta names as dimnames). The CL eta variance is updated from inter-subject CV-squared; other entries keep the model default.
  • method: The method actually used (a string).
  • warnings: Character vector of notes about what was and wasn’t estimated.

Examples

ex <- ferx_example("warfarin")

# -- Classic style (path strings) ------------------------------------------
inits <- ferx_inits_from_nca(ex$model, ex$data)
inits$theta
inits$omega

# Pick a specific strategy
ferx_inits_from_nca(ex$model, ex$data, method = "nca")
ferx_inits_from_nca(ex$model, ex$data, method = "nca_ebe")

# -- Pipe style (ferx_model object) ----------------------------------------

# data |> ferx_model(model) bundles the paths into a ferx_model, which
# ferx_inits_from_nca() unpacks automatically (the second arg can stay NULL).
ex$data |>
  ferx_model(ex$model) |>
  ferx_inits_from_nca()

# Inspect first, then fit using the same strategy in one chain.
ex$data |>
  ferx_model(ex$model) |>
  ferx_inits_from_nca(method = "nca_ebe") |>
  print()

ferx_fit(ex$model, ex$data, inits_from_nca = "nca_ebe")

# Peek at the suggested CL/V before committing to a fit.
ex$data |>
  ferx_model(ex$model) |>
  ferx_inits_from_nca() |>
  (\(x) x$theta[c("TVCL", "TVV")])()