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
)

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

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.

Limitations

Only the table data is populated, not the estimation-iteration trace. Xpose functions that read the NONMEM .ext / .grd files - notably xpose::prm_vs_iteration() and xpose::grd_vs_iteration() - therefore do not work on the returned object: ferx records only a scalar OFV and gradient norm per iteration, not the per-parameter value/gradient trajectory those plots need. For an OFV-over-iterations view use [ferx_plot_trace](ferx_plot_trace.qmd) (requires optimizer_trace = TRUE at fit time).

Value

For backend = "xpose", an xpose_data object. For backend = "xpose4", an xpose.data (S4) object.

Examples

fit  <- ferx_fit("warfarin.ferx", data = "warfarin.csv")
xpdb <- ferx_xpose(fit)
xpose::dv_vs_ipred(xpdb)

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