29

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.5 by Benjamin Guiastrennec, 10 days 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  

Task views: Analysis of Pharmacokinetic Data

LGPL-3 license

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

Depends on ggplot2

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

Suggested by nlmixr.

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