Population predictions from a NLME model

Description

Computes population-level predictions (eta = 0) for all subjects.

Usage

ferx_predict(model, data = NULL, fit = NULL)

Arguments

  • model: Path to a .ferx model file
  • data: Path to a NONMEM-format CSV. When omitted, the model file’s [data] block (path = ...) is used. The DV column may be left empty (. / NA) on the sampling rows - PRED is what this function produces and the DV is never read, so an empty cell means “predict here”. Rows marked MDV = 1 are excluded, as always.
  • fit: Optional ferx_fit result. When provided, predictions use fit$theta instead of the model file’s initial estimate for theta.

Errors raised by the engine

A model or dataset the engine refuses is an R error, never a NULLresult. Where the engine’s validation pass names the finding, the error has class ferx_engine_error and carries code, block, line and suggestion - the same condition a refused [ferx_fit](ferx_fit.qmd) raises, so one tryCatch(..., ferx_engine_error = ) handler covers every entry point. A failure the validation pass cannot attribute to one diagnostic is raised as an ordinary error carrying the engine’s message.

Seealso

Other simulation: [ferx_calc_npde](ferx_calc_npde.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

A data.frame with columns: ID, TIME, PRED. The frame carries a simulation_warnings attribute (a character vector, empty for a clean run) holding the engine’s data-reader diagnostics for data - the same ones ferx_fit() returns in fit$warnings, e.g. a record kept as a design point because its DV was empty, a dose that never landed, or a covariate with no value for some subjects. They are also re-emitted as a single R warning.

Examples

ex <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, method = "gn", covariance = FALSE)
preds <- ferx_predict(ex$model, ex$data, fit = fit)
head(preds)