Create a ferx_model object

Description

Constructs 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_fit.qmd)).

Usage

ferx_model(data = NULL, model)

Arguments

  • data: Optional path to a NONMEM-format CSV data file. Can be omitted here and supplied later to [ferx_fit](ferx_fit.qmd).
  • model: Path to a .ferx model file. The file must exist.

Details

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 .ferxextension 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](ferx_fit.qmd) for the full list of options and post-fit outputs.

Seealso

[ferx_set_section](ferx_set_section.qmd), [ferx_get_section](ferx_get_section.qmd), [ferx_fit](ferx_fit.qmd), [ferx_check_init](ferx_check_init.qmd)Other model-editing: [ferx_get_section](ferx_get_section.qmd)(), [ferx_model_edit](ferx_model_edit.qmd)(), [ferx_model_inspect](ferx_model_inspect.qmd)(), [ferx_model_new](ferx_model_new.qmd)(), [ferx_model_section](ferx_model_section.qmd)(), [ferx_model_set_section](ferx_model_set_section.qmd)(), [ferx_model_show](ferx_model_show.qmd)(), [ferx_model_validate](ferx_model_validate.qmd)(), [ferx_set_section](ferx_set_section.qmd)()

Concept

model-editing

Value

An object of class ferx_model with fields $model and $data.

Examples

ex <- ferx_example("warfarin")

# Inspect the object (prints model path, data path, and structure summary)
m <- ferx_model(ex$data, ex$model)
print(m)

# Without data: supply at fit time via ferx_fit(data = ...)
m <- ferx_model(model = ex$model)


# ?? 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")