Tools for Nonlinear Mixed-Effect Model Building and Diagnostics

A collection of functions to be used as a model building aid for nonlinear mixed-effects (population) analysis using NONMEM. It facilitates data set checkout, exploration and visualization, model diagnostics, candidate covariate identification and model comparison.

by Andrew C. Hooker, Justin J. Wilkins, Mats O. Karlsson and E. Niclas Jonsson

Xpose 4 is a ground-floor rewrite of Xpose 3.1. Chief amongst the enhancements in the new version is the migration from S-PLUS to R, a free, multi-platform statistical environment. We have also added direct access to Xpose functions from the command line, and, through R, access to Xpose tools by third-party applications.

To install xpose you will need:

  • R version >=2.2.0. Download the latest version of R from
  • the gam package. Install the latest version from CRAN. Write at the R command line (type ?install.packages in R for more details):

Install xpose in R using one of the following methods:

  • latest stable release -- From CRAN. Write at the R command line:
  • Latest development version -- from Github. Note that the command below installs the "master" (development) branch; if you want the release branch from Github add ref="release" to the install_github() call. The install_github() approach requires that you build from source, i.e. make and compilers must be installed on your system -- see the R FAQ for your operating system; you may also need to install dependencies manually.

The Hmisc package is also recommended. to install, write at the R command line (type ?install.packages in R for more details):


Start R

To use the classic menu system, type at the R command prompt:


Each function is independently available from the command line, once the Xpose library is loaded. For example, assuming your run is called 'run5.mod', you might do the following:

  • Import data
  xpdb5 <-
  • Display goodness-of-fit plots

More help is available in the online documentation, which can be found by typing (for example) ?xpose at the R command line.

A more detailed description of Xpose with example plots and explanaitions for most of the functions in the package is available in our Bestiarium:

Andrew Hooker (andrew.hooker at should be able to get you an answer if you run into trouble. The website should also be of help.

Bugfix releases will be released regularly, fixing any problems that are found.

Xpose 4 is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details

None at present, but there will certainly be a few


Xpose 4 News/Changelog

Changes in version 4.5.3

o Update to ind.plots() to allow subsets on a per-y-variable basis.
Useful to show IPRED and PRED in a finer grid than DV. See option “y.vals.subset”.

o Update to how axes limits are computed with xpose.plot.default.

o Fix for using expression() in the ylb argument of xpose.VPC.

o Various small bug fixes.

Changes in version 4.5.2

o Internal release

o Updates to read.bootscm.par.est()

Changes in version 4.5.1

o Internal release

o Updated xpose.gam to work with the latest version of the gam package

o Updated kaplan.plot to allow for ylim specification when "cov" argument is used.

o Updated compute.cwres and associted functions to work with NONMEM 7.

o Fixed warnings created in xpose.VPC.categorical when creating personalized x and y axis labels.

Changes in version 4.5.0

o External release with just one package instead of five.

o Added to ind.plots so that when there is only one data point for an individual, the PRED and IPRED show up in the plot.

Changes in version 4.4.3

o Internal release

o Added funcitonality for plotting the delta mean output from the vpc tool in PsN. Option is for xpose.VPC() and can be turned on using See ?xpose.panel.default for more information.

Changes in version 4.4.2

o Internal release

o Removed some default messages that were print to the screen when running xpose.VPC(). can change back to previous behavior with option verbose=TRUE.

o Combined the five packages of xpose into one package.

o Updated the Histogram functionality.

o New plots randtest.hist() and boot.hist() for creating histograms of results from PsN's 'randtest' and 'bootstrap' tools.

o Updated the xpose.VPC() function to handle plotting of mean values from simulations.

Changes in version 4.4.1

o Updates to kaplan.plot.R (thanks to Leonid Gibiansky for reporting the problems)

o kaplan.plot.R: Removed debugging command that was mistakenly left in function

o kaplan.plot.R: "ylab" argument is now passed to the plot when cov option is used.

o kaplan.plot.R: Using the cov option with repeated censoring and no observations to break up the chain then the mean value calculation was wrong (only used the surviving IDs and the last censored ID). Fixed now.

o Changed the "aspect" argument for all plots to default to "fill".
Previously it was "1".

Changes in version 4.4.0

o Added bootstrap of the GAM and diagnostics for the boostrap of the PsN function boot_scm.

Changes in version 4.3.6

o fixed the plot in the classic menu system "Weighted residuals vs covariates".

Changes in version 4.3.5

o Updated help files with workable examples, and an example dataset. Look at data(simpraz.xpdb), simprazExample() and example( for dataset examples and example(basic.gof) and example(cwres.vs.idv) for plot examples. Most of the xpose4specific functions now have examples that can be run with example().

o Updated kaplan.plot() so that the kaplan-meier mean covariate (KMMC) plot can be created. Also added more options for adjusting plot properties.

o New gofSetup() command to create your own customized series of GOF plots.

o fixed how RSE values were reported on runsum() when the parameter was fixed.

o Fixed argument to xpose.VPC.categorical(, so that only one plot per page was possible.

o Fixed xpose.VPC() so that the psn option for vpc "confidence_interval=X" works.

o Fixed compute.cwres() function that wasn't computing anything (and returning an error).

Changes in version 4.3.2

o Fixed bug in xpose.VPC when asking for logx=T (didn't work previously).

o Fixed for when there are ties in individual dOFV drops.

Changes in version 4.3.0 o Updated read.nm.tables so that comma separated NONMEM 7 files can be read into Xpose.

o Changing the behaviour of xpose.multiple.plot.default. Now multiple plots are returned as objects just like single plots are (no automatic printing from the function that created the plot list). This is accomplished by defining a new class - xpose.multiple.plots - and corresponding print and show methods for that class.

o Updated xpose.VPC, xpose.VPC.categorical and xpose.VPC.both to handle the new format of PsN vpc_results.csv files.

o xpose.VPC.categorical now has a new option: censored (T or F) which will create BLOQ VPC plots when TRUE.

o xpose.VPC.both tries to combine continuous and categorical BLOQ plots.

o page numbers can be turned off in multiple page plots using the page.numbers option (T or F).

Changes in version 4.1.0 o Updated ind.plots(), the function is much more flexible now. o Added graphical options to xpose.VPC.categorical() o Fixed logy=T option for xpose.VPC(,logy=T). o Fixed logy=T and logx=T option (bug resulting in error). o VPC changed to require that y-axis be continuous as default. o Fixed classic version of parm.vs.parm() plot. o Fixed runsum(). Previous version had a line between each line in model file. o Added a new function change.xvardef(), which replaces much of the previous change functions. Thanks to S?bastien Bihorel for input which helped create this function. o Added the ability to apply functions to the xaxis of plots. The function options are now called funx and funy. o Added support for reading NONMEM 7 table and output files. o Added functions for odd type (categorical, TTE, count) plots including VPCs. o Updated handling of PsN vpc output file o Updated interpretation of categories in xpose.VPC.categorical()

Changes in version 4.0.4 o was fixed. Previously gave the same result as o Fixed xpose.VPC() bug causing plots to not be created in some situations.
o Added functionality to xpose.VPC() so that users can define their own titles for each subplot if stratification is used in the VPC. see ?xpose.VPC for more info. o Updated method for opening graphical devices in windows to be consistent with the new methods used in R version 2.8.0. o Added functionality to allow the user to plot vertical and horizontal lines in histograms. See ?xpose.panel.histogram for more information. o Fixed small bug with xpose.panel.splom().

Changes in version 4.0.3 o in compute.cwres() a debugging flag had been left in the file resulting in R going into debugging mode when this function was called. This has been fixed.

Changes in version 4.0.2 o Added ability to smooth the "area" plots so that they match the "line" plots. See '' in xpose.pandel.default() o Added 'logx' and 'logy' functionality to the PI plots. o Changed the par.summary and cov.summary routines and removed functions doing almost the same thing (adding that functionality to the current functions). o fixed GAM plot problems in xp.plot() and added more support for GAM from the command line. o Fixed a problem with ind.plots() when the ID variable is not called ID. o Changed all functions in xpose4specific that began with "abs." to begin with "absval." to be consistant with the rules for generic function definitions in R. o Changed name of add.abs() to add.absval(). o Changed name of par.summary() to parm.summary().
o Changed name of param.vs.cov() to parm.vs.cov(). o Changed name of param.vs.param() to parm.vs.parm().

Changes in version 4.0.1 o Added functionality for visual predictive checks o Added functionality for numerical predictive checks

Changes in version o Added generic functions xpose.draw.table, xpose.draw.cell, xpose.get.c and xpose.get.r for drawing tables using the graphics device (JW) o Added specific function param.table to display parameter estimates using the graphics device (e.g. in a PDF file) (JW) o Added additional specific functions for: o Added additional specific functions: IWRES distribution (histogram) (iwres.dist.hist) o Added additional specific functions: IWRES distribution (QQ) (iwres.dist.qq) o Added additional specific functions: ETA distribution (histogram) (ranpar.dist.hist) o Added additional specific functions: ETA scatterplot matrices (ranpar.splom) o Added additional specific functions: ETAs vs covariates (ranpar.vs.cov) o Added additional specific functions: Parameter tables on the graphics device
(param.table) o Updated compute.cwres function so that it would work without xpose 4 Just 'source' the file (compute.cwres.R) and it should work (AH) o fixed problems with the run summary function (AH) o added new general class of printing multiple plot objects on the same page (AH) o Fixed bug with plotting results of GAM (AH)

Changes in version o Bugs in 'groups' argument fixed in xpose.plot.default, dv.vs.pred.ipred, dv.preds.vs.idv (multiple values of x or y not properly handled) (JW) o File devices (e.g. pdf, postscript, etc) now work correctly in all functions (JW) o Bug in multiple-page covariate plots fixed (only the first page would display) (JW) o Bug in reading table files could sometimes leave file debris, which could interfere with reading subsequent data - fixed (JW) o Bug in covariate checking could sometimes cause plot functions to fail (e.g. - fixed (JW) o Bug in the classic menu system prevented display of some plots - fixed (JW) o Bug in the classic menu system prevented display of some plots - fixed (JW) o Bug in CWRES calculation fixed (AH) o Bug in parameter histogram display fixed (JW) o Missing values (defaults to -99) now handled correctly (JW) o QQ plots no longer display categorical variables (JW)

Changes in version o Bug in 'subset' argument to individual plots corrected (JW)

Changes in version o Online documentation cleaned up (JW) o Numerous small bugs fixed (JW) o *nix support added (JW) o Multipage plots now create stacks of display windows, rather than stacks of plots in a single window (JW) o Scatterplot matrices added (JW) o QQ plots for parameters and covariates added (JW) o Generic functions renamed for consistency (JW)

Changes in version o Bugs in CWRES application and documentation fixed (AH) o Bugs in histogram functions fixed - lack of defined covariates no longer causes crash - customization options now work

Changes in version o GAM added (AH) o CWRES plots and functions added (AH) o gam package now required o Known bugs corrected

Changes in version o SUBSET functionality fixed for all procedures o Preferences, summaries and data checkout implemented o Box and whisker plots now do what their preferences tell them to o 'label' function renamed to 'xlabel' for compatibility o Hmisc package now required o Many small additions and tweaks o R package functionality fixed

Changes in version o Ind.plots.R updated (AH)

Changes in version o Xpose 4 is a completely rewritten version of Xpose 3.1, and so everything has changed.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


4.6.0 by Andrew C. Hooker, 3 months ago

Browse source code at

Authors: Andrew C. Hooker [aut, cre, cph], Mats O. Karlsson [aut, cph], Justin J. Wilkins [aut], E. Niclas Jonsson [aut, trl, cph], Ron Keizer [ctb] (functionality for bootstrap of GAM and SCM)

Documentation:   PDF Manual  

LGPL (>= 3) license

Imports Hmisc, survival, dplyr, methods, lazyeval, gam, splines, grid, readr

Depends on lattice

Suggests testthat

Depended on by nonmem2R.

See at CRAN