NONMEM-style run log for a ferx fit

Description

Produces a plain-text summary modelled on the information content of a NONMEM .lst file: run header, model source, data summary, initial vs. final parameter table with SE and and normality diagnostics, and (where available) the final gradient vector with a convergence diagnostic.

Usage

ferx_runlog(fit, gradient_tol = 0.1, show_iterations = TRUE, verbose = TRUE)

Arguments

  • fit: A ferx_fit object returned by [ferx_fit](ferx_fit.qmd) or [ferx_load_fit](ferx_load_fit.qmd).
  • gradient_tol: Numeric scalar. Threshold for the relative gradient (|grad[i] * param[i]|); components exceeding this trigger a convergence warning. Default 0.1.
  • show_iterations: Logical. When TRUE (the default) and the fit was run with optimizer_trace = TRUE, an “Iteration history” section is inserted showing OFV, delta-OFV, and method-specific convergence metrics (gradient norm for FOCE/BFGS, LM-lambda for Gauss-Newton, MH-accept-rate for SAEM) per iteration. Runs with more than 30 iterations are truncated to the first 10 and last 10 rows. Set to FALSE to suppress this section.
  • verbose: Logical. When TRUE (the default) the output is printed to the console. When FALSE it is returned invisibly as a single character string.

Details

Sections that depend on fields introduced in engine version 0.1.6 (model_text, theta_init, omega_init, sigma_init, obs_time_range, final_gradient) are silently omitted when those fields are absent or NULL – so the function works against older .fitrx bundles or in-memory fits that do not carry file provenance. The data summary shows subject and observation counts when fit$n_subjectsand fit$n_obs are present; observation time range when fit$obs_time_range is present. Missing counts produce a partial summary rather than an error.

Value

A single character string containing the full log (invisibly when verbose = TRUE).

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data)
ferx_runlog(fit)
ferx_runlog(fit, verbose = FALSE)  # capture as string