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 = NULL,
  template = NULL,
  path = NULL,
  overwrite = FALSE,
  edit = TRUE,
  print = FALSE
)

Arguments

  • data: Optional path to a NONMEM-format CSV data file. Can be omitted here and supplied later to [ferx_fit](ferx_fit.qmd). When omitted, it defaults to the dataset declared in the model file’s [data] block (path = ...) if the model file has one.
  • model: Path to an existing .ferx model file (wrap mode). The file must exist. Leave NULL in scaffold mode.
  • template: Scaffold mode. One of "1cpt_oral" (default), "1cpt_iv", "2cpt_oral", "2cpt_iv", or "ode". Supplying it (or print = TRUE) triggers scaffold mode.
  • path: Scaffold mode. Path for the new .ferx file. Required unless print = TRUE. Must not already exist unless overwrite = TRUE.
  • overwrite: Scaffold mode. Logical. Overwrite path if it already exists? Defaults to FALSE.
  • edit: Scaffold mode. Logical. Open the new file in an editor after writing? Defaults to TRUE.
  • print: Scaffold mode. Logical. If TRUE, print the skeleton to the console instead of writing a file (no file created, no editor opened). Defaults to FALSE.

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. Scaffold mode. Passing template = (or print = TRUE) switches to scaffold mode: a new .ferx file is written to pathfrom a built-in skeleton and wrapped in a ferx_model object, so the result pipes straight into [ferx_fit](ferx_fit.qmd). print = TRUE prints the skeleton to the console and writes nothing (returns NULL). This replaces the former ferx_model_new().

Seealso

[ferx_model_set_section](ferx_model_set_section.qmd), [ferx_model_get_section](ferx_model_get_section.qmd), [ferx_fit](ferx_fit.qmd), [ferx_check_init](ferx_check_init.qmd)Other model-editing: [ferx_model_edit](ferx_model_edit.qmd), [ferx_model_get_section](ferx_model_get_section.qmd), [ferx_model_inspect](ferx_model_inspect.qmd), [ferx_model_set_section](ferx_model_set_section.qmd), [ferx_model_show](ferx_model_show.qmd), [ferx_model_validate](ferx_model_validate.qmd)

Concept

model-editing

Value

An object of class ferx_model with fields $model and $data. In scaffold mode with print = TRUE, NULLinvisibly.

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)

# Scaffold a new model from a template (writes the file, returns a ferx_model)
tmp <- tempfile(fileext = ".ferx")
m <- ferx_model(template = "1cpt_oral", path = tmp, edit = FALSE)
print(m)

# Peek at a skeleton without writing anything
ferx_model(template = "2cpt_iv", print = TRUE)


# ?? 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_model_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_model_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)
fit$cor_matrix            # parameter correlation matrix
plot(fit)                 # OFV + gradient norm over iterations

# ?? Read a section before fitting ?????????????????????????????????????????
lines <- ferx_model_get_section(ex$model, "parameters")
fit <- ex$data |>
  ferx_model(ex$model) |>
  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
plot(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")