The files attached to an xpdb object can be displayed to the console simply by writing the xpdb name to the console or by using the print() function. Any of these files can be accessed from the xpdb using one of the functions listed below.
The get_code() function can be used to access the parsed model code from the xpdb. This code was used to create the summary and find table names. The parsed code can be used to get additional information about the run. If the argument .problem is specified a subset of the code can be returned based on $PROBLEM.
Note that general code warnings and PsN outputs appended are listed as problem 0.
# A tibble: 764 x 5
problem level subroutine code comment
* <int> <int> <chr> <chr> <chr>
@@ -180,8 +180,8 @@
Access the output data
The get_data() function can be used to access the imported table files. Tables can be accessed by table name or by .problem. In the latter a single dataset containing all aggregated tables is returned. If more than one table name or .problem number is provided a named list is returned.
Note when providing a table name it is not guaranteed that the table will be identical to its file (i.e. the order of the columns may have been changed and tables with FIRSTONLY will no longer be deduplicated).
# A tibble: 550 x 4
ID CLCR AGE WT
<fct> <dbl> <dbl> <dbl>
@@ -201,8 +201,8 @@
Access the run files
The get_file() function can be used to access the imported output files. Files can be accessed by file name, by .problem, .subprob and/or .method. If more than one file name, .problem, .subprob, or .method is provided a named list is returned.
The get_prm() function can be used to access the parameter estimates. To get a nice parameter table printed to the console use the function prm_table() instead. The arguments .problem, .subprob and .method can be used to select the parameter estimates to output.
-
# Raw output for editing
-prm <-get_prm(xpdb, digits =4)
-prm
+
# Raw output for editing
+prm<-get_prm(xpdb, digits=4)
+prm
# A tibble: 11 x 10
type name label value se rse fixed diagonal m n
* <chr> <chr> <chr> <dbl> <dbl> <dbl> <lgl> <lgl> <dbl> <dbl>
@@ -240,8 +240,8 @@
Reporting transformed parameters:
For the OMEGA and SIGMA matrices, values are reported as standard deviations for the diagonal elements and as correlations for the off-diagonal elements. The relative standard errors (RSE) for OMEGA and SIGMA are reported on the approximate standard deviation scale (SE/variance estimate)/2. Use `transform = FALSE` to report untransformed parameters.
@@ -265,13 +265,13 @@
Access the run summary
The get_summary() function can be used to access the generated run summary from which the template_titles. If the argument .problem is specified a subset of the summary can be returned based on $PROBLEM.
Note that general summary information are listed as problem 0.
# A tibble: 12 x 5
problem subprob descr label value
<dbl> <dbl> <chr> <chr> <chr>
1 0 0 Run description descr NONMEM PK example for xpose
- 2 0 0 Run directory dir analysis/models/pk/
+ 2 0 0 Run directory dir data
3 0 0 Run errors errors na
4 0 0 ESAMPLE seed number esampleseed na
5 0 0 Run file file run001.lst
@@ -285,7 +285,7 @@
All xpose plots have by default an informative title, subtitle and caption. For example all plots using individual model predictions (IPRED) will display the epsilons’ shrinkage. These titles can easily be edited as templates using @keywords which will be replaced by their actual value stored in the summary level of the xpdb object when rendering the plots. Keywords are defined by a word preceded by a @ e.g. '@ofv'. A list of all available keyword can be accessed via help('template_titles'). The title, subtitle or caption can be disabled by setting them to NULL. Suffix can be automatically added to title, subtitle and caption of all plots. The suffixes can be defined in the xp_theme.
+
All xpose plots have by default an informative title, subtitle and caption. For example all plots using individual model predictions (IPRED) will display the epsilons’ shrinkage. These titles can easily be edited as templates using @keywords which will be replaced by their actual value stored in the summary level of the xpdb object when rendering the plots. Keywords are defined by a word preceded by a @ e.g. '@ofv'. A list of all available keyword can be accessed via help('template_titles'). The title, subtitle or caption can be disabled by setting them to NULL. Suffix can be automatically added to title, subtitle and caption of all plots. The suffixes can be defined in the xp_theme.
From the plot functions
-
# Using template titles
-dv_vs_ipred(xpdb,
-title ='@y vs. @x (@run, obj: @ofv)',
-subtitle ='Based on: @nind subjects and @nobs records',
-caption ='Dir: @dir')
+
# Using template titles
+dv_vs_ipred(xpdb,
+ title='@y vs. @x (@run, obj: @ofv)',
+ subtitle='Based on: @nind subjects and @nobs records',
+ caption='Dir: @dir')
-
# Disabling all titles
-dv_vs_ipred(xpdb, title =NULL, subtitle =NULL, caption =NULL)
+
# Disabling all titles
+dv_vs_ipred(xpdb, title=NULL, subtitle=NULL, caption=NULL)
-
# Edit title suffix from the xp_theme for a specific plot
-dv_vs_ipred(xpdb, title ='A title', xp_theme =list(title_suffix =' | a suffix for @run'))
+
# Edit title suffix from the xp_theme for a specific plot
+dv_vs_ipred(xpdb, title='A title', xp_theme=list(title_suffix=' | a suffix for @run'))
Using the labs function
Labels can also modified later on by using the ggplot2::labs() function in combination with the ggplot2 + operator.
-
dv_vs_ipred(xpdb) +
-labs(title ='@descr',
-subtitle =NULL,
-caption ='Based on @nobs observations',
-x ='Individual model predictions (@x)',
-y ='Observations (@y) for @nind subjects')
+
dv_vs_ipred(xpdb) +
+ labs(title='@descr',
+ subtitle=NULL,
+ caption='Based on @nobs observations',
+ x='Individual model predictions (@x)',
+ y='Observations (@y) for @nind subjects')
@@ -202,18 +202,18 @@
Modify aesthetics
By default the aesthetics are read from the xp_theme level in the xpdb object but these can be modified in any plot function. xpose makes use of the ggplot2 functions mapping for any layer (e.g. points, lines, etc.) however to direct the mapping to a specific layer, a prefix appealing to the targeted layer should be used. The format is defined as layer_aesthetic = value. Hence to change the color of points in ggplot2 the argument color = 'green' could be used in geom_point(), while in xpose the same could be achieved with point_color = 'green'.
In basic goodness-of-fit plots, the layers have been named as: point_xxx, line_xxx, smooth_xxx, guide_xxx, xscale_xxx, yscale_xxx where xxx can be any option available in the ggplot2 layers: geom_point, geom_line, geom_smooth, geom_abline, scale_x_continuous, etc.
# Example with a string
-dv_vs_ipred(xpdb, facets =c('SEX', 'MED1'), ncol =2, nrow =1, page =1)
+
# Example with a string
+dv_vs_ipred(xpdb, facets=c('SEX', 'MED1'), ncol=2, nrow=1, page=1)
-
# Example with a formula
-dv_vs_ipred(xpdb, facets = SEX~MED1, margins =TRUE)
+
# Example with a formula
+dv_vs_ipred(xpdb, facets=SEX~MED1, margins=TRUE)
All xpose plot functions accept arguments for facet_wrap_pagninate and facet_grid_paginate (e.g. ncol = 2, labeller = 'label_both', etc.). With the default xpose theme scales are set to 'free' from one panel to another (scales = 'free'), this behavior can be changed with scales = 'fixed', 'free_y' or 'free_x'.
xpose offers the opportunity to add any additional layers from ggplot2. Hence, a ggplot2::geom_rug() layer could be added to the dv_vs_ipred() plot along with some annotations (ggplot2::annotate()). Note: the additional layers do not inherit from the xpose aesthetic mapping (i.e. colors or other options need to be defined in each layer as shown below).
The argument log allows to log-transform the axes. Accepted values are x, y or xy.
-
dv_vs_ipred(xpdb, log ='xy', subtitle ='Plot on log scale')
+
dv_vs_ipred(xpdb, log='xy', subtitle='Plot on log scale')
Additional arguments can be provided to the scales via the mapping by using the naming convention xscale_xxx or yscale_xxx where xxx is the name of a ggplot2 scale argument such as name, breaks, labels, expand.
The ggplot2 object is now automatically converted to a plotly graph. The scales can now be changed interactively, groups can be hidden by clicking on the legend
The function xpose_data() collects all model output files and table and organizes them into an R object commonly called xpdb which stands for “xpose database”.
-
xpdb <-xpose_data(runno ='001', dir ='analysis/model/pk/')
Reporting transformed parameters:
For the OMEGA and SIGMA matrices, values are reported as standard deviations for the diagonal elements and as correlations for the off-diagonal elements. The relative standard errors (RSE) for OMEGA and SIGMA are reported on the approximate standard deviation scale (SE/variance estimate)/2. Use `transform = FALSE` to report untransformed parameters.
@@ -234,7 +234,7 @@
Listing variables
A list of available variables for plotting can be displayed to the console by using the list_vars() function on an xpdb object.
Multiples edits can be made to the xpdb object. For instance the type (visible using the list_vars() function described above) of a variable can be changed. Hence the independent variable (idv) could be changed from TIME (default in NONMEM) to TAD. All plots using idv will then automatically use TAD.
# CWRES vs. PRED plot
-res_vs_pred(xpdb, res ='CWRES')
+
# CWRES vs. PRED plot
+res_vs_pred(xpdb, res='CWRES')
Saving plots
The xpose_save function was designed to facilitate the export of xpose plots. The file extension is guessed from the file name and must match one of .pdf (default), .jpeg, .png, .bmp or .tiff. If no extension is provided as part of the file name a .pdf will be generated. Finally, if the plot argument is left empty xpose_save will automatically save the last plot that was created or modified.
-
The xpose_save() function is compatible with templates titles and keywords such as @run for the run number and @plotfun for the name of the plotting function can be used to automatically name files. Learn more about the template titles keywords using help('template_titles').
-
# Save the last generated plot
-dv_vs_ipred(xpdb)
-xpose_save(file ='run001_dv_vs_ipred.pdf')
-
-# Template titles can also be used in filename and the directory
-xpdb %>%
-dv_vs_ipred() %>%
-xpose_save(file ='@run_@plotfun_[@ofv].jpeg', dir ='@dir')
+
The xpose_save() function is compatible with templates titles and keywords such as @run for the run number and @plotfun for the name of the plotting function can be used to automatically name files. Learn more about the template titles keywords using help('template_titles').
+
# Save the last generated plot
+dv_vs_ipred(xpdb)
+xpose_save(file='run001_dv_vs_ipred.pdf')
+
+# Template titles can also be used in filename and the directory
+xpdb%>%
+ dv_vs_ipred() %>%
+ xpose_save(file='@run_@plotfun_[@ofv].jpeg', dir='@dir')
If facets is a formula e.g facets = SEX~MED1, facets will be created using ggforce::facet_grid_paginate
-
# Example with a string
-dv_vs_ipred(xpdb, facets =c('SEX', 'MED1'))
+
# Example with a string
+dv_vs_ipred(xpdb, facets=c('SEX', 'MED1'))
-
# Example with a formula
-dv_vs_ipred(xpdb, facets = SEX~MED1, margins =TRUE)
+
# Example with a formula
+dv_vs_ipred(xpdb, facets=SEX~MED1, margins=TRUE)
All xpose plot functions accept arguments for facet_wrap_pagninate and facet_grid_paginate (e.g. ncol = 2, labeller = 'label_both', etc.). With the default xpose theme scales are set to 'free' from one panel to another (scales = 'free'), this behavior can be changed with scales = 'fixed', 'free_y' or 'free_x'.
@@ -161,32 +161,32 @@
Setting the layout
When the arguments ncol and nrow are set and under the condition that they are more panels to be drawn that can fit on a single page given the selected layout, the multiple page functionality will automatically be enabled.
It is also possible to change the page(s) to be drawn from an already existing xpose_plot object via the print() function.
-
# Create an xpose_plot, by default page = 1
-p1 <-dv_vs_ipred(xpdb, facets =c('SEX', 'MED1'), ncol =2, nrow =1)
-
-# Change the page to be drawn
-print(p1, page =2)
+
# Create an xpose_plot, by default page = 1
+p1<-dv_vs_ipred(xpdb, facets=c('SEX', 'MED1'), ncol=2, nrow=1)
+
+# Change the page to be drawn
+print(p1, page=2)
Numbering pages
To number pages the keywords @page and @lastpage can be used to respectively indicate the current page and the total number of pages.
The pdf format can conveniently store multiple pages within a single document. However other graphical devices (e.g. 'png', 'jpg') can also be used, simply ensure to have a page counter (i.e. '%03d') added the file name.
The stratify options defines up to two stratifying variable to be used when computing the VPC data. The stratify variables can either be provided as a character vector (stratify = c('SEX', 'MED1')) or a formula (stratify = SEX~MED1) . The former will result in the use of ggforce::facet_wrap_paginate() and the latter of ggforce::facet_grid_paginate() when creating the plot. With “categorical” VPC the “group” variable will also be added by default.
More advanced options (i.e. binning, pi, ci, predcorr, lloq, etc.) are accessible via the opt argument. The opt argument expects the output from the vpc_opt() functions argument.
To create VPC using the xpdb data, at least one simulation and one estimation problem need to present. Hence in the case of NONMEM the run used to generate the xpdb should contain several$PROBLEM. In vpc_data() the problem number can be specified for the observation (obs_problem) and the simulation (sim_problem). By default xpose picks the last one of each to generate the VPC.
-
# View the xpdb content and data problems
-xpdb_ex_pk
+
# View the xpdb content and data problems
+xpdb_ex_pk
The vpc_data() contains an argument psn_foler which can be used to point to a PsN generated VPC folder. As in most xpose function template_titles keywords can be used to automatize the process e.g. psn_folder = '@dir/@run_vpc' where @dir and @run will be automatically translated to initial (i.e. when the xpdb was generated) run directory and run number 'analysis/models/pk/run001_vpc'.
+
The vpc_data() contains an argument psn_folder which can be used to point to a PsN generated VPC folder. As in most xpose function template_titles keywords can be used to automatize the process e.g. psn_folder = '@dir/@run_vpc' where @dir and @run will be automatically translated to initial (i.e. when the xpdb was generated) run directory and run number 'analysis/models/pk/run001_vpc'.
In this case, the data will be read from the /m1 sub-folder (or m1.zip if compressed). Note that PsN drops unused columns to reduce the simtab file size. Thus, in order to allow for more flexibility in R, it is recommended to use multiple stratifying variables (-stratify_on=VAR1,VAR2) and the prediction corrected (-predcorr adds the PRED column to the output) options in PsN to avoid having to rerun PsN to add these variables later on. In addition, -dv, -idv, -lloq, -uloq, -predcorr and -stratify_onPsN options are automatically applied to xpose VPC.
The PsN generated binning can also applied to xpose VPC with the vpc_data() option psn_bins = TRUE (disabled by default). However PsN and the vpc package work slightly differently so the results may not be optimal and the output should be evaluated carefully.
# 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')
+
# 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')
#> # A tibble: 48 x 5
#> problem subprob descr label value
-#> <dbl><dbl><chr><chr><chr>
-#> 1 0 0 Run description descr NONMEM PK example for xpose
-#> 2 0 0 Run directory dir analysis/models/pk/
-#> 3 0 0 Run errors errors na
-#> 4 0 0 ESAMPLE seed number esampleseed na
-#> 5 0 0 Run file file run001.lst
-#> 6 0 0 Number of ESAMPLE nesample na
-#> 7 0 0 Reference model ref 000
-#> 8 0 0 Run number run run001
-#> 9 0 0 Software software nonmem
-#> 10 0 0 Run start time timestart Mon Oct 16 13:34:28 CEST 2017
-#> # … with 38 more rows
+#> <dbl><dbl><chr><chr><chr>
+#> 1 0 0 Run description descr NONMEM PK example for xpose
+#> 2 0 0 Run directory dir data
+#> 3 0 0 Run errors errors na
+#> 4 0 0 ESAMPLE seed number esampleseed na
+#> 5 0 0 Run file file run001.lst
+#> 6 0 0 Number of ESAMPLE nesample na
+#> 7 0 0 Reference model ref 000
+#> 8 0 0 Run number run run001
+#> 9 0 0 Software software nonmem
+#> 10 0 0 Run start time timestart Mon Oct 16 13:34:28 CEST 2017
+#> # … with 38 more rows
#> # A tibble: 48 x 5
#> problem subprob descr label value
-#> <dbl><dbl><chr><chr><chr>
-#> 1 0 0 Run description descr NONMEM PK example for xpose
-#> 2 0 0 Run directory dir analysis/models/pk/
-#> 3 0 0 Run errors errors na
-#> 4 0 0 ESAMPLE seed number esampleseed na
-#> 5 0 0 Run file file run001.lst
-#> 6 0 0 Number of ESAMPLE nesample na
-#> 7 0 0 Reference model ref 000
-#> 8 0 0 Run number run run001
-#> 9 0 0 Software software nonmem
-#> 10 0 0 Run start time timestart Mon Oct 16 13:34:28 CEST 2017
-#> # … with 38 more rows
+#> <dbl><dbl><chr><chr><chr>
+#> 1 0 0 Run description descr NONMEM PK example for xpose
+#> 2 0 0 Run directory dir data
+#> 3 0 0 Run errors errors na
+#> 4 0 0 ESAMPLE seed number esampleseed na
+#> 5 0 0 Run file file run001.lst
+#> 6 0 0 Number of ESAMPLE nesample na
+#> 7 0 0 Reference model ref 000
+#> 8 0 0 Run number run run001
+#> 9 0 0 Software software nonmem
+#> 10 0 0 Run start time timestart Mon Oct 16 13:34:28 CEST 2017
+#> # … with 38 more rows
with a @ (e.g. @ofv) which will be replaced by their actual value when rendering the plot.
For example '@run, @nobs observations in @nind subjects' would become 'run001,
1022 observations in 74 subjects'
-