Skip to main content

Write a fitted model with its final estimates as initial values

Description

Writes the model a fit was made with as a .ferx file whose initial values are the fit’s final estimates - NONMEM’s final.mod, Pharmpy’s update_inits. Refitting from the written file starts at the fit’s optimum: its objective function value at iteration 0 is the fit’s OFV. When some estimate cannot be written (below), a warning names it, so a file that is not the fit’s optimum is never returned silently.

Usage

ferx_update_model(fit, path = NULL, overwrite = FALSE)

Arguments

  • fit: A ferx_fit object returned by [ferx_fit](ferx_fit.qmd) or [ferx_load_fit](ferx_load_fit.qmd).
  • path: Where to write the model. NULL (default) writes nothing and returns the text instead.
  • overwrite: Logical. When FALSE (default), an existing file at path is an error.

Details

The edit is the engine’s own (ModelEdit::SeedInits in ferx-core), the one every search uses to write its final.ferx. Only the numbers in the [parameters] block change:

  • each theta init takes the fitted value; its bounds are kept;
  • each omega / kappa takes the fitted variance, or its square root on a declaration marked (sd);
  • each sigma takes the fitted value on the declaration’s own scale (variance, or SD with (sd));
  • a block_omega / block_kappa takes the fitted lower triangle, keeping its block structure;
  • a block_sigma takes the fitted residual covariance, lower triangle on the variance scale it is declared on: sigma_i^2 on the diagonal, rho_ij * sigma_i * sigma_j off it. Each number is replaced in place, so a bracket written over several lines keeps its lines. A free block the fit holds no value for (a fit from an older bundle without residual_correlations) is left as written, with a warning;
  • a [mixture] fit’s per-class omega(k) / sigma(k) overrides take their fitted class values (fit$mixture_overrides), on each line’s own scale; a fit that records none leaves them as written, with a warning;
  • a FIXed parameter is left as declared, as is any estimate that is not finite.

A theta level block (theta NAME[N] or theta NAME[COL, ...]) cannot be written: the model language gives a block one (init, lower, upper) for all its levels, and a constrained (contrast = ...) block must start at 0, so its fitted level values have no place in the file. Such a block is left as declared, with a warning naming it; a refit then starts its levels at the declared value, not at the fit’s OFV. Comments - whole-line ones and those at the end of a rewritten declaration - formatting and every other block are kept as written. A declaration written over several lines is rewritten onto its first line, carrying the comments of the others. The model text is the one that was fitted (fit$model_text, when it still hashes to fit$model_hash), whatever has happened to the file at fit$model_path since. A fit that does not carry it falls back to that file, with a warning of class ferx_model_edited_warning when the file has been edited since the fit.

Seealso

[ferx_save_fit](ferx_save_fit.qmd) (write_model = TRUE writes this file next to the bundle), [ferx_fit](ferx_fit.qmd)Other model-editing: [ferx_model](ferx_model.qmd), [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

With path, the path written, invisibly. Without, the updated model text as a single character string.

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, method = "gn", covariance = FALSE)
final <- ferx_update_model(fit, tempfile(fileext = ".ferx"))
cat(ferx_model_get_section(final, "parameters"), sep = "\n")