Simulation-based NPDE / NPD diagnostics from a fit

Description

Computes Normalized Prediction Distribution Errors (NPDE, decorrelated within subject) and Normalized Prediction Discrepancies (NPD) post-hoc by Monte-Carlo simulation under the fitted model (Brendel et al. 2006; Comets et al. 2008). Use this when a model was fitted without [fit_options] npde_nsim and you want the diagnostics without re-running [ferx_fit](ferx_fit.qmd). Unlike CWRES, NPDE/NPD are robust to model nonlinearity and non-Gaussian random effects, and follow N(0, 1) under a correctly specified model.

Usage

ferx_npde(fit, nsim = 1000L, seed = NULL, model = NULL, data = NULL)

Arguments

  • fit: A ferx_fit result, carrying theta, omega, sigma, and (unless overridden) the model_path / data_path captured at fit time.
  • nsim: Number of Monte-Carlo replicates per subject (default 1000). NPDE needs nsim greater than each subject’s observation count for a full-rank simulated covariance; subjects that fail this get NA NPDE (NPD is still computed).
  • seed: Optional integer RNG seed for reproducibility. NULL (default) uses the engine’s built-in default seed.
  • model: Path to the .ferx model file. Defaults to fit$model_path.
  • data: Path to the NONMEM-format CSV. Defaults to fit$data_path.

Seealso

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

Concept

simulation

Value

The input fit, with NPDE and NPD columns added to its sdtab data frame (replacing any existing ones). Because the diagnostics live in fit$sdtab, downstream consumers such as [ferx_xpose](ferx_xpose.qmd) and goodness-of-fit plots pick them up automatically.

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, method = "gn", covariance = FALSE)
fit <- ferx_npde(fit, nsim = 1000L, seed = 12345L)
head(fit$sdtab[, c("ID", "TIME", "NPDE", "NPD")])