Xpose: NONMEM Model Diagnostics and R Workflow Guide

Short answer

Xpose is an open-source R package developed by the Uppsala University Pharmacometrics Research Group for model diagnostics and post-processing in population pharmacokinetic and pharmacodynamic (PopPK/PD) modeling. Primarily paired with NONMEM, Xpose imports estimation outputs and table files to generate standard ggplot2 goodness-of-fit plots, parameter distributions, covariate analyses, and Visual Predictive Checks for clinical pharmacology.

Definition and scope

Xpose is a statistical visualization and model-evaluation toolkit for quantitative clinical pharmacology and pharmacometrics. In population modeling, researchers characterize drug absorption, distribution, metabolism, and excretion (ADME) across patient populations using nonlinear mixed-effects models. While software engines such as NONMEM estimate population parameters and random effects, they output raw text tables and numerical logs that require post-processing.

Xpose transforms these raw files into structured graphical diagnostics. First released in 1998 for S-PLUS by E. Niclas Jonsson and Mats O. Karlsson, Xpose transitioned through the lattice-based xpose4 package to modern xpose (version 0.4.23, maintained on CRAN by Benjamin Guiastrennec, Andrew C. Hooker, Sebastian Ueckert, and Mats O. Karlsson). Modern Xpose is built on ggplot2 and the tidyverse, providing reproducible data import, numerical run summaries, parameter shrinkage assessment, and publication-ready diagnostics.

How it works or how it is used in practice

Xpose automates model evaluation by directly linking NONMEM run directories to R scripting environments.

1. NONMEM Table Export

Modelers specify standardized table outputs in the NONMEM control stream using NOPRINT ONEHEADER options:

$TABLE ID TIME IPRED IWRES CWRES EVID MDV NOPRINT ONEHEADER FILE=sdtab001
$TABLE ID CL V KA ETA1 ETA2 NOPRINT ONEHEADER FILE=patab001
$TABLE ID WT AGE CRCL ALB NOPRINT ONEHEADER FILE=cotab001
$TABLE ID SEX RACE STUD NOPRINT ONEHEADER FILE=catab001

2. Database Import (xpdb)

Inside R, the xpose_data() function parses the run summary (.lst), parameter estimates (.ext), covariance matrix (.cov), and output tables into an xpdb database object:

library(xpose)
xpdb <- xpose_data(runno = '001', dir = 'models/pk/')
summary(xpdb)

3. Goodness-of-Fit (GOF) Diagnostics

Standard diagnostic plots are generated using dedicated, single-line functions:

• Observations vs. Predictions: dv_vs_pred(xpdb) plots observations against population predictions (PRED) to assess structural model fit, while dv_vs_ipred(xpdb) evaluates individual predictions (IPRED).
• Residual Diagnostics: res_vs_pred(xpdb, res = 'CWRES') and res_vs_idv(xpdb, res = 'CWRES') plot conditional weighted residuals against predictions and time to verify symmetric dispersion around zero without systemic bias.
• Residual Spread: absval_res_vs_pred(xpdb) evaluates absolute individual weighted residuals (|IWRES|) to detect residual error misspecification.
• Parameter Distributions: prm_distrib(xpdb) and prm_qq(xpdb) plot random-effect (η) histograms and quantile-quantile distributions to inspect normality and evaluate η-shrinkage.

4. Customization and Export

Because diagnostic figures are native ggplot objects, analysts can add aesthetic layers, customize themes, or stratify using + facet_wrap(~SEX). The xpose_save() utility exports figures for technical reports.

Types or related concepts

Xpose workflows depend on standard table files exported from NONMEM, alongside key differences across package versions.

NONMEM Table File Architecture

Xpose organizes data import around four conventional table classes:

Table Type	Standard Name	Key Variables	Primary Diagnostic Role
Standard Table	sdtab[run]	ID, TIME, DV, PRED, IPRED, WRES, CWRES, IWRES	Basic goodness-of-fit, concentration-time profiles, and residual distributions.
Parameter Table	patab[run]	ID, CL, V, KA, ETA1, ETA2	Empirical Bayes estimates (EBEs), between-subject variability, and η-shrinkage.
Continuous Covariate	cotab[run]	ID, WT, AGE, CRCL, ALB	Scatter plots assessing continuous physiological covariate relationships.
Categorical Covariate	catab[run]	ID, SEX, RACE, ETHN	Discrete covariate evaluation and subgroup stratification.

Modern xpose vs. Legacy xpose4

• Modern xpose (v0.4+): Built natively on ggplot2 and the tidyverse. It uses programmatic, pipe-friendly (%>%) workflows, pairs with the vpc package for simulation diagnostics, and supports modern modeling suites like nlmixr2 via xpose.nlmixr2.
• Legacy xpose4: Built on Trellis/lattice graphics. It relied on an interactive console menu (xpose4()), which lacked the scripting flexibility and modular layering of modern ggplot2 pipelines.

Where it matters for labs, clinics or supply decisions

Xpose serves quantitative pharmacology teams across preclinical, clinical, and regulatory milestones:

• Regulatory Submissions: Health authorities such as the US FDA and EMA require goodness-of-fit graphics in population PK study reports. Reviewers assess CWRES plots and individual fits to confirm model stability and validate exposure-response conclusions.
• Clinical Trial Simulations: Validated population PK/PD models provide the basis for clinical trial simulations. Xpose diagnostics confirm that structural models and variability estimates are sound before simulating dosing regimens or pediatric dose extrapolations.
• Auditable Data Governance: In laboratories adhering to scientific data management systems (SDMS), scripted Xpose workflows replace manual plotting, ensuring reproducibility and alignment with ICH E9 statistical principles.
• Translational Discovery Pipelines: Discovery teams correlate early compound properties—including Lipinski rule of five criteria—with preclinical PK data. Xpose provides the visual validation layer for pharmacokinetic models, frequently alongside custom routines developed with the Rcpp package for high-performance R routines.

Common misunderstandings

• Misunderstanding: Xpose estimates population PK/PD model parameters.
  Reality: Xpose does not perform regression or parameter estimation. It is strictly a diagnostic post-processing tool. Estimation occurs in engines like NONMEM or nlmixr2; Xpose then reads the generated output files.
• Misunderstanding: A lower objective function value (OFV) eliminates the need for graphical diagnostics.
  Reality: While OFV decreases indicate improved mathematical fit, they can mask severe residual bias, non-random error distributions, or high η-shrinkage that only graphical inspections reveal.
• Misunderstanding: Any arbitrary NONMEM table works with Xpose without specific formatting.
  Reality: Automated parsing depends on standard file naming conventions (sdtab, patab, cotab, catab) and headers created with NOPRINT ONEHEADER. Non-standard tables require manual variable mapping.
• Misunderstanding: Modern xpose relies on interactive console prompts.
  Reality: Modern Xpose is fully programmatic, enabling integration into automated reporting pipelines, R Markdown scripts, and Quarto documents.

FAQ

What is the difference between Xpose and Xpose4?

Xpose4 is the older, lattice-based package that used an interactive console menu. Modern Xpose (version 0.4+) was completely rewritten around ggplot2, providing programmatic syntax, easy plot customization, and tidyverse compatibility.

Which table files are essential for basic Xpose diagnostics?

At minimum, the standard table (sdtab[run]) containing ID, TIME, DV, PRED, IPRED, and residual metrics (such as CWRES) is required for core goodness-of-fit evaluation. Parameter tables (patab) and covariate tables (cotab, catab) are needed for shrinkage and covariate plots.

Why are conditional weighted residuals (CWRES) preferred over WRES?

Standard WRES uses a first-order approximation around population means, which can introduce artificial patterns when models are fitted with First-Order Conditional Estimation (FOCE). CWRES conditions residuals on individual parameter estimates, offering an unbiased assessment of structural fit.

Can Xpose work with software other than NONMEM?

Yes. While primarily developed for NONMEM, extensions such as xpose.nlmixr2 allow researchers to use Xpose diagnostic functions with open-source modeling engines in R.

Sources

• Comprehensive R Archive Network (CRAN). Package ‘xpose’: Diagnostics for Pharmacometric Models (Version 0.4.23). Published March 2, 2026. Accessed November 9, 2026.
• Uppsala University Pharmacometrics Research Group. Xpose Official Documentation and Vignettes. Accessed November 9, 2026.
• Keizer RJ, Karlsson MO, Hooker A. Modeling and Simulation Workbench for NONMEM: Tutorial on Pirana, PsN, and Xpose. CPT: Pharmacometrics and Systems Pharmacology. 2013;2(6):e50. doi:10.1038/psp.2013.24. PMCID: PMC3697037. Accessed November 9, 2026.
• Jonsson EN, Karlsson MO. Xpose–an S-PLUS based population pharmacokinetic/pharmacodynamic model building aid for NONMEM. Computer Methods and Programs in Biomedicine. 1999;58(1):51-64. doi:10.1016/s0169-2607(98)00067-4. PMID: 10195646. Accessed November 9, 2026.