Run the covariance step against an existing fit

Description

Run the finite-difference-Hessian covariance step against a fit that was produced earlier - the covariance-step analogue of [ferx_sir](ferx_sir.qmd). Useful when the original fit was expensive and you want to add standard errors without re-estimating, when you want to re-run the step with a different covariance_method (e.g. the rsr sandwich), or when working with a fit loaded from a .fitrx bundle.

Usage

ferx_covariance(
  fit,
  covariance_method = "r",
  mu_referencing = TRUE,
  verbose = FALSE
)

Arguments

fit: A ferx_fit object produced by [ferx_fit](ferx_fit.qmd) or [ferx_load_fit](ferx_load_fit.qmd).
covariance_method: Covariance estimator: "r" (inverse Hessian, the default, NONMEM MATRIX=R), "s" (inverse cross-product, MATRIX=S), or "rsr" (the Huber-White sandwich, MATRIX=RSR). "hessian" / "cross_product" / "sandwich" are accepted as aliases.
mu_referencing: Use mu-referencing for the inner-loop warm restart. Default TRUE (the engine default). Set to match the setting used for the original fit.
verbose: When TRUE, the engine prints progress to stderr. Default FALSE.

Details

ferx_covariance() reconstructs the fitted parameters from the fit, re-runs the inner loop (seeded from the per-subject empirical Bayes ETAs) to rebuild the covariance-step inputs, and calls the same covariance step [ferx_fit](ferx_fit.qmd) runs inline. The result closely matches fitting with covariance = TRUE (the same engine step; agreement is close but not bit-exact, since the standalone re-reads the data and cold-starts the inner EBE loop). The returned fit is the input with cov_matrix, cor_matrix, se_theta / se_omega / se_sigma / se_kappa, covariance_status, eigenvalues, and condition_numberrefreshed. A covariance step that runs but cannot produce a usable matrix (a non-positive-definite or structurally-unusable FD Hessian) is not an error: the returned fit reports covariance_status = "failed" with a diagnostic appended to warnings, mirroring [ferx_fit](ferx_fit.qmd). An error is reserved for input problems (missing / hash-mismatched model or data).

Integrity check

Like [ferx_sir](ferx_sir.qmd), ferx_covariance() re-reads the model and data files recorded on the fit (fit$model_path, fit$data_path) and verifies their SHA-256 hashes (fit$model_hash, fit$data_hash); if either file changed since the fit, the call is a hard error. Running the covariance step against a modified model or dataset would be meaningless. Edge case: if hashing failed at fit time the corresponding fit$*_hash is NA and the integrity check silently passes on that side. Check !is.na(fit$model_hash) && !is.na(fit$data_hash) before relying on the protection.

[ferx_fit](ferx_fit.qmd) for the inline covariance step (covariance = TRUE), [ferx_sir](ferx_sir.qmd) for the SIR uncertainty step. Other fitting: [ferx_check_init](ferx_check_init.qmd)(), [ferx_collect](ferx_collect.qmd)(), [ferx_fit](ferx_fit.qmd)(), [ferx_inits_from_nca](ferx_inits_from_nca.qmd)(), [ferx_sir](ferx_sir.qmd)(), [ferx_stop](ferx_stop.qmd)(), [print.ferx_job](ferx_fit_async.qmd)()

Concept

fitting

Value

The input fit, with cov_matrix, cor_matrix, se_theta, se_omega, se_sigma, se_kappa, covariance_status, eigenvalues, and condition_number refreshed.

Examples

ex  <- ferx_example("warfarin")

# Fit without the covariance step, then add it post-hoc.
fit <- ferx_fit(ex$model, ex$data, covariance = FALSE)
fit <- ferx_covariance(fit)
fit$se_theta       # standard errors now populated
fit$cov_matrix     # parameter covariance matrix

# Re-run with the robust sandwich estimator instead.
fit_rsr <- ferx_covariance(fit, covariance_method = "rsr")
fit_rsr$se_theta