Plot the optimizer trace from a ferx fit or running job

Description

Produces a two-panel diagnostic plot from the per-iteration trace written when optimizer_trace = TRUE was passed to [ferx_fit](ferx_fit.qmd). The top panel shows OFV over iterations; the bottom panel shows a method-specific convergence metric (gradient norm for gradient-based methods, MH accept rate for SAEM, LM lambda for Gauss-Newton). Phase boundaries are drawn as vertical dashed lines.

Usage

# S3 method for ferx_fit
plot(x, y = NULL, log_ofv = FALSE, monotonic = TRUE, ...)

# S3 method for ferx_job
plot(x, y = NULL, log_ofv = FALSE, monotonic = TRUE, ...)

Arguments

  • x: A ferx_fit object (from [ferx_fit](ferx_fit.qmd)) or a ferx_job handle (from [ferx_fit_async](ferx_fit_async.qmd)).
  • y: Ignored. Present only for consistency with the plot(x, y, ...) generic; must be NULL if supplied.
  • log_ofv: Logical; when TRUE, shift the OFV panel down by its minimum value (\(OFV - min(OFV)\)) instead of plotting the raw OFV. Despite the name this is a shift, not a log transform. Default FALSE.
  • monotonic: Logical; when TRUE (the default), the OFV panel shows the running minimum (cummin) over FOCE/FOCEI iterations only, rather than their raw per-evaluation OFV, since FOCE/FOCEI traces include rejected line-search trial steps that can transiently increase OFV. Gauss-Newton and SAEM iterations (including a chained method’s SAEM/GN segment preceding a FOCE/FOCEI segment) are always left as-is.
  • ...: Ignored.

Details

plot.ferx_job dispatches on the handle returned by [ferx_fit_async](ferx_fit_async.qmd) and plots the trace accumulated so far, before the job has completed. If no iterations have been written yet, a placeholder panel is shown instead of an error.

Seealso

Other diagnostics: [check_diagnostics](check_diagnostics.qmd)(), [ferx_conddist](ferx_conddist.qmd)(), [ferx_cov_screen](ferx_cov_screen.qmd)(), [ferx_get_warnings](ferx_get_warnings.qmd)(), [ferx_runlog_iters](ferx_runlog_iters.qmd)(), [ferx_trace](ferx_trace.qmd)(), [summary.ferx_fit](summary.ferx_fit.qmd)()

Concept

diagnostics

Value

Invisibly returns the trace data frame (from [ferx_trace](ferx_trace.qmd)), or NULL when no trace data is available yet (job case).

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, method = "gn", covariance = FALSE,
                optimizer_trace = TRUE)
plot(fit)