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, Mats O. Karlsson and E. Niclas Jonsson
Xpose 4 is 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.
To install xpose you will need:
Install xpose in R using one of the following methods:
install_github()approach requires that you build from source, i.e.
makeand compilers must be installed on your system -- see the R FAQ for your operating system; you may also need to install dependencies manually.
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:
xpdb5 <- xpose.data(5)
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: http://xpose.sourceforge.net/bestiarium_v1.0.pdf
Andrew Hooker (andrew.hooker at farmbio.uu.se) should be able to get you an answer if you run into trouble. The website http://xpose.sf.net 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 http://www.gnu.org/licenses/.
None at present, but there will certainly be a few
Xpose 4 News/Change-log
Changes in version 4.6.0
o Update to xpose.VPC() so that outliers can be identified and plotted.
o Update to xpose.VPC() so that for any lines in the VPC they are plotted at the median of the observed values of the X axis for all bins by default.
o Update to xpose.VPC() to allow a rug at the bottom of the plot showing where the bins are located.
o Update to the namespace so that only lattice is loaded when loading xpose.
o All documentation now written in roxygen
o Updates to boot GAM and boot SCM plots and documentation.
o Various small bug fixes.
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 associated 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 functionality for plotting the delta mean output from the vpc tool in PsN. Option is for xpose.VPC() and can be turned on using PI.delta.mean=T. 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(xpose.data) 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(max.plots.per.page=1), 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 dOFV.vs.id 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 behavior 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(Pi.ci=T,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 Sebastien Bihorel for input which helped create this function. o Added the ability to apply functions to the x-axis 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 cwres.vs.pred.bw() was fixed. Previously cwres.vs.pred.bw() gave the
same result as cwres.vs.idv.bw().
o Fixed xpose.VPC() bug causing plots to not be created in some
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 PI.ci "area" plots so that they match
the "line" plots. See 'PI.ci.area.smooth' in
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
o Changed all functions in xpose4specific that began with "abs." to
begin with "absval." to be consistent 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 184.108.40.206.7
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 scatter-plot 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 220.127.116.11.5 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. abs.wres.vs.pred.by.cov) - 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 18.104.22.168.3 o Bug in 'subset' argument to individual plots corrected (JW)
Changes in version 22.214.171.124.2 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 Scatter-plot matrices added (JW) o QQ plots for parameters and covariates added (JW) o Generic functions renamed for consistency (JW)
Changes in version 126.96.36.199.1 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 188.8.131.52 o GAM added (AH) o CWRES plots and functions added (AH) o gam package now required o Known bugs corrected
Changes in version 184.108.40.206 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 220.127.116.11.1 o Ind.plots.R updated (AH)
Changes in version 18.104.22.168 o Xpose 4 is a completely rewritten version of Xpose 3.1, and so everything has changed.