Simulate with parameter-uncertainty propagation

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.

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

Value

A data.frame with columns: DRAW, SIM, ID, TIME, IPRED, DV_SIM. Row count: n_uncertainty_draws * n_sim_per_draw * n_obs.

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).

Examples

if (FALSE) { # \dontrun{
ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, covariance = TRUE)

# Asymptotic (default): fast, MVN around the ML estimate
sims <- ferx_simulate_with_uncertainty(
  ex$model, ex$data, fit,
  n_uncertainty_draws = 200, n_sim_per_draw = 10
)

# SIR: 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"
)
} # }