Simulate from a NLME model

Description

Simulates observations from a parsed model with between-subject variability and residual error. When a fit is supplied, the fitted theta, omega, and sigma replace the model file’s initial values - which is the usual flow after [ferx_fit](ferx_fit.qmd) (e.g. for posterior-predictive checks or VPCs).

Usage

ferx_simulate(
  model,
  data,
  n_sim = 1L,
  seed = 42L,
  fit = NULL,
  match = FALSE,
  horizon = NULL
)

Arguments

  • model: Path to a .ferx model file
  • data: Path to a NONMEM-format CSV (provides population structure: doses, obs times)
  • n_sim: Number of simulation replicates
  • seed: Random seed for reproducibility
  • fit: Optional ferx_fit result. When provided, simulation uses fit$theta, fit$omega, and fit$sigma instead of the model file’s initial values.
  • match: Propensity-score matching method (default FALSE). When enabled, each replicate’s drawn etas are reassigned to subjects by propensity-score matching against the subjects’ fitted (posthoc) etas - Mahalanobis matching under the model omega. This pairs each subject’s observed dosing/sampling design with a similar drawn eta, correcting VPC bias from treatment adaptation in real-world data (e.g. longer dosing intervals for high-clearance patients). Accepts:
  • FALSE / "none": No matching (default).
  • TRUE / "optimal": Global linear-assignment minimum Mahalanobis distance (MatchIt(method = "optimal")); best on average in simulation, the recommended method.
  • "nearest": Greedy nearest-neighbour (MatchIt(method = "nearest", distance = "mahalanobis")).
  • "rank": Pair by the rank of each eta’s Mahalanobis norm.Requires data to be real observed data (every subject must have observations, so its posthoc eta can be computed). The posthoc etas are computed at the fitted parameters when fit is supplied, otherwise at the model file’s initial values.
  • horizon: Optional administrative censoring time for time-to-event (TTE) endpoints. A finite, positive horizon is required to simulate a drug-driven (joint PK-TTE) model: the augmented hazard ODE is integrated until the cumulative hazard reaches -log U, censoring at horizon if no event fires (ferx-core #564). Purely-Gaussian models ignore it. NULL (default) leaves it unset.

Seealso

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

Concept

simulation

Value

A data.frame. Gaussian rows carry DRAW, SIM, ID, TIME, CMT, IPRED, DV_SIM (with OBSERVED = NA). For a joint PK-TTE model each subject also yields a TTE row on the event CMT, where TIME is the sampled event/censor time and OBSERVED is 1 (event before horizon) or 0 (right-censored at it); its IPRED and DV_SIM are NA. Use is.na(OBSERVED) to separate continuous rows from event rows.

Examples

ex <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, method = "gn", covariance = FALSE)
sim <- ferx_simulate(ex$model, ex$data, n_sim = 10L, seed = 1L, fit = fit)
head(sim)

# Propensity-score-matched simulation for a real-world-data VPC:
sim_pm <- ferx_simulate(ex$model, ex$data, n_sim = 10L, seed = 1L,
                        fit = fit, match = "optimal")