Simulate with parameter-uncertainty propagation

Description

For each parameter set drawn from the uncertainty distribution, the per-subject random-effect / residual-error simulator runs n_sim_per_draw times. The result includes both individual variability (etas, epsilons) and parameter uncertainty - useful for uncertainty-aware VPCs, dose-recommendation intervals, and any analysis where treating the ML estimates as fixed would understate variability.

Usage

ferx_simulate_with_uncertainty(
  model,
  data,
  fit,
  n_uncertainty_draws = 100L,
  n_sim_per_draw = 1L,
  method = c("asymptotic", "sir"),
  seed = 42L
)

Arguments

  • model: Path to a .ferx model file
  • data: Path to a NONMEM-format CSV (provides population structure)
  • fit: A ferx_fit result. Must carry either cov_matrix (asymptotic) or sir_resamples (SIR) depending on method.
  • n_uncertainty_draws: Number of parameter sets to draw from the uncertainty distribution
  • n_sim_per_draw: Number of eta/eps replicates per parameter draw
  • method: Either "asymptotic" (default) or "sir"
  • seed: Random seed for reproducibility

Details

Two uncertainty sources are supported:

  • method = "asymptotic": Multivariate normal around the ML estimate in the engine’s packed (log-theta, Cholesky-omega, log-sigma) parameter space, using fit$cov_matrix. Requires fit to come from a ferx_fit() call with covariance = TRUE.
  • method = "sir": Sample with replacement from fit$sir_resamples. Requires the fit to have been run with sir = TRUE and sir_keep_samples = TRUE (passed via settings).

Seealso

Other simulation: [ferx_npde](ferx_npde.qmd)(), [ferx_predict](ferx_predict.qmd)(), [ferx_predict_survival](ferx_predict_survival.qmd)(), [ferx_simulate](ferx_simulate.qmd)(), [ferx_simulate_adaptive](ferx_simulate_adaptive.qmd)()

Concept

simulation

Value

A data.frame with columns: DRAW, SIM, ID, TIME, CMT, IPRED, DV_SIM, OBSERVED. CMT is the observation compartment; OBSERVED is NAthroughout (this path is Gaussian-only - a drug-driven ODE-TTE endpoint is not supported here). Row count: n_uncertainty_draws * n_sim_per_draw * n_obs.

Examples

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

# Asymptotic (default): fast, MVN draws around the ML estimate
sims <- ferx_simulate_with_uncertainty(
  ex$model, ex$data, fit,
  n_uncertainty_draws = 200, n_sim_per_draw = 10
)
head(sims)         # SIM, ID, TIME, IPRED, DV_SIM
range(sims$DV_SIM) # sanity check on simulated range

# SIR method: requires sir = TRUE + sir_keep_samples = TRUE at fit time
fit_sir <- ferx_fit(ex$model, ex$data,
                    covariance = TRUE, sir = TRUE,
                    settings = list(sir_keep_samples = TRUE))
sims_sir <- ferx_simulate_with_uncertainty(
  ex$model, ex$data, fit_sir,
  n_uncertainty_draws = 200, n_sim_per_draw = 10,
  method = "sir"
)

# Summarise: 90% prediction interval per time point
pi90 <- aggregate(DV_SIM ~ TIME, data = sims,
                  FUN = function(x) quantile(x, c(0.05, 0.5, 0.95)))