ferx_model.RdConstructs a ferx_model S3 object that bundles a .ferx model
file path with an optional data path. This is the entry point for pipe-based
workflows. Both the model file and data path are validated at construction
time (the data path may be omitted and supplied later to
ferx_fit).
ferx_model(data = NULL, model)Optional path to a NONMEM-format CSV data file. Can be omitted
here and supplied later to ferx_fit.
Path to a .ferx model file. The file must exist.
An object of class ferx_model with fields $model and
$data.
Argument order: data comes first so a data object can flow
naturally into a pipeline:
ex$data |> ferx_model(ex$model) |> ferx_fit() |> summary()This is a change from earlier versions (where model was the first
argument). Old positional calls of the form ferx_model("pk.ferx") or
ferx_model("pk.ferx", "data.csv") are detected by the .ferx
extension on what is now the data slot and silently rewritten with a
deprecation warning; this auto-correction will be removed in a future
release. Calls that name data explicitly
(ferx_model("pk.ferx", data = "data.csv")) keep working unchanged
because R matches data = by name first and the remaining positional
argument falls into the model slot.
All fit options (method, covariance, threads,
settings, …) can still be passed directly to ferx_fit() in
the pipe — the ferx_model object only carries the file paths. See
ferx_fit for the full list of options and post-fit outputs.
ex <- ferx_example("warfarin")
# Inspect the object — prints model path, data path, and structure summary
m <- ferx_model(ex$data, ex$model)
print(m)
#> ferx_model
#> Model: /home/runner/work/_temp/Library/ferx/examples/models/warfarin.ferx
#> Data: /home/runner/work/_temp/Library/ferx/examples/data/warfarin.csv
#> ---
#> Structural: 1-cpt oral (TVCL, TVV, TVKA)
#> IIV: ETA_CL, ETA_V, ETA_KA
#> IOV: none
#> Residual: proportional
# Without data — supply at fit time via ferx_fit(data = ...)
m <- ferx_model(model = ex$model)
if (FALSE) { # \dontrun{
# ── Minimal pipe ────────────────────────────────────────────────────────
# ferx_fit() picks up $data automatically from the ferx_model object.
fit <- ex$data |>
ferx_model(ex$model) |>
ferx_fit(method = "focei", covariance = TRUE) |>
summary()
# ── Override fit options before fitting ─────────────────────────────────
# ferx_set_section() rewrites [fit_options] on disk and passes the
# ferx_model through so the pipe continues. When the model file lives
# inside the installed package (as for ferx_example()), the file is
# copied to tempdir() first so the bundled example is never mutated.
fit <- ex$data |>
ferx_model(ex$model) |>
ferx_set_section("fit_options", c(
" method = focei",
" maxiter = 500",
" covariance = true"
)) |>
ferx_fit()
summary(fit)
ferx_model_inspect(fit) # structure (no path needed post-fit)
ferx_cor_matrix(fit) # parameter correlation matrix
ferx_plot_trace(fit) # OFV + gradient norm over iterations
# ── Peek at a section mid-pipe without breaking the chain ────────────────
fit <- ex$data |>
ferx_model(ex$model) |>
ferx_get_section("parameters") |> # prints [parameters], passes through
ferx_fit(method = "focei")
# ── Validate initialisation before a long run ────────────────────────────
# ferx_check_init() runs 5 iterations and returns trace + diagnostics.
chk <- ferx_check_init(ex$model, ex$data, method = "focei")
chk$summary # ofv_start, ofv_end, ofv_drop — confirm OFV is dropping
ferx_plot_trace(chk$fit) # visual check of first few iterations
# ── Multi-stage chain: SAEM → FOCEI ─────────────────────────────────────
fit <- ex$data |>
ferx_model(ex$model) |>
ferx_fit(method = c("saem", "focei"), covariance = TRUE)
# ── Simulate and predict from fitted parameters ──────────────────────────
sim <- ferx_simulate(ex$model, ex$data, n_sim = 100, seed = 42, fit = fit)
pred <- ferx_predict(ex$model, ex$data, fit = fit)
# ── Data can be overridden at fit time ───────────────────────────────────
# (substitute the path to your own dataset for "other_cohort.csv")
ferx_model(ex$data, ex$model) |>
ferx_fit(data = "other_cohort.csv")
} # }