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: Aferx_fitobject 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. WhenFALSE(default), an existing file atpathis 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
thetainit takes the fitted value; its bounds are kept; - each
omega/kappatakes the fitted variance, or its square root on a declaration marked(sd); - each
sigmatakes the fitted value on the declaration’s own scale (variance, or SD with(sd)); - a
block_omega/block_kappatakes the fitted lower triangle, keeping its block structure; - a
block_sigmatakes the fitted residual covariance, lower triangle on the variance scale it is declared on:sigma_i^2on the diagonal,rho_ij * sigma_i * sigma_joff 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 withoutresidual_correlations) is left as written, with a warning; - a
[mixture]fit’s per-classomega(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")