Package 'xpose'

Description

Plot of the change in compartment amounts over the independent variable

Usage

amt_vs_idv(
  xpdb,
  mapping = NULL,
  group = "ID",
  drop_fixed = TRUE,
  type = "l",
  title = "Compartments amount vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

amt_vs_idv(xpdb_ex_pk, nrow = 2, ncol = 1)

Description

Provide a list of options to the general plotting functions such as xplot_scatter in order to create appropriate data input for ggplot2.

Usage

data_opt(
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  .source = "data",
  simtab = FALSE,
  filter = NULL,
  tidy = FALSE,
  index_col = NULL,
  value_col = NULL,
  post_processing = NULL
)

Arguments

See Also

xplot_distrib xplot_qq xplot_scatter

Examples

data_opt(.problem = 1, .source = 'data', simtab = TRUE)

Description

Histograms and density plots of the ETA and parameter values.

Usage

prm_distrib(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "hr",
  title = "Parameter distribution | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

eta_distrib(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "hr",
  title = "Eta distribution | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

res_distrib(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  type = "hr",
  title = "@x distribution | @run",
  subtitle = "Based on @nobs observations",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

cov_distrib(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "hr",
  title = "Continuous covariates distribution | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. histogram_fill = 'blue', rug_sides = 'b', etc.

• histogram: options to geom_histogram

• density: options to geom_density

• rug: options to geom_rug

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_distrib

Examples

# Histogram of parameters
prm_distrib(xpdb_ex_pk, type = 'h')

# Density plot of etas with a rug
eta_distrib(xpdb_ex_pk, type = 'dr')

# Histogram of different residuals
res_distrib(xpdb_ex_pk, type = 'hr', res = c('IWRES', 'CWRES'))

# Density plot of continuous covariates
cov_distrib(xpdb_ex_pk, type = 'd')

Description

Plot of observations (DV) vs population predictions (PRED), individual predictions (IPRED) or conditional population predictions (CPRED).

Usage

dv_vs_ipred(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

dv_vs_pred(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

dv_vs_pred(xpdb_ex_pk)

dv_vs_ipred(xpdb_ex_pk)

Description

Access model code from an xpdb object.

Usage

get_code(xpdb, .problem = NULL)

Arguments

Value

A tibble of the parsed model.

See Also

xpose_data, read_nm_model

Examples

parsed_model <- get_code(xpdb_ex_pk)
parsed_model

Description

Access model output table data from an xpdb object.

Usage

get_data(xpdb, table = NULL, .problem = NULL, quiet)

Arguments

Value

By default returns data from the last estimation problem. If only simulation problems are present then the data from last simulation will be returned instead. Object returned as tibble for single tables/problems or a named list for multiple tables/problems.

See Also

list_data, xpose_data, read_nm_tables

Examples

# By table name
sdtab <- get_data(xpdb_ex_pk, 'sdtab001')
sdtab

# By problem
tables <- get_data(xpdb_ex_pk, .problem = 1)
tables

# Tip to list available tables in the xpdb
print(xpdb_ex_pk)

Description

Access model output file data from an xpdb object.

Usage

get_file(
  xpdb,
  file = NULL,
  ext = NULL,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  quiet
)

Arguments

Value

A tibble for single file or a named list for multiple files.

See Also

list_files, xpose_data, read_nm_files

Examples

# Single file (returns a tibble)
ext_file <- get_file(xpdb_ex_pk, file = 'run001.ext')
ext_file

# Multiple files (returns a list)
files <- get_file(xpdb_ex_pk, file = c('run001.ext', 'run001.phi'))
files

# Tip to list available files in the xpdb
print(xpdb_ex_pk)

Description

Access model parameter estimates from an xpdb object.

Usage

get_prm(
  xpdb,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  digits = 4,
  transform = TRUE,
  show_all = FALSE,
  quiet
)

Arguments

Value

A tibble for single problem/subprob or a named list for multiple problem|subprob.

See Also

prm_table

Examples

# Store the parameter table
prm <- get_prm(xpdb_ex_pk, .problem = 1)

# Display parameters to the console
prm_table(xpdb_ex_pk, .problem = 1)

Description

Access special model data from an xpdb object.

Usage

get_special(xpdb, .problem = NULL, quiet)

Arguments

Value

A list.

See Also

list_special, xpose_data

Examples

special <- get_summary(xpdb_ex_pk)
special

Description

Access model summary data from an xpdb object.

Usage

get_summary(xpdb, .problem = NULL, .subprob = NULL, only_last = FALSE)

Arguments

Value

A tibble of model summary.

See Also

xpose_data, template_titles, summary.xpose_data

Examples

run_summary <- get_summary(xpdb_ex_pk)
run_summary

Description

An additional set of complete ggplot2 themes intended to make ggplot2 more readable when used in presentation or publications. These themes also bring the legend_position option without having to call the ggplot2 theme() function to modify a complete theme.

• theme_bw2: Black and white theme inspired by a theme from Gunnar Yngman.

• theme_readable: Light grey theme, with dimmed background and grid lines intended to bring the focus on the data.

Usage

theme_bw2(base_size = 11, base_family = "", legend_position = "right")

theme_readable(base_size = 11, base_family = "", legend_position = "right")

Arguments

Examples

# With the gg_theme theme_readable() (default)
dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')

# With the gg_theme theme_bw2()
xpdb_ex_pk %>% 
 update_themes(gg_theme = theme_bw2()) %>% 
 dv_vs_ipred(facets = 'SEX')

Description

Observations (DV), individual predictions (IPRED) and population predictions (PRED) plotted against the independent variable for every individual

Usage

ind_plots(
  xpdb,
  mapping = NULL,
  group = "variable",
  type = "lp",
  title = "Individual plots | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir | Page @page of @lastpage",
  tag = NULL,
  log = NULL,
  facets,
  .problem,
  quiet,
  color = c("grey60", "deepskyblue4", "deepskyblue3"),
  point_alpha = c(0.8, 0, 0),
  line_linetype = c("blank", "solid", "55"),
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

## Not run: 
# Basic example
ind_plots(xpdb_ex_pk, page = 1,
          ncol = 2, nrow = 2)

## End(Not run)

Description

Add a column containing a simulation counter (irep). A new simulation is counted everytime a value in x is lower than its previous value.

Usage

irep(x, quiet = FALSE)

Arguments

Examples

xpdb_ex_pk_2 <- xpdb_ex_pk %>% 
 mutate(sim_id = irep(ID), .problem = 2)

Description

List NONMEM output tables file names from a nm_model object.

Usage

list_nm_tables(nm_model = NULL)

Arguments

See Also

read_nm_model, read_nm_tables

Examples

## Not run: 
read_nm_model(file = 'run001.lst') %>% 
  list_nm_tables()

## End(Not run)

Description

Function listing all available variables in an xpdb object.

Usage

list_vars(xpdb, .problem = NULL)

Arguments

See Also

set_var_types

Examples

list_vars(xpdb_ex_pk)

Description

Function providing a detailed listing of all available datasets in an xpdb object.

Usage

list_data(xpdb)

list_files(xpdb)

list_special(xpdb)

Arguments

See Also

get_data, get_file, get_special

Examples

# List output tables data
list_data(xpdb_ex_pk)

# List output files data
list_files(xpdb_ex_pk)

# List special data
xpdb_ex_pk %>% 
vpc_data(quiet = TRUE) %>% 
list_special()

Description

Manually provide names of the table files to be imported by xpose_data.

Usage

manual_nm_import(
  tab_names = c("sdtab", "mutab", "patab", "catab", "cotab", "mytab", "extra", "xptab",
    "cwtab"),
  tab_suffix = "",
  sim_suffix = "sim"
)

Arguments

Details

In order to be imported manually, table names must follow the following convention: <tab_names><runno><tab/sim_suffix> e.g. sdtab001sim. When the argument 'file' is used in xpose_data, the <runno> part is guessed by taking the portion of the string starting by any digit and ending at the file extension e.g. file = run001a.mod will guess <runno> as '001a'. If no valid <runno> can be guessed, xpose will return an error. In this case it is advised to use the xpose_data argument 'runno' directly rather than 'file' hence preventing xpose from having to guess <runno>.

Note that with manual table import xpose still reads in the NONMEM model file in order to generate the run summary.

See Also

xpose_data

Examples

## Not run: 
# Import all names specified by default as in xpose4
xpose_data(runno = '001', manual_import = manual_nm_import())

# Import a specific table name
xpose_data(runno = '001', manual_import = manual_nm_import(tab_names = 'mytab'))

## End(Not run)

Description

Change of parameter value or gradient vs. iterations.

Usage

prm_vs_iteration(
  xpdb,
  mapping = NULL,
  group = "variable",
  type = "l",
  title = "Parameter @y vs. @x | @run",
  subtitle = "Method: @method, minimization time: @runtime\nTermination message: @term",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  .subprob,
  .method,
  quiet,
  ...
)

grd_vs_iteration(
  xpdb,
  mapping = NULL,
  group = "variable",
  type = "l",
  title = "Gradient @y vs. @x | @run",
  subtitle = "Method: @method, minimization time: @runtime\nTermination message: @term",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  .subprob,
  .method,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

prm_vs_iteration(xpdb_ex_pk)

grd_vs_iteration(xpdb_ex_pk)

Description

mutate() adds new variables and preserves existing ones. select() keeps only the listed variables; rename() keeps all variables.

Usage

## S3 method for class 'xpose_data'
mutate(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
select(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
rename(.data, ..., .problem, .source, .where)

Arguments

Examples

# Mutate columns
xpdb_ex_pk %>% 
 mutate(lnDV = log(DV), 
        sim_count = irep(ID), 
        .problem = 1) %>% 
 dv_vs_idv(aes(y = lnDV))
 
# Rename/select columns
xpdb_ex_pk %>% 
 select(ID:TAD, DV, EVID) %>% 
 rename(TSLD = TAD) %>% 
 dv_vs_idv(aes(x = TSLD))

Description

Plot of observations (DV), individual model predictions (IPRED) and/or population predictions (PRED) plotted against the independent variable (IDV).

Usage

dv_vs_idv(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  facets,
  .problem,
  quiet,
  ...
)

ipred_vs_idv(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  facets,
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  .problem,
  quiet,
  ...
)

pred_vs_idv(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  facets,
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  .problem,
  quiet,
  ...
)

dv_preds_vs_idv(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  facets,
  title = "Observations, Individual and Population Predictions vs. @x | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

dv_vs_idv(xpdb_ex_pk)

ipred_vs_idv(xpdb_ex_pk)

pred_vs_idv(xpdb_ex_pk)

dv_preds_vs_idv(xpdb_ex_pk)

Description

This function returns to the console a list of the files and options attached to an xpose_data object.

Usage

## S3 method for class 'xpose_data'
print(x, ...)

Arguments

Examples

# Using the print function
print(xpdb_ex_pk)

# Or simply by writing the xpdb name
xpdb_ex_pk

Description

This function explicitly draw an xpose_plot and interprets keywords contained in labels.

Usage

## S3 method for class 'xpose_plot'
print(x, page, ...)

Arguments

Examples

my_plot <- dv_vs_ipred(xpdb_ex_pk) +
            labs(title = 'A label with keywords: @nind individuals & @nobs observations')
# Using the print function
print(my_plot)

# Or simply by writting the plot object name
my_plot

Description

Display parameter estimates from an xpdb object to the console.

Usage

prm_table(
  xpdb,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  digits = 4,
  transform = TRUE,
  show_all = FALSE
)

Arguments

See Also

get_prm,

Examples

## Not run: 
# Store the parameter table
prm <- get_prm(xpdb_ex_pk, .problem = 1)

# Display parameters to the console
prm_table(xpdb_ex_pk, .problem = 1)

## End(Not run)

Description

QQ plots of the ETA and model residuals.

Usage

prm_qq(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "p",
  title = "QQ plot of parameters | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

eta_qq(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "p",
  title = "QQ plot of etas | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

res_qq(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  type = "p",
  title = "QQ plot of @sample | @run",
  subtitle = "Based on @nobs observations",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

cov_qq(
  xpdb,
  mapping = NULL,
  drop_fixed = TRUE,
  type = "p",
  title = "QQ plot of continuous covariates | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', etc.

• point: options to geom_point

• guide: options to geom_abline

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_distrib

Examples

# QQ plot of parameters
prm_qq(xpdb_ex_pk)

# QQ plot of eta
eta_qq(xpdb_ex_pk)

# QQ plot of residuals
res_qq(xpdb_ex_pk, res = c('IWRES', 'CWRES'))

# QQ plot of continuous covariates
cov_qq(xpdb_ex_pk)

Description

Quickly import NONMEM output files into R.

Usage

read_nm_files(
  runno = NULL,
  prefix = "run",
  ext = c(".ext", ".cor", ".cov", ".phi", ".grd", ".shk"),
  file = NULL,
  dir = NULL,
  quiet = FALSE
)

Arguments

File path generation

The rules for model file names generation are as follow:

• with runno: the full path is generated as <dir>/<prefix><runno>.<ext> e.g. with dir = 'model/pk', prefix = 'run', runno = '001', ext = '.lst' the resulting path would be model/pk/run001.lst

• with file: the full path is generated as <dir>/<file> e.g. with dir = 'model/pk', file = 'run001.lst' the resulting path would also be model/pk/run001.lst. Note: in this case the file extension should be provided as part of the 'file' argument.

See Also

xpose_data, read_nm_tables

Examples

## Not run: 
# Using the `file` argument to import a model file:
ext_file <- read_nm_files(file = 'run001.ext', dir = 'models')

# Using the `runno` argument to import a model file:
ext_file <- read_nm_files(runno = '001', ext = '.ext', dir = 'models')

## End(Not run)

Description

Parse NONMEM model files in R format

Usage

read_nm_model(
  runno = NULL,
  prefix = "run",
  ext = ".lst",
  file = NULL,
  dir = NULL,
  check_ext = TRUE
)

Arguments

Details

A NONMEM model output file (i.e. .lst, .out or .res) should preferably be provided to read_nm_model to allow for a more extensive xpose summary. However in some cases these output files may not contain the model code, thus preventing xpose from identifying the associated output tables names. In such cases xpose will attempt to read the associated model file (i.e. .mod or .ctl) instead to find the model code. Note: it is important that between the naming convention between the NONMEM output and the model file remains consistent e.g. run001.lst should be associated with run001.mod.

Value

A tibble of class model containing the following columns:

• problem: a numeric identifier for the $PROBLEM associated with the code.

• level: a unique numeric identifier to each subroutine block associated with the code.

• subroutine: a character identifier named after the 3 first letters of the subroutine name e.g. '$THETA' and '$TABLE' will become 'the' and 'tab' respectively. In addition all output from the .lst is labeled 'lst', the general nonmem output e.g. NM-TRAN messages are labelled 'oth'. With priors thp, tpv, omp, opd, sip, spd abbreviations are given to the THETAP, THETAPV, OMEGAP, etc.

• code: the code without comments or subroutine names e.g. '$THETA 0.5 ; TVCL' will return '0.5'.

• comment: the last comment of a record e.g. '0.5 ; Clearance (L/h) ; TVCL' will return 'TVCL'.

File path generation

The rules for model file names generation are as follow:

• with runno: the full path is generated as <dir>/<prefix><runno>.<ext> e.g. with dir = 'model/pk', prefix = 'run', runno = '001', ext = '.lst' the resulting path would be model/pk/run001.lst

• with file: the full path is generated as <dir>/<file> e.g. with dir = 'model/pk', file = 'run001.lst' the resulting path would also be model/pk/run001.lst. Note: in this case the file extension should be provided as part of the 'file' argument.

See Also

xpose_data, read_nm_tables

Examples

## Not run: 
# Using the `file` argument to import a model file:
nm_model <- read_nm_model(file = 'run001.lst', dir = 'models')

# Using the `runno` argument to import a model file:
nm_model <- read_nm_model(runno = '001', ext = '.lst', dir = 'models')

## End(Not run)

Description

Quickly import NONMEM output tables into R. This function automatically detects the optimal settings to import the tables from nonmem.

Usage

read_nm_tables(
  file = NULL,
  dir = NULL,
  combined = TRUE,
  rm_duplicates = TRUE,
  quiet = FALSE,
  simtab = NULL,
  ziptab = TRUE,
  ...
)

Arguments

Table format requirement

When using read_nm_tables with the combined argument set to FALSE an ID column must be present in all data tables. When combined is set to TRUE instead an ID column must be present in at least one table for each problem and for each 'firstonly' category. ID columns are required to properly combine/merge tables and removing NA records. If the ID column is missing from a table and combined = FALSE read_nm_tables will return the following warning: Unknown variables: `ID`. While the data is returned beware that NA records might be left in the data and the output should be checked carefully. If combined = TRUE read_nm_tables xpose is more strict and will return the following warning instead: Dropped `<tablenames>` due to missing required `ID` column..

Examples

## Not run: 
# Import tables manually and return them as a list of individual tables
nm_tables <- read_nm_tables(file = c('sdtab001', 'patab001'), 
                            dir = 'models', combined = FALSE)

# Import tables manually and return them as a single merged table
nm_tables <- read_nm_tables(file = c('sdtab001', 'patab001'), 
                            dir = 'models', combined = TRUE)

# Import tables automatically (used internally by xpose_data())
nm_tables <- read_nm_model(file = 'run001.lst', dir = 'models') %>% 
              list_nm_tables() %>% 
              read_nm_tables()

# Passing arguments to readr via `...` 
# (e.g. import columns as character and only first 10 rows)
nm_tables <- read_nm_tables(file = 'sdtab001', dir = 'models', 
                            col_type = readr::cols(.default = 'c'), 
                            n_max = 10)


## End(Not run)

Description

Model residuals plotted against the independent variable (IDV).

The residuals can be one of:

• RES: model residuals

• WRES: weighted model residuals

• CWRES: conditional weighted model residuals

• EWRES/ECWRES: Monte Carlo based model residuals

• NPDE: Normalized prediction distribution error

Usage

res_vs_idv(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

absval_res_vs_idv(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  group = "ID",
  type = "pls",
  title = "@y vs. @x  | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

# Standard residual
res_vs_idv(xpdb_ex_pk, res = c('IWRES', 'CWRES'))

# Absolute value of the residuals
absval_res_vs_idv(xpdb_ex_pk, res = 'CWRES')

Description

Model residuals plotted against population predictions (PRED).

The residuals can be one of:

• RES: model residuals

• WRES: weighted model residuals

• CWRES: conditional weighted model residuals

• EWRES/ECWRES: Monte Carlo based model residuals

• NPDE: Normalized prediction distribution error

Usage

res_vs_pred(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

absval_res_vs_pred(
  xpdb,
  mapping = NULL,
  res = "CWRES",
  group = "ID",
  type = "pls",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter

Examples

# Standard residual
res_vs_pred(xpdb_ex_pk, res = c('IWRES', 'CWRES'))

# Absolute value of the residuals
absval_res_vs_pred(xpdb_ex_pk, res = 'CWRES')

Description

Function designed to change the type, label or unit associated with variables.

Usage

set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)

set_var_labels(xpdb, .problem = NULL, ..., quiet)

set_var_units(xpdb, .problem = NULL, ..., quiet)

Arguments

Value

An xpose_data object

Recognized variable types

• a: Compartments' amount

• amt: Dose amount

• catcov: Categorical covariate

• contcov: Continuous covariate

• dv: Dependent variable

• dvid: DV identifier

• eta: Eta

• evid: Event identifier

• id: Subject identifier

• idv: Independent variable

• ipred: Individual model predictions

• mdv: Missing dependent variable

• na: Not attributed

• occ: Occasion flag

• param: Model parameter

• pred: Typical model predictions

• res: Residuals

See Also

list_vars

Examples

# Change variable type
xpdb_2 <- set_var_types(xpdb_ex_pk, .problem = 1, idv = 'TAD')

# Change labels
xpdb_2 <- set_var_labels(xpdb_2, .problem = 1, ALAG1 = 'Lag time', CL = 'Clearance', V = 'Volume')

# Change units
xpdb_2 <- set_var_units(xpdb_2, .problem = 1, ALAG1 = 'h', CL = 'L/h', V = 'L')

Description

Use filter() to select rows/cases where conditions are true. Unlike base subsetting, rows where the condition evaluates to NA are dropped. Use slice() to select row/cases by their position

Usage

## S3 method for class 'xpose_data'
filter(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
slice(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
distinct(.data, ..., .problem, .source, .where)

Arguments

Examples

# Subset by condition
xpdb_ex_pk %>% 
 filter(DV < 1, .problem = 1) %>% 
 dv_vs_ipred()
  
# Subset by positions
xpdb_ex_pk %>% 
 slice(1:100, .problem = 1) %>% 
 dv_vs_ipred()
 
# Deduplicate rows
xpdb_ex_pk %>% 
 distinct(TIME, .problem = 1) %>% 
 dv_vs_ipred()

Description

group_by() takes an existing table and converts it into a grouped table where operations are performed "by group". ungroup() removes grouping. summarize() reduces multiple values down to a single value.

Usage

## S3 method for class 'xpose_data'
group_by(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
ungroup(x, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
summarise(.data, ..., .problem, .source, .where)

## S3 method for class 'xpose_data'
summarize(.data, ..., .problem, .source, .where)

Arguments

Examples

# Create a distribution plot of Cmax
xpdb_ex_pk %>% 
 group_by(ID, SEX, .problem = 1) %>% 
 summarize(CMAX = max(DV), .problem = 1) %>% 
 ungroup(.problem = 1) %>% 
 xplot_distrib(aes(x = CMAX, density_fill = SEX), type = 'dr')

Description

This function returns a summary of an xpose_data to the console.

Usage

## S3 method for class 'xpose_data'
summary(object, .problem = NULL, ...)

Arguments

Examples

summary(xpdb_ex_pk)

Description

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and the filename when saving with the xpose_save function.

Template titles are defined via a single string containing key variables staring 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'

Many key variables are available:

@condn

Condition number

@covtime

Covariance matrix runtime

@data

Model input data used

@descr

Model description

@dir

Model directory

@epsshk

Epsilon shrinkage

@errors

Run errors (e.g termination error)

@esampleseed

ESAMPLE seed number (used in NPDE)

@etashk

Eta shrinkage

@file

Model file name

@label

Model label

@method

Estimation method or sim

@nesample

Number of ESAMPLE (used in NPDE)

@nind

Number of individuals

@nobs

Number of observations

@nsig

Number of significant digits

@nsim

Number of simulations

@ofv

Objective function value

@page and @lastpage

Are respectively the page number and the number of the last page when faceting on multiple pages

@probn

Problem number

@plotfun

Name of the plot function

@ref

Reference model

@run

Model run name

@runtime

Estimation/Sim runtime

@software

Software used (e.g. NONMEM)

@simseed

Simulation seed

@subroutine

Differential equation solver

@timestart

Run start time

@timestop

Run stop time

@timeplot

Time of the plot rendering

@term

Termination message

@version

Software version (e.g. 7.3)

@vpcci

VPC confidence interval

@vpcdir

VPC data directory

@vpclloq

VPC lower limit of quantification

@vpcnsim

Number of simulations for VPC

@vpcpi

VPC prediction interval

@vpculoq

VPC upper limit of quantification

@warnings

Run warnings (e.g. boundary)

@x @y etc.

Name of any ggplot2 variable used for mapping in an aes() type function

See Also

xpose_save

Examples

# Defined when creating a plot
dv_vs_ipred(xpdb_ex_pk, 
            title = '@x vs. @y',
            subtitle = '@ofv, @nind subjects, @nobs obs.',
            caption = '@run, @descr')
            
# Any label can be modified later on
dv_vs_ipred(xpdb_ex_pk, aes(point_color = SEX, 
                            line_color = SEX)) + 
 labs(title = 'This runs is: @descr', 
      color = 'Color scale for @run',
      x     = 'IPRED for @nind subjects',
      subtitle = NULL)

Description

Create an xpose theme. This function will update the theme of an xpdb object. All plots generated with this xpdb will automatically use the defined xpose (xp_theme) and ggplot2 (gg_theme) themes.

Usage

update_themes(xpdb = NULL, gg_theme = NULL, xp_theme = NULL, quiet)

Arguments

Examples

# Before default theme
dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')

# Updating the gg_theme and xp_theme
xpdb_ex_pk %>%
  update_themes(gg_theme = theme(legend.position = 'top'),
                xp_theme = list(point_color = 'blue',
                                line_color  = 'blue')) %>%
  dv_vs_ipred(facets = 'SEX')

Description

Generate visual predictive checks (VPC)

Usage

vpc(
  xpdb,
  vpc_type = NULL,
  mapping = NULL,
  smooth = TRUE,
  type = "alpr",
  title = "Visual predictive checks | @run",
  subtitle = "Number of simulations: @vpcnsim, confidence interval: @vpcci%",
  caption = "@vpcdir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  gg_theme,
  xp_theme,
  facets,
  quiet,
  area_fill = c("steelblue3", "grey60", "steelblue3"),
  line_linetype = c("93", "solid", "93"),
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', area_fill = 'green', etc.

• point: options to geom_point

• line: options to geom_line

• area: options to geom_ribbon (smooth = TRUE) or geom_rect (smooth = FALSE)

• rug: options to geom_rug

• text: options to geom_text

• guide: options to geom_hline

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

vpc_data

Examples

xpdb_ex_pk %>% 
 vpc_data(opt = vpc_opt(n_bins = 7)) %>% 
 vpc()

Description

Generate visual predictive checks (VPC) data

Usage

vpc_data(
  xpdb,
  opt,
  stratify,
  vpc_type = c("continuous", "categorical", "censored", "time-to-event"),
  psn_folder = NULL,
  psn_bins = FALSE,
  obs_problem = NULL,
  sim_problem = NULL,
  quiet
)

Arguments

See Also

vpc vpc_opt

Examples

## Not run: 
xpdb_ex_pk %>% 
 vpc_data() %>% 
 vpc()

## End(Not run)

Description

Provide a list of options to vpc_data function.

Usage

vpc_opt(
  bins = "jenks",
  n_bins = "auto",
  bin_mid = "mean",
  pred_corr = FALSE,
  pred_corr_lower_bnd = 0,
  pi = c(0.025, 0.975),
  ci = c(0.025, 0.975),
  lloq = NULL,
  uloq = NULL,
  rtte = FALSE,
  rtte_calc_diff = TRUE,
  events = NULL,
  kmmc = NULL,
  reverse_prob = FALSE,
  as_percentage = TRUE
)

Arguments

See Also

vpc vpc_data

Examples

vpc_opt()

Description

xpose themes are used to consistently apply a set of preference for the plot geoms (e.g. color scales, point size, etc.) whereas ggplot2 theme focus on the plot background, axes, titles etc.

• theme_xp_default: The default xp_theme in xpose

• theme_xp_xpose4: An xp_theme that makes xpose look like xpose4.

Usage

theme_xp_default()

theme_xp_xpose4()

Examples

# With the xp_theme theme_xp_default() (default)
dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')

# With the xp_theme theme_xp_xpose4()
xpdb_ex_pk %>%
  update_themes(xp_theme = theme_xp_xpose4()) %>%
  dv_vs_ipred(facets = 'SEX')

Description

Moxonidine xpose_data example.

Format

An xpose_data object

Source

Moxonidine model: Assumption Testing in Population Pharmacokinetic Models: Illustrated with an Analysis of Moxonidine Data from Congestive Heart Failure Patients. Journal of Pharmacokinetics and Biopharmaceutics. 26(2):207–246 (1998).

Examples

print(xpdb_ex_pk)

Description

Manually generate distribution plots from an xpdb object.

Usage

xplot_distrib(
  xpdb,
  mapping = NULL,
  type = "hr",
  guide = FALSE,
  xscale = "continuous",
  yscale = "continuous",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "density_plot",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. histogram_fill = 'blue', rug_sides = 'b', etc.

• histogram: options to geom_histogram

• density: options to geom_density

• rug: options to geom_rug

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter xplot_qq

Examples

# A simple histogram
xplot_distrib(xpdb_ex_pk, aes(x = WT), type = 'hr')

# A simple density plot
xplot_distrib(xpdb_ex_pk, aes(x = CWRES), type = 'dr')

Description

Manually generate QQ plots from an xpdb object.

Usage

xplot_qq(
  xpdb,
  mapping = NULL,
  type = "p",
  guide = FALSE,
  xscale = "continuous",
  yscale = "continuous",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "qq_plot",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', etc.

• point: options to geom_point

• guide: options to geom_abline

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_scatter xplot_distrib

Examples

xplot_qq(xpdb_ex_pk, aes(sample = CWRES), guide = TRUE)

Description

Manually generate scatter plots from an xpdb object.

Usage

xplot_scatter(
  xpdb,
  mapping = NULL,
  group = "ID",
  type = "pls",
  guide = FALSE,
  xscale = "continuous",
  yscale = "continuous",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "scatter_plot",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  ...
)

Arguments

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. point_color = 'blue', smooth_method = 'lm', etc.

• point: options to geom_point

• line: options to geom_line

• guide: options to geom_abline

• smooth: options to geom_smooth

• text: options to geom_text

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Template titles

Template titles can be used to create highly informative diagnostics plots. They can be applied to any plot title, subtitle, caption and tag. Template titles are defined via a single string containing key variables staring 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''. The available key variables are listed under template_titles.

See Also

xplot_distrib xplot_qq

Examples

xplot_scatter(xpdb_ex_pk, aes(x = IPRED, y = DV))

Description

Gather model outputs into a R database

Usage

xpose_data(
  runno = NULL,
  prefix = "run",
  ext = ".lst",
  file = NULL,
  dir = NULL,
  gg_theme = theme_readable,
  xp_theme = theme_xp_default(),
  simtab = NULL,
  manual_import = NULL,
  ignore = NULL,
  check_ext = TRUE,
  extra_files,
  quiet,
  ...
)

Arguments

File path generation

The rules for model file names generation are as follow:

• with runno: the full path is generated as <dir>/<prefix><runno>.<ext> e.g. with dir = 'model/pk', prefix = 'run', runno = '001', ext = '.lst' the resulting path would be model/pk/run001.lst

• with file: the full path is generated as <dir>/<file> e.g. with dir = 'model/pk', file = 'run001.lst' the resulting path would also be model/pk/run001.lst. Note: in this case the file extension should be provided as part of the 'file' argument.

Table format requirement

When importing data, an ID column must be present in at least one table for each problem and for each 'firstonly' category. ID columns are required to properly combine/merge tables and removing NA records. If ID columns are missing xpose will return the following warning: Dropped `<tablenames>` due to missing required `ID` column.

Examples

## Not run: 
# Using the `file` argument to point to the model file:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models')

# Using the `runno` argument to point to the model file:
xpdb <- xpose_data(runno = '001', ext = '.lst', dir = 'models')

# Using the `extra_files` argument to import specific output files only:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', extra_files = c('.ext', '.phi'))

# Using `ignore` to disable import of tables and output files:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', ignore = c('data', 'files'))

# Using `simtab` to disable import of simulation tables
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', simtab = FALSE)


## End(Not run)

Description

Built as a wrapper around ggsave, this function facilitates the export of xpose plots.

Usage

xpose_save(
  plot = last_plot(),
  file = NULL,
  dir = NULL,
  device = NULL,
  scale = 1,
  width = 7,
  height = 6,
  units = c("in", "cm", "mm", "px"),
  dpi = 200,
  limitsize = TRUE,
  bg = NULL,
  ...
)

Arguments

Examples

## Not run: 
xpdb_ex_pk %>%
 dv_vs_ipred() %>%
 xpose_save(file = file.path(tempdir(), "dv_vs_ipred_example.pdf"))

## End(Not run)