27

xpose

Diagnostics for Pharmacometric Models

Diagnostics for non-linear mixed-effects (population) models from 'NONMEM' < http://www.iconplc.com/innovation/nonmem/>. 'xpose' facilitates data import, creation of numerical run summary and provide 'ggplot2'-based graphics for data exploration and model diagnostics.

travis_status appveyor status cran_version codecov downloads

xpose was designed as a ggplot2-based alternative to xpose4. xpose aims to reduce the post processing burden and improve diagnostics commonly associated the development of non-linear mixed effect models.

Installation

# Install the lastest release from the CRAN
install.packages('xpose')
 
# Or install the development version from GitHub
# install.packages('devtools')
devtools::install_github('UUPharmacometrics/xpose')

Getting started

Load xpose

library(xpose)

Import run output

xpdb <- xpose_data(runno = '001')

Glance at the data object

xpdb
run001.lst overview: 
 - Software: nonmem 7.3.0 
 - Attached files (memory usage 1.3 Mb): 
   + obs tabs: $prob no.1: catab001.csv, cotab001, patab001, sdtab001 
   + sim tabs: $prob no.2: simtab001.zip 
   + output files: run001.cor, run001.cov, run001.ext, run001.grd, run001.phi, run001.shk 
   + special: <none> 
 - gg_theme: theme_readable 
 - xp_theme: theme_xp_default 
 - Options: dir = analysis/models/pk/, quiet = TRUE, manual_import = NULL
Model summary
summary(xpdb, problem = 1)
Summary for problem no. 0 [Global information] 
 - Software                      @software   : nonmem
 - Software version              @version    : 7.3.0
 - Run directory                 @dir        : analysis/models/pk/
 - Run file                      @file       : run001.lst
 - Run number                    @run        : run001
 - Reference model               @ref        : 000
 - Run description               @descr      : NONMEM PK example for xpose
 - Run start time                @timestart  : Mon Oct 16 13:34:28 CEST 2017
 - Run stop time                 @timestop   : Mon Oct 16 13:34:35 CEST 2017

Summary for problem no. 1 [Parameter estimation] 
 - Input data                    @data       : ../../mx19_2.csv
 - Number of individuals         @nind       : 74
 - Number of observations        @nobs       : 476
 - ADVAN                         @subroutine : 2
 - Estimation method             @method     : foce-i
 - Termination message           @term       : MINIMIZATION SUCCESSFUL
 - Estimation runtime            @runtime    : 00:00:02
 - Objective function value      @ofv        : -1403.905
 - Number of significant digits  @nsig       : 3.3
 - Covariance step runtime       @covtime    : 00:00:03
 - Condition number              @condn      : 21.5
 - Eta shrinkage                 @etashk     : 9.3 [1], 28.7 [2], 23.7 [3]
 - Epsilon shrinkage             @epsshk     : 14.9 [1]
 - Run warnings                  @warnings   : (WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.

Summary for problem no. 2 [Model simulations] 
 - Input data                    @data       : ../../mx19_2.csv
 - Number of individuals         @nind       : 74
 - Number of observations        @nobs       : 476
 - Estimation method             @method     : sim
 - Number of simulations         @nsim       : 20
 - Simulation seed               @simseed    : 221287
 - Run warnings                  @warnings   : (WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.
                                               (WARNING 22) WITH $MSFI AND "SUBPROBS", "TRUE=FINAL" ...

Generate diagnostics

Standard goodness-of-fit plots
dv_vs_ipred(xpdb)
Individual plots
ind_plots(xpdb, page = 1)
Visual predictive checks
xpdb %>% 
  vpc_data(stratify = 'SEX', opt = vpc_opt(n_bins = 7, lloq = 0.1)) %>% 
  vpc()
Distribution plots
eta_distrib(xpdb, labeller = 'label_value')
Minimization diagnostics
prm_vs_iteration(xpdb, labeller = 'label_value')
And many other features!

Recommended reading

The xpose website contains several useful articles to make full use of xpose

When working with xpose, a working knowledge of ggplot2 is recommended. Help for ggplot2 can be found in:

News

xpose 0.4.3

General

  • Fixed bug in get_prm()/prm_table() where off diagonal correlations were improperly computed.
  • Fixed bug in print.xpose_data()where a warning from stringi was returned.
  • Fixed multiple bugs introduced by the new versions of tidyverse packages
  • Added compatibility to ggplot2 v3.0.0

xpose 0.4.2

General

  • Address CRAN requests
  • Improved internal structure of VPC
  • Fixed bug with vpc 1.0.1

xpose 0.4.1

General

  • Improved integration of the xpose.nlmixr package
  • Prevented a problem in the print() function with the upcoming ggplot2 version
  • Fixed bug in summary() where missing estimation method was reported if NM code written as METH=... instead of METHOD=...
  • Fixed bug where labels in prm_table(), get_prm() were missing with a commented row in $THETA, $OMEGA or $SIGMA
  • Fixed bug in prm_table(), get_prm() where only NA would be reported when missing the -1000000006 record in the .ext file (i.e. NM <7.3)
  • Prevented negative RSE in prm_table() and get_prm()
  • Improved description of the prm_table() output
  • Fixed bug in summary() with non numeric covariance step time
  • Fixed bug in ind_plots() where the aesthetics would get mixed up if the variable names were changed
  • Small fixes to vignettes, documentations and website

xpose 0.4.0

General

  • Added xpdb memory usage to print.xpose_data()
  • Replaced print.prm.data() to prm_table()
  • Fixed documentation

Data import/edit

  • Added compatibility with dplyr::n() when editing xpdb #51
  • Added get_special() to access special data
  • Improved get_prm() labeller parsing with OMEGA and SIGMA BLOCKS
  • get_prm() and prm_table():
    • Both gained a transform argument to disable parameter transformation
    • RSE is now always reported (also for untransformed)
    • Corrected RSE for off-diagonal elements from OMEGA and SIGMA when output as correlation and SE when output as standard deviation
  • Added list_data(), list_files() and list_special() to get info on the data structure in the xpdb
  • Renamed the arguments problem, subprob, method and source to .problem, .subprob, etc. for consistency with dplyr functions.
  • Improved error checking for themes in xpose_data
  • Improved error checking in get_prm()

Plots

  • print.xpose_plot() now displays a message when the number of facets is > 20, informing that many panels are being printed and that it may take a while to render the plot
  • Improved .problem, .subprob and .method error checking

xpose 0.3.0

General

  • Improved documentation and testing
  • Improved compatibility with NONMEM 7.4.1
  • Improved website look, and content with new 'FAQ' and 'Plot' sections and a cheat-sheet
  • Multiple bug small bug fixes and code improvements
  • Added multiple page functionality to all plots and xpose_save()
  • Added get_prm() function

Data import/edit

  • Improved dir and file arguments usage
  • Improved error robustness of xpose_data()
  • Added new dplyr verbs for xpdb editing: slice(), select(), rename(), distinct(), summarize(), group_by() and ungroup()
  • dplyr verbs can now also be used to edit vpc data
  • Added irep() function to add simulation counter to any dataset
  • Bug fix in read_nm_files() not properly reporting FO method
  • Bug fix in read_nm_tables() not properly parsing data (missing minus signs) in some very specific cases

Plots

  • Small modifications to xp_theme() defaults
  • Faceting options can now be defined globally in the xp_theme
  • Added amt_vs_idv() plot
  • Improved faceting of minimization plots
  • Multiples improvements to the vpc_data() and vpc() functions.
  • More keywords added to template_titles

xpose 0.2.0

General

  • Renamed package xpose
  • Added example dataset xpdb_ex_pk
  • New internal data structure using nested tibbles
  • Improvement of documentation, and testing

Data import

read_nm_tables()

  • Handles NONMEM tables in .csv, .zip format
  • Handles multiple $PROB and tables with FIRSTONLY option
  • Added option to import data manually as in xpose4 with manual_nm_import()
  • Added indexing of variable and convenience functions to edit it: set_vars_type(), set_vars_label(), set_vars_units()

read_nm_files()

  • Now imports multiple $PROB and sub-problems

Summary

  • Added print() and summary() methods for xpdb
  • Added list_vars() function to list available variables
  • Added many new keywords to template_titles

Access xpdb

  • Added convenience functions to access data from xpdb get_code(), get_data(), get_file(), get_summary().
  • Added a method for xpdb to dplyr::filter()

Plots

  • Changed cwres_vs_idv, type residual functions to more general res_vs_idv(res = 'CWRES') functions
  • Implemented/improved general plotting functions: xplot_distrib(), xplot_qq(), xplot_scatter(), with convenience function to fetch data in xpdb data_opt_set().
  • Implemented: dv_vs_idv(), ipred_vs_idv(), pred_vs_idv(), dv_preds_vs_idv(), ind_plots(), vpc(), prm_distrib(), eta_distrib(), res_distrib(), cov_distrib(), prm_qq(), eta_qq(), res_qq(), cov_qq(), prm_vs_iteration(), grd_vs_iteration().
  • Updated/renamed: theme_bw2(), theme_readable(), theme_xp_default(), theme_xp_xpose4().

VPC

ggxpose 0.1.0

First commit

  • Proof of concept pre-release around simple goodness-of-fit functions like dv_vs_ipred()

Definition of core functions and workflow

  • Defined the xpose_geom() core function to specifically direct arguments to ggplot2 layers
  • Defined the concept of template titles
  • Define the templates for xpose_theme()
  • Makes use of the tidyverse and pipes %>%

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("xpose")

0.4.4 by Benjamin Guiastrennec, a month ago

https://github.com/UUPharmacometrics/xpose

Report a bug at https://github.com/UUPharmacometrics/xpose/issues

Browse source code at https://github.com/cran/xpose

Authors: Benjamin Guiastrennec [aut, cre, cph] , Andrew C. Hooker [aut, cph] , Sebastian Ueckert [aut, cph] , Mike K. Smith [ctb] , Mats O. Karlsson [aut, cph]

Documentation:   PDF Manual  

LGPL-3 license

Imports dplyr, ggforce, grDevices, purrr, readr, rlang, stringr, tibble, tidyr, utils, stats, vpc

Depends on ggplot2

Suggests gridExtra, rmarkdown, knitr, testthat, plotly, webshot, mvtnorm

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug