Build an Xpose object from a ferx fit

Description

Produces an in-memory Xpose object so that all downstream Xpose diagnostics (goodness-of-fit, covariate, and parameter plots) work out-of-the-box on a ferx fit, without writing NONMEM-style table files to disk.

Usage

ferx_xpose(
  fit,
  backend = c("xpose", "xpose4"),
  continuous = NULL,
  categorical = NULL,
  runno = 1L,
  iterations = TRUE
)

Arguments

  • fit: A ferx_fit object returned by [ferx_fit](ferx_fit.qmd).
  • backend: Which Xpose package to target: "xpose" (the modern tidyverse package, the default) or "xpose4" (the classic S4 package).
  • continuous, categorical: Optional character vectors naming covariates to treat as continuous / categorical, overriding the fit$covariate_types classification. Names not present among the fit’s covariates are ignored with a warning.
  • runno: Run number recorded on the resulting Xpose object (cosmetic).
  • iterations: Logical; when TRUE (the default) and the fit carries a per-parameter optimizer trace (from optimizer_trace = TRUE), populate the $files slot so xpose::prm_vs_iteration() and xpose::grd_vs_iteration() work. Ignored by the "xpose4" backend and a no-op when no trace is present.

Details

The mapping from fit to the standard NONMEM table columns is:

  • sdtab from fit$sdtab: ID, TIME, DV, PRED, IPRED, CWRES, IWRES, and (when present) NPDE, NPD, CMT, OCC, CENS, TAFD, TAD. RES = DV - PRED and IRES = DV - IPRED are derived; WRES is set to NA (ferx does not compute the FO-weighted residual). NPDE/NPD (present when the fit ran with npde_nsim > 0) are mapped to the residual role, so Xpose residual plots can use them.
  • patab: individual parameter values (fit$individual_estimates) and empirical-Bayes etas (fit$ebe_etas), repeated for every observation row of each subject.
  • cotab/catab: covariates, split into continuous and categorical using fit$covariate_types (override with the continuous and categorical arguments). Covariate values are taken from fit$sdtab when echoed there, otherwise carried forward (LOCF) from fit$covtab.

Estimation-iteration trace

When the fit was run with optimizer_trace = TRUE and iterations = TRUE(the default), the per-iteration parameter and gradient trajectories are populated into the $files slot of the returned "xpose" object as synthetic NONMEM .ext / .grd tables, so xpose::prm_vs_iteration() (parameter value vs iteration) and xpose::grd_vs_iteration() (gradient vs iteration) work out-of-the-box. The .ext table carries one column per parameter (using the fit’s declared parameter names, e.g. TVCL, ETA_CL) plus OBJ; the .grd table carries one GRD(n) column per parameter and is only emitted for gradient-based methods (a derivative-free trace has no gradient to plot). When no per-parameter trace is present - the fit was run without optimizer_trace = TRUE, or predates ferx recording per-parameter values - the slot is left empty: the iteration plots then raise xpose’s usual “no files” message, while the table (goodness-of-fit / covariate) plots are unaffected. For an OFV-over-iterations view use [plot.ferx_fit](plot.ferx_fit.qmd). Only the "xpose" backend populates this slot; "xpose4" ignores iterations.

Value

For backend = "xpose", an xpose_data object (with a populated $files slot when an optimizer trace is present, see the “Estimation-iteration trace” section). For backend = "xpose4", an xpose.data (S4) object.

Examples

fit  <- ferx_fit("warfarin.ferx", data = "warfarin.csv",
                 optimizer_trace = TRUE)
xpdb <- ferx_xpose(fit)
xpose::dv_vs_ipred(xpdb)
xpose::prm_vs_iteration(xpdb)   # parameter trajectories (needs the trace)
xpose::grd_vs_iteration(xpdb)   # gradient trajectories (gradient methods)

xpdb4 <- ferx_xpose(fit, backend = "xpose4")
xpose4::basic.gof(xpdb4)