Run SIR against an existing fit

Description

Run a Sampling Importance Resampling (SIR) uncertainty step against a fit that was produced earlier - useful when the original fit was expensive and you want to add SIR without re-estimating, or when working with a fit loaded from a .fitrx bundle.

Usage

ferx_sir(
  fit,
  sir_samples = 1000L,
  sir_resamples = 250L,
  sir_seed = NULL,
  sir_keep_samples = FALSE,
  verbose = FALSE
)

Arguments

fit: A ferx_fit object produced by [ferx_fit](ferx_fit.qmd) or [ferx_load_fit](ferx_load_fit.qmd).
sir_samples: Number of proposal samples drawn from the asymptotic distribution. Higher values give tighter weights at proportional cost. Default 1000.
sir_resamples: Number of resampled vectors. Must be <= sir_samples. Default 250.
sir_seed: Integer RNG seed for reproducibility. NULL (the default) uses the engine’s built-in seed.
sir_keep_samples: When TRUE, retain the resampled packed parameter vectors on the returned fit. Required for [ferx_simulate_with_uncertainty](ferx_simulate_with_uncertainty.qmd) with method = "sir". Default FALSE.
verbose: When TRUE, the engine prints progress to stderr. Default FALSE.

Details

ferx_sir() re-uses the fit’s asymptotic covariance matrix as the SIR proposal distribution and the per-subject empirical Bayes ETAs as warm-starts for the inner loop. The returned fit is the input with sir_ess, sir_ci_theta, sir_ci_omega, sir_ci_sigma (and, when sir_keep_samples = TRUE, sir_resamples / sir_resamples_n / sir_resamples_dim) populated.

Integrity check

ferx_fit() records the model and data file paths plus SHA-256 hashes on the returned fit (fit$model_path, fit$data_path, fit$model_hash, fit$data_hash). ferx_sir() re-reads those files and verifies the hashes; if either file changed since the fit, the call is a hard error. The point of running SIR against the original fit is to refine its uncertainty estimate, which is meaningless against a modified model or dataset. Edge case: if hashing failed at fit time (e.g. permission flip between parse and hash) the corresponding fit$*_hash is NA and the integrity check silently passes on that side. This is rare in practice - hashing would have to fail while the parse just succeeded - but if you require integrity verification, check !is.na(fit$model_hash) && !is.na(fit$data_hash) before relying on the protection.

[ferx_fit](ferx_fit.qmd) for the inline SIR option (sir = TRUE), [ferx_simulate_with_uncertainty](ferx_simulate_with_uncertainty.qmd) for downstream consumption of the retained resamples. Other fitting: [ferx_check_init](ferx_check_init.qmd)(), [ferx_collect](ferx_collect.qmd)(), [ferx_fit](ferx_fit.qmd)(), [ferx_fit_async](ferx_fit_async.qmd)(), [ferx_inits_from_nca](ferx_inits_from_nca.qmd)()

Concept

fitting

Value

The input fit, augmented with sir_ess, sir_ci_theta, sir_ci_omega, sir_ci_sigma, and (when requested) sir_resamples / sir_resamples_n / sir_resamples_dim.

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, covariance = TRUE)

# Run SIR post-hoc (equivalent to sir = TRUE at fit time)
fit <- ferx_sir(fit, sir_samples = 2000, sir_resamples = 500, sir_seed = 42)

# Effective sample size - closer to sir_resamples means good coverage
fit$sir_ess

# 95% CI for fixed-effect thetas
fit$sir_ci_theta

# 95% CI for IIV omega diagonal
fit$sir_ci_omega

# 95% CI for residual error sigma
fit$sir_ci_sigma

# Retain resamples for downstream uncertainty simulation
fit2 <- ferx_sir(fit, sir_samples = 2000, sir_resamples = 500,
                 sir_keep_samples = TRUE)
sims <- ferx_simulate_with_uncertainty(
  ex$model, ex$data, fit2,
  n_uncertainty_draws = 200, n_sim_per_draw = 5,
  method = "sir"
)
head(sims)