Title:	Extra Functionality for the 'xpose' Package
Version:	0.0.2
Description:	Adding some at-present missing functionality, or functions unlikely to be added to the base 'xpose' package. This includes some diagnostic plots that have been missing in translation from 'xpose4', but also some useful features that truly extend the capabilities of what can be done with 'xpose'. These extensions include the concept of a set of 'xpose' objects, and diagnostics for likelihood-based models.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	assertthat, cli, colorspace, conflicted, dplyr (≥ 1.1.2), forcats (≥ 1.0.0), GGally, ggplot2 (≥ 3.4.2), glue, lifecycle, magrittr, pmxcv, purrr (≥ 1.0.1), readr (≥ 2.1.4), rlang, stats, stringr (≥ 1.5.0), tibble (≥ 3.2.1), tidyr (≥ 1.3.0), tidyselect, utils, vctrs, xpose
Suggests:	DiagrammeR, grDevices, knitr, rmarkdown, testthat (≥ 3.0.0), vdiffr
Config/testthat/edition:	3
Depends:	R (≥ 2.10)
LazyData:	true
VignetteBuilder:	knitr
URL:	https://jprybylski.github.io/xpose.xtras/, https://github.com/jprybylski/xpose.xtras
NeedsCompilation:	no
Packaged:	2024-11-20 19:03:45 UTC; PRYBYJ
Author:	John Prybylski [aut, cre]
Maintainer:	John Prybylski <john.prybylski@pfizer.com>
Repository:	CRAN
Date/Publication:	2024-11-21 17:20:02 UTC

xpose.xtras: Extra Functionality for the 'xpose' Package

Description

Adding some at-present missing functionality, or functions unlikely to be added to the base 'xpose' package. This includes some diagnostic plots that have been missing in translation from 'xpose4', but also some useful features that truly extend the capabilities of what can be done with 'xpose'. These extensions include the concept of a set of 'xpose' objects, and diagnostics for likelihood-based models.

Author(s)

Maintainer: John Prybylski john.prybylski@pfizer.com (ORCID)

See Also

Useful links:

• https://jprybylski.github.io/xpose.xtras/

• https://github.com/jprybylski/xpose.xtras

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Binary check if LHS is parent of LHS

Description

Binary check if LHS is parent of LHS

Usage

possible_parent %p% possible_child

Arguments

Value

⁠<logical>⁠ TRUE if LHS is parent of RHS

Examples

# Detect direct parent
pheno_set$run6 %p% pheno_set$run7

# Detect non-parentage (does not try to "flip" parentage)
pheno_set$run6 %p% pheno_set$run5

# Does not detect grand-parentage
pheno_set$run6 %p% pheno_set$run13

Describe parameter associations

Description

The relationship between structural parameters and omega parameters can be described. This is useful if it deviates from the typical log-normal.

Default transformations are those that are built into pmxcv, but see examples for how associations can be described for other relationships.

Usage

add_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)

drop_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)

Arguments

Details

At time of writing, the built-in distributions for pmxcv are below. Those marked with an asterisk require a fixed effect parameter to calculate CV.

• log typical log-normal. Optional exact parameter (if TRUE, default, will not calculate with integration); this is unrelated to the cvtype option. Note, if cvtype is set to "sqrt", log-normal gte_prm CVs will use the square root, not any integration or analytical estimate, regardless of how this association is specified..

• logexp* modified log-normal log(1+X)

• logit* logit-normal

• arcsin* arcsine-transform

• nmboxcox* Box-Cox transform as typically implemented in pharmacometrics. Requires a lambda parameter.

To pass a custom parameter, use custom transform, and pass pdist and qdist to that transform. See Examples.

Reminder about qdist and pdist: Consider that qlogis transforms a proportion to a continuous, unbounded number; it is the logit transform. The pdist function converts a continuous, unbounded number to a proportion; it is the inverse logit transform. Other R stats functions work similarly, and as such functions used as qdist and pdist values are expected to act similarly.

Note that the functions used in describing associations are not real functions, it is just the syntax for this application. Based on examples, be mindful of where positional arguments would acceptable and where named arguments are required. Care has been given to provide a modest amount of flexibility with informative errors for fragile points, but not every error can be anticipated. If this function or downstream results from it seem wrong, the association syntax should be scrutinized. These "functions" are not processed like in mutate_prm, so (eg) the2 will not be substituted for the value of the2; if lambda is a fitted value (like the2), in that edge case the value of the2 should be written explicitly in the association formula, and if any mutate_prm changes the2 then users should be mindful of the new association needed. This may be updated in the future.

Format for associations is: LHS~fun(OMEGA, args...)

• LHS: Selector for a fixed effect parameter. Can be ⁠the{m}⁠ (eg, the1), {name} (eg, THETA1) or {label} (eg, TVCL). These should not be quoted. Multiple associations can be defined at once with +. Cannot be empty.

• RHS: Should be a simple call to only one function, which should be custom or one of the built-in distributions or custom(...). A lot of things can look like simple calls, so may not break immediately; keep to the described format and everything should be fine.

• RHS OMEGA: Selector for omega variable. Similar rules to the fixed effect selector. Can be ⁠ome{m}⁠, {name} or {label}, limited to diagonal elements. Should not be quoted. OMEGA is not a named argument (OMEGA={selector} should not be considered valid); whatever is used as the first argument to the "function" will be considered an OMEGA selector. NOTE, if selecting an OMEGA parameter by name (eg, OMEGA(2,2)), backticks (eg `OMEGA(2,2)`) must be used or else the selection will throw an error.

• RHS args: Applies when the distribution has extra arguments. If these are limited to 1, can be passed by position (eg, lambda for nmboxcox and exact for log). For custom(), qdist, pdist and any arguments needed to pass to them should be named.

For the nmboxcox transformation, a lambda value (especially negative ones) may not work well with the integration-based CV estimation. This may occur even if the lambda is fitted and stable in that fitting, but it cannot be predicted which ones will be affected. This note is intended to forewarn that this might happen.

Value

An updated xp_xtras object

References

Prybylski, J.P. Reporting Coefficient of Variation for Logit, Box-Cox and Other Non-log-normal Parameters. Clin Pharmacokinet 63, 133-135 (2024). https://doi.org/10.1007/s40262-023-01343-2

See Also

dist.intcv

Examples

pheno_base %>%
   add_prm_association(the1~log(IIVCL),V~log(IIVV)) %>%
   get_prm() # get_prm is the only way to see the effect of associations

# These values are not fitted as logit-normal, but
# just to illustrate:
pheno_final %>%
   add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) %>%
   get_prm()

# ... same for Box-Cox
pheno_base %>%
   add_prm_association(V~nmboxcox(IIVV, lambda=0.5)) %>%
   # Naming the argument is optional
   add_prm_association(CL~nmboxcox(IIVCL, -0.1)) %>%
   get_prm()

# A 'custom' use-case is when logexp, log(1+X), is
# desired but 1 is too large.
# Again, for this example, treating this like it applies here.
pheno_base %>%
  add_prm_association(V~custom(IIVV, qdist=function(x) log(0.001+x),
        pdist=function(x) exp(x)-0.001)) %>%
   get_prm()

# Dropping association is easy
bad_assoc <- pheno_final %>%
   add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV))
bad_assoc

Add relationship(s) to an xpose_set

Description

Add relationship(s) to an xpose_set

Usage

add_relationship(xpdb_s, ..., .warn = TRUE, .remove = FALSE)

remove_relationship(xpdb_s, ...)

Arguments

Value

An xpose_set object with relationships added

Examples

xpdb_set %>%
  add_relationship(mod1~fix2) # ouroboros

xpdb_set %>%
  remove_relationship(fix1~mod2) # split down the middle

Add one or more xpdb objects to an xpose_set

Description

Add one or more xpdb objects to an xpose_set

Usage

add_xpdb(xpdb_s, ..., .relationships = NULL)

Arguments

Value

An xpose_set object with the new xpdb objects added

Examples

data("xpdb_ex_pk", package = "xpose")

add_xpdb(xpdb_set, ttt=xpdb_ex_pk)

Level-defining helper functions

Description

Level-defining helper functions

Usage

as_leveler(x, .start_index = 1)

is_leveler(x)

lvl_bin(x = c("No", "Yes"), .start_index = 0)

lvl_sex()

lvl_inord(x, .start_index = 1)

Arguments

Value

Special character vector suitable to be used as leveler

Examples

set_var_levels(xpdb_x,
  SEX = lvl_sex(),
  MED1 = lvl_bin(),
  MED2 = lvl_inord(c("n","y"), .start_index = 0)
  )

Convert an object to an xpose_data and xp_xtras object

Description

This function masks the default in xpose package, adding the xp_xtras class to default xpose_data objects.

Usage

as_xpdb_x(x)

as_xp_xtras(x)

check_xpdb_x(x, .warn = TRUE)

check_xp_xtras(...)

Arguments

Value

<xpose_data> and <xp_xtras> object

Examples

xp_x <- as_xpdb_x(xpose::xpdb_ex_pk)
check_xpdb_x(xp_x)

Add individual objective function to data

Description

Add individual objective function to data

Usage

backfill_iofv(xpdb, .problem = NULL, .subprob = NULL, .label = "iOFV")

Arguments

Details

This function will only work for objects with software listed as nonmem, which has a phi file and with an OBJ column in that file.

Value

<xp_xtras> object with new column in the data and a column with iofv var type.

Examples

xpdb_x %>%
  backfill_iofv() %>%
  list_vars()

Non-simulation based likelihood model diagnostic

Description

These plots attempt to provide a means of verifying that the estimated likelihoods and probabilities for categorical outcomes are captured within the model.

When the smooth spline is included (type includes "s"), it is expected that the overall trend is up and to the right; a relatively flat trend suggests that the modeled likelihood is inconsistent with the observed outcome.

Usage

catdv_vs_dvprobs(
  xpdb,
  mapping = NULL,
  cutpoint = 1,
  type = "vbs",
  title = "@y vs. @x | @run",
  subtitle = "Ofv: @ofv, Number of individuals: @nind",
  caption = "@dir",
  tag = NULL,
  xlab = c("probability", "basic"),
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Value

The desired plot

Examples

# Test M3 model
pkpd_m3 %>%
  # Need to ensure var types are set
  set_var_types(catdv=BLQ,dvprobs=LIKE) %>%
  # Set probs
  set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>%
  # Optional, but useful to set levels
  set_var_levels(1, BLQ = lvl_bin()) %>%
  # Plot with basic xlab makes no assumptions
  catdv_vs_dvprobs(xlab = "basic")

# Test categorical model
vismo_xpdb <- vismo_pomod  %>%
  set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>%
  set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23)

# Various cutpoints (note axes labels and texts)
vismo_xpdb %>%
  catdv_vs_dvprobs(xlab = "basic")
vismo_xpdb %>%
  catdv_vs_dvprobs(cutpoint = 2, xlab = "basic")
vismo_xpdb %>%
  catdv_vs_dvprobs(cutpoint = 3, xlab = "basic")

# Latter is arguably clearer with default xlab
vismo_xpdb %>%
  catdv_vs_dvprobs(cutpoint = 3)

Verify validity of level list

Description

Verify validity of level list

Usage

check_levels(lvl_list, index)

Arguments

Value

Nothing, warning or error

Check an xpose_set object

Description

Check an xpose_set object

Usage

check_xpose_set(xpdb_s, .warn = TRUE)

check_xpose_set_item(xpdb_s_i, .example = xpdb_set)

Arguments

Value

TRUE or error thrown

Examples

check_xpose_set(xpdb_set)

check_xpose_set_item(xpdb_set$mod1)

Backfill utility for descriptions

Description

A slightly more generic approach to getting model descriptions.

Usage

desc_from_comments(
  xpdb,
  start_check = ".*description",
  maxlines = 5,
  remove = paste0(start_check, ":\\s*"),
  extra_proc = c,
  collapse = " "
)

Arguments

Value

The description-updated <xpose_data) object

See Also

set_prop()

Examples

# This has a description, but it's not visible by default
pheno_base

# It can be added with the following
pheno_base %>%
  desc_from_comments()

# Extra processing for preference can also implemented
pheno_base %>%
  desc_from_comments(extra_proc = tolower)

# If a run label ($PROB) would make a good description, use the
# following instead:
pkpd_m3 %>%
  set_prop(descr=get_prop(pkpd_m3,"label"))

Visualize xpose_set

Description

In its current state, this function is intended to provide a simple visual representation of an xpose_set. Functionality and aesthetic enhancements are expected in future releases.

Usage

diagram_lineage(xpdb_s, ...)

Arguments

Value

A DiagrammeR-compliant graph object.

Examples

diagram_lineage(pheno_set) %>%
  DiagrammeR::render_graph(layout="tree")

Display deltaOFV values across xpose_set

Description

If no base model is provided, and if lineage is unclear, the first model in the xpose_set is used as the base model.

Usage

## S3 method for class 'xpose_set'
diff(x, ...)

Arguments

Value

<numeric> vector of deltaOFV values

Check if any xpose_data objects are repeated in xpose_set

Description

Check if any xpose_data objects are repeated in xpose_set

Usage

## S3 method for class 'xpose_set'
duplicated(x, incomparables = FALSE, ...)

Arguments

Value

A logical vector or list of logical vectors

Model average plots

Description

This is for use when the model averaging of a set is planned.

Usage

dv_vs_ipred_modavg(
  xpdb_s,
  ...,
  .lineage = FALSE,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  quiet
)

dv_vs_pred_modavg(
  xpdb_s,
  ...,
  .lineage = FALSE,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  quiet
)

ipred_vs_idv_modavg(
  xpdb_s,
  ...,
  .lineage = FALSE,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  quiet
)

pred_vs_idv_modavg(
  xpdb_s,
  ...,
  .lineage = FALSE,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  quiet
)

plotfun_modavg(
  xpdb_s,
  ...,
  .lineage = FALSE,
  avg_cols = NULL,
  avg_by_type = NULL,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  .fun = NULL,
  .funargs = list(),
  quiet
)

Arguments

Value

The desired plot

See Also

modavg_xpdb()

Examples

pheno_set %>%
  dv_vs_ipred_modavg(run8,run9,run10, auto_backfill = TRUE)

pheno_set %>%
  dv_vs_pred_modavg(run8,run9,run10, auto_backfill = TRUE)

pheno_set %>%
  ipred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE)

pheno_set %>%
  pred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE)

# Model averaged ETA covariates
pheno_set %>%
  plotfun_modavg(run8,run9,run10, auto_backfill = TRUE,
     avg_by_type = "eta",.fun = eta_vs_catcov,
     # Note quoting
     .funargs = list(etavar=quote(ETA1)))

Master xpdb editing function

Description

Generic function used to build dedicated editing functions

Usage

edit_xpose_data(
  .fun,
  .fname,
  .data,
  ...,
  .problem,
  .source,
  .where,
  check_quos = FALSE
)

Arguments

Value

The modified xpose_data object

Grid plots

Description

This is essentially a wrapper around ggpairs, except it uses xpose motifs and styling. Note that this function produces a lot of repetitive output if quiet=FALSE; this may not be an issue, but it could look like an error has occurred if many covariates and individual parameter estimates are included.

Usage

eta_grid(
  xpdb,
  mapping = NULL,
  etavar = NULL,
  drop_fixed = TRUE,
  title = "Eta correlations | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  pairs_opts,
  .problem,
  quiet,
  ...
)

cov_grid(
  xpdb,
  mapping = NULL,
  cols = NULL,
  covtypes = c("cont", "cat"),
  show_n = TRUE,
  drop_fixed = TRUE,
  title = "Covariate relationships | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  pairs_opts,
  .problem,
  quiet,
  ...
)

eta_vs_cov_grid(
  xpdb,
  mapping = NULL,
  etavar = NULL,
  cols = NULL,
  covtypes = c("cont", "cat"),
  show_n = TRUE,
  drop_fixed = TRUE,
  title = "Eta covariate correlations | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  etacov = TRUE,
  pairs_opts,
  .problem,
  quiet,
  ...
)

Arguments

Value

xp_tras_plot object

Examples

eta_grid(xpdb_x)
cov_grid(xpdb_x)
eta_vs_cov_grid(xpdb_x)

# Labels and units are also supported
xpdb_x %>%
  xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>%
  xpose::set_var_units(AGE="yrs") %>%
  set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>%
  eta_vs_cov_grid()

Eta categorical covariate plots (typical)

Description

Eta categorical covariate plots (typical)

Usage

eta_vs_catcov(
  xpdb,
  mapping = NULL,
  etavar = NULL,
  drop_fixed = TRUE,
  orientation = "x",
  show_n = check_xpdb_x(xpdb, .warn = FALSE),
  type = "bol",
  title = "Eta versus categorical covariates | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Details

The ability to show number per covariate level is inspired by the package pmplots, but is implements here within the xpose ecosystem for consistency.

Value

The desired plot

Examples

eta_vs_catcov(xpdb_x)

# Labels and units are also supported
xpdb_x %>%
  xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>%
  xpose::set_var_units(AGE="yrs") %>%
  set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>%
  eta_vs_catcov()

Eta continuous covariate plots (typical)

Description

Eta continuous covariate plots (typical)

Usage

eta_vs_contcov(
  xpdb,
  mapping = NULL,
  etavar = NULL,
  drop_fixed = TRUE,
  linsm = FALSE,
  type = "ps",
  title = "Eta versus continuous covariates | @run",
  subtitle = "Based on @nind individuals, Eta shrink: @etashk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

Value

The desired plot

Examples

eta_vs_contcov(xpdb_x)

# Labels and units are also supported
xpdb_x %>%
  xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>%
  xpose::set_var_units(AGE="yrs") %>%
  set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>%
  eta_vs_contcov()

Expose a model parameter of xpdb objects in an xpose_set

Description

Expose a model parameter of xpdb objects in an xpose_set

Usage

expose_param(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)

Arguments

Details

The parameter returned will be top-level, and to avoid conflicting names will be prepended by .. (e.g., ..ome1). The selector used to fetch the parameter will be used in this .. name. If a better name is preferred, there are convenient renaming functions from dplyr where needed.

When using parameter selectors, quotations should be used for more complex names, like "OMEGA(1,1)", since these may be read incorrectly otherwise.

The untransformed parameter is used for this exposure. The get_prm call uses transform=FALSE.

Value

An xpose_set object with the parameter exposed

See Also

expose_property()

Examples

pheno_set %>%
  expose_param(the1) %>%
  reshape_set()


pheno_set %>%
  expose_param(RUVADD, "OMEGA(1,1)") %>%
  reshape_set()

# This function is useful for generating a model-building table
pheno_set %>%
  # Determine longest lineage
  select(all_of(xset_lineage(.))) %>%
  # Select key variability parameters
  expose_param(RUVADD, "OMEGA(1,1)") %>%
  # Make sure all models have descriptions
  focus_qapply(desc_from_comments) %>%
  # Extract description
  expose_property(descr) %>%
  # Transform to tibble
  reshape_set() # %>% pipe into other processing

Expose a property of xpdb objects in an xpose_set

Description

Expose a property of xpdb objects in an xpose_set

Usage

expose_property(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)

Arguments

Details

The property returned will be top-level, and to avoid conflicting names will be prepended by .. (e.g., ..descr).

For some properties, transformations are applied automatically to make them more useful. This includes:

• etashk and epsshk: transformed to numeric vectors as in <get_shk>

• ofv and other per-problem properties: transformed as needed and pulls from each xpdb default problem.

Value

An xpose_set object with the properties exposed

See Also

expose_param()

Examples

xpdb_set <- expose_property(xpdb_set, descr)
xpdb_set$mod1$..descr

xpdb_set <- expose_property(xpdb_set, etashk)
xpdb_set$mod1$..etashk

Place .problem, .subprob and .method into environment consistently

Description

Since this is a common need, it is being functionalized to ensure consistency.

Usage

fill_prob_subprob_method(
  xpdb,
  .problem,
  .subprob,
  .method,
  envir = parent.frame()
)

Arguments

Filtration method for xpose_set

Description

Filtration method for xpose_set

Usage

## S3 method for class 'xpose_set'
filter(.data, ..., .rowwise = FALSE)

Arguments

Value

A filtered xpose_set

Examples

xpdb_set %>%
  filter(label=="mod1")

xpdb_set %>%
  filter(length(parent)>1, .rowwise=TRUE)

Focus on an xpdb object in an xpose_set

Description

For piping, set is passed, but with S3 method transformations are applied to the focused xpdb object.

Usage

focus_xpdb(xpdb_s, ..., .add = FALSE)

unfocus_xpdb(xpdb_s)

focused_xpdbs(xpdb_s)

focus_function(xpdb_s, fn, ...)

focus_qapply(xpdb_s, fn, ..., .mods = everything())

Arguments

Details

While these functions are used internally, it is recognized that they may have value in user scripting. It is hoped these are self-explanatory, but the examples should address common uses.

Note: focus_qapply() (re)focuses as specified in .mods and then un-focuses all elements of the set so should only be used in the case where a quick application suffices. Otherwise, focusing with a sequence of focus_function calls (or a monolithic single focus_function call with a custom function) should be preferred.

Value

An xpose_set object with the focused xpdb object(s)

Examples

# Select two xpdb objects to focus on
xpdb_set %>% focus_xpdb(mod2,fix1)

# Add a focus
xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb(mod1, .add=TRUE)

# Remove focus
xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb()

# Focus function and tidyselect
pheno_set %>%
  focus_xpdb(everything()) %>%
  # Add iOFV col and iofv type to all xpdbs in set
  focus_function(backfill_iofv) %>%
  # Show 1... can do all like this, too, but no need
  unfocus_xpdb() %>%
  select(run6) %>%
  {.[[1]]$xpdb} %>%
  list_vars()

# Quick-apply version of previous example
pheno_set %>%
  focus_qapply(backfill_iofv) %>%
  select(run6) %>%
  {.[[1]]$xpdb} %>%
  list_vars()

Combine a property from all components of a franken_xpdb

Description

Combine a property from all components of a franken_xpdb

Usage

franken_prop(
  xpdb_f,
  xpdb_list,
  prop,
  problem = NULL,
  glue_cmd = function(x) glue::glue_collapse(x, ", ", last = " and "),
  indices = seq_along(xpdb_list)
)

Arguments

Details

This function is meant to be called within franken_xpdb. It is expected to be ready to handle cases where, for example, multiple props are being set in a pipe, or a problem-associated property is being set while a problem=0 property is also being set.

This is a low-level function, so its use outside of internal functions is not intended.

Value

Same as xpdb_f with new properties.

Examples

# This is designed to be called in a function environment which
# would provide something like the following:

xpdb_f <- franken_xpdb(pheno_base, pheno_final, .types="catcov")

xpdb_list <- list(pheno_base, pheno_final)

# The following would be inside the function
xpdb_f %>%
  franken_prop(xpdb_list, "run",
    glue_cmd = function(x) paste(x, collapse="+"))

# xpdb_f may have to be written to a few times if
# and problem-specific combinations are needed:

updated <- xpdb_f %>%
  franken_prop(xpdb_list, "run",
    glue_cmd = function(x) paste(x, collapse="+"))

# problem will also be available. Assume there's
# no reason to loop here, but that may be needed
problem <- 1
updated <- updated %>%
  franken_prop(xpdb_list, "ofv",  problem=problem,
    glue_cmd = function(x) paste(x, collapse="&"))

Combine several xpose_data objects into one

Description

This is an internal function designed to meet the needs of specific plotting functions

Usage

franken_xpdb(
  ...,
  .cols = NULL,
  .types = NULL,
  prop_transforms = NULL,
  problem,
  quiet = TRUE
)

Arguments

Value

The first xpose_data object with new data columns

Examples

franken_xpdb(pheno_base, pheno_final, .types="catcov") %>%
  xpose::get_data() %>%
  select(starts_with("APGR"))

Get full index for xpose_data data

Description

Get full index for xpose_data data

Usage

get_index(xpdb, .problem = NULL, ...)

set_index(xpdb, index, ...)

Arguments

Value

Tibble of index

Examples

get_index(xpose::xpdb_ex_pk)

Access model parameters

Description

Access model parameter estimates from an xpdb object.

Methods have been added to implement extensions. See Details.

Usage

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

Arguments

Details

When using an <xp_xtra> object, this function will add a column to the output where CV% for each diagonal element of omega is calculated. This CV% is with respect to the resulting structural parameter, so unless the default log-normal association is applicable update with add_prm_association.

For log-normal, users may prefer to use the first-order CV% (\sqrt{\omega^2}) instead of the exact. In such case, xpdb <- set_option(xpdb, cvtype="sqrt") will get that preferred form.

If a single omega parameter is associated with multiple fixed effect parameters, the cv column will be a list. For the omega row associated with multiple fixed effect parameters, there will be multiple CV values. This will be the case even if the transformation is log-normal and therefore scale-invariant, given the need for generality.

Note the approach used to calculate CV% assumes an untransformed scale for the fitted parameter value (unrelated to transform=TRUE). That means, for example, that for a logit-normal fitted parameter value, it is expected the value will be something constrained between 0 and 1, not the unbounded, continuous transformed value. The function <mutate_prm> is intended to help where that might be an issue.

Value

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

References

Prybylski, J.P. Reporting Coefficient of Variation for Logit, Box-Cox and Other Non-log-normal Parameters. Clin Pharmacokinet 63, 133-135 (2024). https://doi.org/10.1007/s40262-023-01343-2

See Also

add_prm_association()

Examples

# xpose parameter table
get_prm(xpose::xpdb_ex_pk, .problem = 1)

# xpose.xtra parameter table (basically the same)
get_prm(pheno_final, .problem = 1)

# For the sake of example, even though these were all lognormal:
pheno_final %>%
  add_prm_association(CLpkg~logit(IIVCL)) %>%
  add_prm_association(Vpkg~nmboxcox(IIVV, lambda = 0.01)) %>%
  get_prm(.problem = 1)

Generic function to extract a property from a model summary

Description

Generic function to extract a property from a model summary

Usage

get_prop(xpdb, prop, .problem = NULL, .subprob = NULL, .method = NULL)

Arguments

Value

Exact value for the property

Examples

data("xpdb_ex_pk", package = "xpose")

get_prop(xpdb_ex_pk, "descr")

Get shrinkage estimates from model summary

Description

This function parses shrinkages as they are currently presented in get_summary, so it is dependent on the current implementation of that function.

Usage

get_shk(xpdb, wh = "eta", .problem = NULL, .subprob = NULL, .method = NULL)

Arguments

Value

A numeric vector of shrinkage estimates.

Examples

data("xpdb_ex_pk", package = "xpose")

# eta Shrinkage
get_shk(xpdb_ex_pk)

# epsilon Shrinkage
get_shk(xpdb_ex_pk, wh = "eps")

Grab processed xpose_plot

Description

This function is very simple and unlikely to capture every possible situation. Paginated plots are not supported.

This is helpful for working with xpose plots in patchwork or ggpubr functions.

Usage

grab_xpose_plot(plot)

Arguments

Value

Grob or list of grobs

Examples

single_plot <- xpdb_x %>%
eta_vs_catcov(etavar = ETA1) %>%
grab_xpose_plot()

listof_plots <- xpdb_x %>%
eta_vs_catcov(etavar = c(ETA1,ETA3)) %>%
grab_xpose_plot()

Objective function changes across models

Description

Another visualization of how individual objective functions change over the course of model development.

Usage

iofv_vs_mod(
  xpdb_s,
  ...,
  .lineage = FALSE,
  auto_backfill = FALSE,
  mapping = NULL,
  orientation = "x",
  type = "bjc",
  title = "Individual OFVs across models",
  subtitle = "Based on @nind individuals, Initial OFV: @ofv",
  caption = "Initial @dir",
  tag = NULL,
  axis.text = "@run",
  facets,
  .problem,
  quiet
)

Arguments

Value

The desired plot

Examples

pheno_set %>%
  focus_qapply(backfill_iofv) %>%
  iofv_vs_mod()

pheno_set %>%
  focus_qapply(backfill_iofv) %>%
  iofv_vs_mod(run3,run11,run14,run15)

pheno_set %>%
  focus_qapply(backfill_iofv) %>%
  iofv_vs_mod(.lineage = TRUE)

Compare model predictions

Description

For two models in an xpose_set, these functions are useful in comparing individual and population predictions

Usage

ipred_vs_ipred(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "pls",
  title = "Individual prediction comparison | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet
)

pred_vs_pred(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "pls",
  title = "Population prediction comparison | @run",
  subtitle = "Ofv: @ofv, Eps shrink: @epsshk",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet
)

Arguments

Value

The desired plot

Examples

pheno_set %>%
  ipred_vs_ipred(run5,run15)

pheno_set %>%
  pred_vs_pred(run5,run15)

Add simulation counter

Description

Add a column containing a simulation counter (irep). A new simulation is counted every time a value in x is different than its previous value and is a duplicate.

This version of the function does not require IDs be ascending, but does not work for datasets where IDs are repeated (not in sequence). Both cases are read as separate individuals for NONMEM, but NONMEM does not need to detect repetition of ID sequences (for NONMEM, 1,1,2,2,3,3,1,1,2,2,3,3 is 6 individuals, regardless of being 2 repeats of 3 individuals). Given the vast majority of datasets use 1 individual per ID, (which cannot be said about IDs always being ascending), only one of these corrections is implemented.

Usage

irep(x, quiet = FALSE)

Arguments

Details

Bugfix for irep.

Value

⁠<numeric>⁠ vector tracking the number of simulations based on unique subject IDs.

Examples

data("xpdb_ex_pk", package = "xpose")

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

Convenience functions used in package

Description

Convenience functions used in package

Usage

is_formula_list(x)

Arguments

Value

⁠<logical>⁠ TRUE if is a list of formulas

Basic class checker for xp_xtras

Description

Basic class checker for xp_xtras

Usage

is_xp_xtras(x)

Arguments

Value

<logical> TRUE if xp_xtras object

Examples

is_xp_xtras(xpose::xpdb_ex_pk)

is_xp_xtras(xpdb_x)

For a categorical DV variable, show associated probabilities

Description

A convenient quick check for how probabilities are currently assigned, based on set_dv_probs.

Usage

list_dv_probs(xpdb, .problem = NULL, .dv_var = NULL)

Arguments

Value

<tibble> of probabilities

Examples

pkpd_m3 %>%
  set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>%
  list_dv_probs(.dv_var=BLQ)

Updates to list_vars

Description

To accommodate changes made in xpose.xtras, <list_vars> needed some minimal updates.

Usage

list_vars(xpdb, .problem = NULL, ...)

## Default S3 method:
list_vars(xpdb, .problem = NULL, ...)

## S3 method for class 'xp_xtras'
list_vars(xpdb, .problem = NULL, ...)

Arguments

Value

<tibble> of variables

Examples

list_vars(xpose::xpdb_ex_pk)

list_vars(xpdb_x)

Create a model-averaged xpose data object

Description

This function is a helper for plotting functions where models in an xpose_set can be averaged together. The implementation attempts to match and extend from the cited prior work.

Usage

modavg_xpdb(
  xpdb_s,
  ...,
  .lineage = FALSE,
  avg_cols = NULL,
  avg_by_type = NULL,
  algorithm = c("maa", "msa"),
  weight_type = c("individual", "population"),
  auto_backfill = FALSE,
  weight_basis = c("ofv", "aic", "res"),
  res_col = "RES",
  quiet
)

Arguments

Value

Weight-averaged <xpose_data> object.

References

Uster, D.W., Stocker, S.L., Carland, J.E., Brett, J., Marriott, D.J.E., Day, R.O. and Wicha, S.G. (2021), A Model Averaging/Selection Approach Improves the Predictive Performance of Model-Informed Precision Dosing: Vancomycin as a Case Study. Clin. Pharmacol. Ther., 109: 175-183. https://doi.org/10.1002/cpt.2065

Examples

pheno_set %>%
  modavg_xpdb(
    avg_cols = IPRED,
    auto_backfill = TRUE,
    algorithm = "maa",
    weight_basis = "aic"
  )

Add, remove or rename variables in an xpdb

Description

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

Note: this function uses xpose.xtras::edit_xpose_data, but is otherwise the same as <xpose::mutate>.

Usage

mutate_x(.data, ..., .problem, .source, .where)

rename_x(.data, ..., .problem, .source, .where)

Arguments

Value

An updated xpose data object

Mutation method for xpose_set

Description

Mutation method for xpose_set

Usage

## S3 method for class 'xpose_set'
mutate(.data, ..., .force = FALSE, .retest = !.force, .rowwise = FALSE)

Arguments

Value

A set with updated top-level data (unless focused)

Examples

xpdb_set %>%
  # Adds foo = bar for all objects in the set
  mutate(foo = "bar") %>%
  # Reshape to visualize
  reshape_set()

Transform parameter values in place

Description

Apply transformations to fitted parameter values.

As fitted, sometimes parameter values are not as easy to communicate, but to transform them outside of the xpose ecosystem limits some available features. To have the best experience, this function can update the parameter values that are used by xpose get_prm functions. At this time these transformations are not applied to param vars (list_vars), but that can already be done with the mutate method.

This only works for theta parameters.

All valid mutations are applied sequentially, so a double call to the2~the2^3 will result in effectively the2~the2^9, for example.

RSE values are calculated at runtime within get_prm, so they are not updated (or updatable) with this function.

Usage

mutate_prm(
  xpdb,
  ...,
  .autose = TRUE,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  .sesim = 1e+05,
  quiet
)

Arguments

Details

Important points about covariance and correlation

Covariance and correlation parameters are adjusted when standard error (SE) values are changed directly or with .autose. When a transformation is applied as a function for the fixed effect parameter (eg, ~plogis), the resulting SE may have an unexpected scale; this is because it is now reporting the standard deviation of a transformed and potentially non-normal distribution. If the parameter were fit in the transformed scale (constrained to any appropriate bounds), it would likely have a different SE given that most covariance estimation methods (excluding non-parametric and resampling-based) will treat the constrained parameter as continuous and unconstrained.

The updates to variance-covariance values (and the correlation values, though that is mostly invariant) are applied to the entire matrices. When piped directly into get_prm, only the SE estimate is shown, but <get_file> can be used to see the complete updated variance-covariance values. This could be useful if those matrices are being used to define priors for a Bayesian model fitting, as the re-scaling of off-diagonal elements is handled automatically.

A function to transform parameters will result in a more accurate autose result. If a call (the1~exp(the)) or a value (the1~2) are used, the standard error will be simply scaled.

Value

An updated xp_xtras object with mutated parameters

Examples

vismo_pomod %>%
  # Function
  mutate_prm(THETA11~exp) %>%
  # Value (se will not be scaled); plogis = inverse logit
  mutate_prm(THETA12~plogis(THETA12)) %>%
  get_prm()

Select parameter row number

Description

The selection rules are described in <add_prm_association>.

Usage

param_selector(sel, prm_tbl)

Arguments

Value

<integer> of selected row number. Can be used to get value and other elements of information from prm_tbl.

An xp_xtras example of a base model

Description

Base model for phenobarbital in neonates.

Usage

pheno_base

Format

xp_xtras

An xp_xtras object.

Details

This is run6 in <pheno_set>

Source

https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd

An xp_xtras example of a final model

Description

Final model for phenobarbital in neonates.

Usage

pheno_final

Format

xp_xtras

An xp_xtras object.

Details

This is re-parameterized from the covariate-building work, which in this case did not identify a relationship with Apgar score.

This is run16 in <pheno_set>

Source

https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd

An xp_xtras example of a final model

Description

Final model for phenobarbital in neonates.

Usage

pheno_saem

Format

xp_xtras

An xp_xtras object.

Details

This is the same as pheno_final but fitted with SAEM/IMP.

Not a part of <pheno_set>

Source

https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd

A more complex example of xpose_set object

Description

Model-building set for the phenobarbital in neonates PK data used across multiple packages.

Usage

pheno_set

Format

xpose_set

An xpose_set object of length 14 with a branched lineage.

Details

This is not a demonstration of high-quality model-building, it is just a typical and simple example.

Source

https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd

An xp_xtras example of an M3 model

Description

A representative PK/PD model with M3 fitting applied.

Usage

pkpd_m3

Format

xp_xtras

An xp_xtras object.

Source

https://doi.org/10.1002/psp4.13219

References

Beal, S.L. Ways to Fit a PK Model with Some Data Below the Quantification Limit. J Pharmacokinet Pharmacodyn 28, 481-504 (2001). https://doi.org/10.1023/A:1012299115260

Prybylski JP. Indirect modeling of derived outcomes: Are minor prediction discrepancies a cause for concern? CPT Pharmacometrics Syst Pharmacol. 2024; 00: 1-9. doi:10.1002/psp4.13219

An xp_xtras example of an M3 model (dataset)

Description

The dataset used to fit the pkpd_m3 model.

Usage

pkpd_m3_df

Format

xp_xtras

An xp_xtras object.

Source

https://doi.org/10.1002/psp4.13219

References

Prybylski JP. Indirect modeling of derived outcomes: Are minor prediction discrepancies a cause for concern? CPT Pharmacometrics Syst Pharmacol. 2024; 00: 1-9. doi:10.1002/psp4.13219

Specific waterfall plots

Description

Differences are second listed model minus first listed. Eg, in eta_waterfall(run1,run2), the when etas in run2 are greater than those in run1, the difference will be positive.

Usage

prm_waterfall(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "bh",
  max_nind = 0.7,
  scale_diff = TRUE,
  show_n = TRUE,
  title = "Parameter changes between models | @run",
  subtitle = "Based on @nobs observations in @nind individuals",
  caption = "@dir",
  tag = NULL,
  facets = NULL,
  facet_scales = "free_x",
  .problem,
  .subprob,
  .method,
  quiet
)

eta_waterfall(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "bh",
  max_nind = 0.7,
  scale_diff = TRUE,
  show_n = TRUE,
  title = "Eta changes between models | @run",
  subtitle = "Based on @nobs observations in @nind individuals",
  caption = "@dir",
  tag = NULL,
  facets = NULL,
  facet_scales = "free_x",
  .problem,
  .subprob,
  .method,
  quiet
)

iofv_waterfall(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "bh",
  max_nind = 0.7,
  scale_diff = FALSE,
  show_n = TRUE,
  title = "iOFV changes between models | @run",
  subtitle = "Based on @nobs observations in @nind individuals",
  caption = "@dir",
  tag = NULL,
  facets = NULL,
  facet_scales = "free_x",
  .problem,
  .subprob,
  .method,
  quiet
)

Arguments

Details

For type-based customization of plots:

• b bar plot (from geom_bar)

• h hline at 0 (from geom_hline)

• t text of change value (from geom_text)

Value

<xpose_plot> object

Examples

# Parameter value changes
pheno_set %>%
  # Ensure param is set
  focus_qapply(set_var_types, param=c(CL,V)) %>%
  prm_waterfall(run5,run6)


# EBE value changes
pheno_set %>%
  eta_waterfall(run5,run6)

# iOFV changes
pheno_set %>%
  focus_qapply(backfill_iofv) %>%
  # Note the default scaling is flipped here
  iofv_waterfall(run5,run6)

Convert levels list into tibble

Description

Consumes formula list and converts into corresponding tibble.

Usage

proc_levels(lvl_list)

Arguments

Value

<tibble> of levels

Pulling method for xpose_set

Description

Pulling method for xpose_set

Usage

## S3 method for class 'xpose_set'
pull(.data, ...)

Arguments

Value

The top-level information for a set requested.

Examples

xpdb_set %>%
  pull(xpdb)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

all_of, any_of, filter, mutate, pull, rename, select

Renaming method for xpose_set

Description

Renaming method for xpose_set

Usage

## S3 method for class 'xpose_set'
rename(.data, ...)

Arguments

Value

Re-labeled set

Examples

xpdb_set %>%
  rename(Mod = mod1)

Reportable digits for model fit

Description

An opinionated function where for optimization routines that report number of significant digits (eg, FO-based), only those number of digits are considered reportable.

Usage

reportable_digits(xpdb, .default = 3, .problem, .subprob, .method)

Arguments

Value

Number of reportable digits

Examples

reportable_digits(xpdb_x)

Convert xpose_set to a nested list.

Description

This amounts to a convenience function for tidy manipulations.

Usage

reshape_set(x)

unreshape_set(y)

Arguments

Value

<tibble> Nested list, or <xpose_set>

Examples

rset <- reshape_set(xpdb_set)
# Properties (exposed and top-level) can be seen. xpdb objects are nested in the xpdb column.
rset %>% dplyr::select(-xpdb) %>% dplyr::glimpse()

unreshape_set(rset)

# The reversibility of reshaping can be confirmed:
identical(xpdb_set,reshape_set(xpdb_set) %>% unreshape_set())

Selection method for xpose_set

Description

Selection method for xpose_set

Usage

## S3 method for class 'xpose_set'
select(.data, ...)

Arguments

Value

Subset of xpose set

Examples

xpdb_set %>%
  select(starts_with("fix"))

xpdb_set %>%
  select(mod1, fix1)

Convenience wrapper for tidyselect

Description

This is intended for use as an internal function to select a subset of xpdb objects from an xpose_set.

It is a lower level version of <select.xpose_set>

Usage

select_subset(xpdb_s, ...)

Arguments

Value

<numeric> vector of indices for selected xpdb objects

Examples

select_subset(mod2, xpdb_s=xpdb_set)

select_subset(dplyr::starts_with("fix"), xpdb_s=xpdb_set)

Base model for xpose_set

Description

Base model for xpose_set

Usage

set_base_model(xpdb_s, ...)

get_base_model(xpdb_s)

unset_base_model(xpdb_s)

Arguments

Value

<xpose_set> object with a base model

Examples

w_base <- xpdb_set %>%
  set_base_model(mod2)
w_base # base model listed in output

get_base_model(w_base) # base model name

unset_base_model(w_base) # base model no longer in output

Set probability columns for categorical endpoints

Description

For categorical DVs or similar endpoints (such as censoring flag columns, like BLQ), this function allows probability columns to be defined for each level.

Usage

set_dv_probs(
  xpdb,
  .problem = NULL,
  ...,
  .dv_var = NULL,
  .handle_missing = c("quiet", "warn", "error")
)

Arguments

Details

The same probability cannot be assigned to multiple values. Pseudo-functions can be used, or new columns can be created to overcome this limitation. The available pseudo-functions should be written like ge(value) (for >=), gt(value) (for >), etc. These comparison names are those used in Perl, Fortran and many other languages. The function eq() should not be used, but it will be ignored either way; equivalence is implied with the base syntax.

Value

<xp_xtras> object with updated probabilities

Examples

pkpd_m3 %>%
 # Not necessary, but correct to set var type before using this
 set_var_types(.problem=1, catdv=BLQ, dvprobs=LIKE) %>%
 # Set var type. Warnings can be helpful unless an inverse likelihood column is available
 set_dv_probs(.problem=1, 1~LIKE, .dv_var = BLQ, .handle_missing = "warn") %>%
 list_vars()

# Same as above with demo of inverse column
pkpd_m3 %>%
 xpose::mutate(INVLIKE = 1-LIKE) %>%
 set_var_types(.problem=1, catdv=BLQ, dvprobs=c(LIKE,INVLIKE)) %>%
 # Note no warning
 set_dv_probs(.problem=1, 1~LIKE, 0~INVLIKE, .dv_var = BLQ, .handle_missing = "warn")%>%
 list_vars()

# With categorical model
vismo_pomod  %>%
 # Update var types
 set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>%
 # Warning (as noted), does not recognize 3 is covered implicitly. That's ok!
 set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23, .handle_missing = "warn")%>%
 list_vars()

# Same as above, but...
vismo_pomod  %>%
 set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>%
 # Default is to not bother users with a warning
 set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23)%>%
 list_vars()

Set an xpose option

Description

Set an xpose option

Usage

set_option(xpdb, ...)

Arguments

Value

xp_xtras object

Examples

xpdb_x <- set_option(xpdb_x, quiet = TRUE)

Set a summary property

Description

Set a summary property

Usage

set_prop(xpdb, ..., .problem = NULL, .subprob = NULL)

Arguments

Details

Although one might be tempted to set custom properties using this function, with the intention to maintain cross-functionality with xpose, users cannot set a non-existent property with this function. When used internally, workarounds to this semi-limitation are used.

Value

xp_xtras object

Examples

set_prop(xpose::xpdb_ex_pk, descr = "New model description") %>%
  xpose::get_summary()

Set variable levels

Description

For variable types such as catcov, it can be convenient to define levels. This function provides a straightforward means to do so, consistent with tidy functions like <case_when>.

Several convenience functions are provided for common levels in <levelers>.

Usage

set_var_levels(
  xpdb,
  .problem = NULL,
  ...,
  .missing = "Other",
  .handle_missing = c("quiet", "warn", "error")
)

Arguments

Value

<xp_xtras> object with updated levels

Examples

set_var_levels(xpdb_x,
  SEX = lvl_sex(),
  MED1 = lvl_bin(),
  MED2 = c(
    0 ~ "n",
    1 ~ "y"
  )
)

Set variable types

Description

<set_var_types> wrapper that accepts tidyselect syntax. Character vector-based selection still works.

set_var_types_x accepts xpose_data or xp_xtras objects.

set_var_types without ⁠_x⁠ is defined with S3 methods. To maintain xpose expectations, the default method is <set_var_types>, but if an xp_xtras object is used, the method uses set_var_types_x.

Usage

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

Arguments

Value

An xpose_data object

Examples

data("xpdb_ex_pk", package = "xpose")

# Change variable type
xpdb_2 <- set_var_types_x(
  xpdb_ex_pk, .problem = 1,
  idv = TAD,
  catcov = starts_with("MED"),
  contcov = c(CLCR,AGE)
  )

Set variable types

Description

<set_var_types> wrapper that accepts tidyselect syntax. Character vector-based selection still works.

set_var_types_x accepts xpose_data or xp_xtras objects.

set_var_types without ⁠_x⁠ is defined with S3 methods. To maintain xpose expectations, the default method is <set_var_types>, but if an xp_xtras object is used, the method uses set_var_types_x.

Usage

## Default S3 method:
set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)

Arguments

Value

An xpose_data object

Examples

data("xpdb_ex_pk", package = "xpose")

# Change variable type
xpdb_2 <- set_var_types_x(
  xpdb_ex_pk, .problem = 1,
  idv = TAD,
  catcov = starts_with("MED"),
  contcov = c(CLCR,AGE)
  )

Set variable types

Description

<set_var_types> wrapper that accepts tidyselect syntax. Character vector-based selection still works.

set_var_types_x accepts xpose_data or xp_xtras objects.

set_var_types without ⁠_x⁠ is defined with S3 methods. To maintain xpose expectations, the default method is <set_var_types>, but if an xp_xtras object is used, the method uses set_var_types_x.

Usage

## S3 method for class 'xp_xtras'
set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)

Arguments

Value

An xpose_data object

Examples

data("xpdb_ex_pk", package = "xpose")

# Change variable type
xpdb_2 <- set_var_types_x(
  xpdb_ex_pk, .problem = 1,
  idv = TAD,
  catcov = starts_with("MED"),
  contcov = c(CLCR,AGE)
  )

Set variable types

Description

<set_var_types> wrapper that accepts tidyselect syntax. Character vector-based selection still works.

set_var_types_x accepts xpose_data or xp_xtras objects.

set_var_types without ⁠_x⁠ is defined with S3 methods. To maintain xpose expectations, the default method is <set_var_types>, but if an xp_xtras object is used, the method uses set_var_types_x.

Usage

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

Arguments

Value

An xpose_data object

Examples

data("xpdb_ex_pk", package = "xpose")

# Change variable type
xpdb_2 <- set_var_types_x(
  xpdb_ex_pk, .problem = 1,
  idv = TAD,
  catcov = starts_with("MED"),
  contcov = c(CLCR,AGE)
  )

Change colors of shark plots

Description

This changes the point and text color in the xp_theme of an xpose_data object.

Usage

shark_colors(
  xpdb,
  upcolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkup_color,
  dncolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkdn_color
)

Arguments

Value

<xpose_data> object

See Also

shark_plot()

Examples

# Where this would fit in a particular workflow
xpose_set(pheno_base, pheno_final) %>%
  # forward functions affecting xpdb objects
  focus_xpdb(everything()) %>%
  # Add iOFVs
  focus_function(backfill_iofv) %>%
  # Change color of all xpdb xp_themes (though only the first one needs to change)
  focus_function(
  function(x) shark_colors(
      x,
      upcolor = "purple",
      dncolor = "green"
    )) %>%
  # See new plot
  shark_plot()

Individual contributions to dOFV

Description

This is intended to match the overall behavior of dOFV.vs.id() in xpose4, within the framework of the xpose_set object.

dofv_vs_id is an alias of the function shark_plot, for recognition.

Usage

shark_plot(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "plt",
  alpha = 0.05,
  df = "guess",
  text_cutoff = 0.8,
  title = "Individual contributions to dOFV | @run",
  subtitle = "Based on @nind individuals, OFVs: @ofv",
  caption = "@dir",
  tag = NULL,
  ylab = "dOFV",
  xlab = "Number of individuals removed",
  opt,
  facets = NULL,
  .problem,
  .subprob,
  .method,
  quiet
)

dofv_vs_id(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "plt",
  alpha = 0.05,
  df = "guess",
  text_cutoff = 0.8,
  title = "Individual contributions to dOFV | @run",
  subtitle = "Based on @nind individuals, OFVs: @ofv",
  caption = "@dir",
  tag = NULL,
  ylab = "dOFV",
  xlab = "Number of individuals removed",
  opt,
  facets = NULL,
  .problem,
  .subprob,
  .method,
  quiet
)

Arguments

Details

For type-based customization of plots:

• p points (using aesthetics for sharkup and sharkdn)

• l lines for dOFV (both total dOFV and significance are plotted)

• t text (using aesthetics for shkuptxt and shkdntxt)

In xpose4, users can control sig.drop, but this function uses alpha and df to determine the critical delta by the likelihood ratio test. It is acknowledged there are situations where this may not be valid, but it is suggested that df or alpha be adjusted to meet the desired sig.drop.

my_alpha <- 0.05
my_df <- 1.34 # fractional, perhaps to account for different IIVs

my_sigdrop <- -stats::qchisq(1-my_alpha, my_df)
my_sigdrop
#> [1] -4.633671
# Then use alpha=my_alpha, df=my_df in `shark_plot` call.

Value

<xpose_plot> object

See Also

shark_colors()

Examples

pheno_set %>%
  # Make sure set has iofv var types defined
  focus_xpdb(everything()) %>%
  focus_function(backfill_iofv) %>%
  # Pick two models or consistent with two_set_dots()
  shark_plot(run6,run11)

pheno_set %>%
  # As before
  focus_xpdb(everything()) %>%
  focus_function(backfill_iofv) %>%
  # Add indicator (or use established covariate)
  mutate(APGRtest = as.numeric(as.character(APGR))<5) %>%
  # Pick two models or consistent with two_set_dots()
  shark_plot(run6,run11, facets = "APGRtest")

Group/ungroup and summarize variables in an xpdb

Description

group_by_x() 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.

Note: this function uses xpose.xtras::edit_xpose_data, but is otherwise the same as <xpose::group_by>.

Usage

group_by_x(.data, ..., .problem, .source, .where)

ungroup_x(.data, ..., .problem, .source, .where)

Arguments

Value

Group data in an xpose data object

Typical processing for plots of 2 sets

Description

Typical processing for plots of 2 sets

Usage

two_set_dots(xpdb_s, ..., .inorder = FALSE, envir = parent.frame())

Arguments

Details

Note that this function does not return valid xpdb-like objects (<xpose_data> or <xp_xtras>). The necessary objects for most functions can be retrieved using mod1$xpdb and mod2$xpdb.

Value

Into environment specified by envir, <xpose_set_item> mod1 and mod2

Translate values to levels

Description

This is intended to be used as a convenience function in plotting where levels are set for some variable.

Usage

val2lvl(vals, lvl_tbl = NULL)

Arguments

Value

A vector of levels corresponding to the input vector.

An xp_xtras example of the discrete-time Markov model of categorical vismodegib data

Description

The referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. This is a fit of the provided discrete-time Markov model to the 50 participant mock data.

Usage

vismo_dtmm

Format

xp_xtras

An xp_xtras object.

Source

Derived from sup-0009 and sup-0010 from the reference.

References

Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487

An xp_xtras example of the proportional odds categorical vismodegib model

Description

The referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. This is a fit of the provided proportional odds model to the 50 participant mock data.

Usage

vismo_pomod

Format

xp_xtras

An xp_xtras object.

Source

Derived from sup-0009 and sup-0010 from the reference.

References

Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487

A tibble of mock data used for fitting vismodegib models

Description

The referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. There is a mock dataset for one person, and using the provided model a 50 participant mock dataset could be generated.

Usage

vismodegib

Format

tibble

An tibble.

Source

Generated using sup-0009 and sup-0010 from the reference.

References

Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487

Ensure consistent style with GGally functions

Description

Ensure consistent style with GGally functions

Usage

wrap_xp_ggally(fn, xp_theme, ...)

Arguments

Value

ggplot2 function

Updated version of the xpose4 theme

Description

Updated version of the xpose4 theme

Usage

xp4_xtra_theme()

Value

An xpose theme object with xpose4 color palette

xp_var Method

Description

To add a small amount of functionality to <xp_var>, this method was created.

Usage

xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE)

## Default S3 method:
xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE)

## S3 method for class 'xp_xtras'
xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE)

Arguments

Value

A tibble of identified variables.

Extra theme defaults

Description

Adds aesthetics for plot components used in this package.

Usage

xp_xtra_theme(base_on = NULL)

Arguments

Details

This package attempts to generate a consistent theme even if users are working with a highly customized xp_theme. There is are only a few hard-coded aesthetics, and the rest are derived from existing aesthetics in base_on, which defaults to the default from xpose.

Only a few options are worth noting. In <xplot_pairs> (and functions using it), the aesthetics for GGally-specific elements like barDiag are defined as ⁠gga(element)_(aesthetic)⁠. The labeller for pairs plots is also changed from the de facto default label_both to label_value, but any labeller can be provided as pairs_labeller.

Value

An xpose theme object

An example xpose_set object

Description

A set of identical xpdb objects to demo various features of xpose.xtras.

Usage

xpdb_set

Format

xpose_set

An xpose_set object of length 4 with a single lineage.

Source

Assembled from the xpdb_ex_pk object in the xpose package.

An example xp_xtras object

Description

The <xpdb_ex_pk> object converted to xp_xtras. For examples.

Usage

xpdb_x

Format

xp_xtras

An xp_xtras object with no extra data filled.

Source

Assembled from the xpdb_ex_pk object in the xpose package.

Default xpose boxplot function

Description

Manually generate boxplots from an xpdb object.

Usage

xplot_boxplot(
  xpdb,
  mapping = NULL,
  type = "bo",
  xscale = "discrete",
  yscale = "continuous",
  orientation = "x",
  group = "ID",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "boxplot",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  jitter_seed,
  ...
)

Arguments

Details

For type-based customization of plots:

• b box-whisker (using default quantiles)

• p points (from geom_dotplot)

• v violin (from geom_violin)

• o outliers (show outliers)

• l line through 0 (or as indicated in hline_yintercept or yline_xintercept)

• s smooth line (from geom_smooth)

• j jitter points (from geom_jitter)

• c connecting lines for jitter points (from geom_path)

Value

The desired plot

Wrapper around ggpairs

Description

Following the xpose design pattern to derive <ggpairs> plots.

Established xplot_ are used to generate parts of the grid.

Usage

xplot_pairs(
  xpdb,
  mapping = NULL,
  cont_opts = list(group = "ID", guide = FALSE, type = "ps"),
  dist_opts = list(guide = FALSE, type = "hr"),
  cat_opts = list(type = "bo", log = NULL),
  contcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb),
    title = "Pearson Corr"),
  catcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb),
    title = "Spearman rho"),
  catcat_opts = list(use_rho = TRUE),
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "pairs",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  progress = rlang::is_interactive() && quiet,
  switch = NULL,
  ...
)

Arguments

Details

There is only limited control over the underlying ggpairs() call given the need to address abstractions in GGally and xpose. However, users can modify key display features. For scatter, distribution and boxplots, the type option is directly forwarded to the user. For upper elements of the matrix, users can modify features of the text displayed or supply some other function entirely (other_fun).

⁠_opts⁠ lists are consumed with <modifyList> from the default, so there is no need to declare preferences that align with the default if updating a subset.

Value

specified pair plot

Generate a set of xpdb objects

Description

This function generates a set of xpose data (xpdb) objects that can be used to define relationships between models. The

Usage

xpose_set(..., .relationships = NULL, .as_ordered = FALSE)

Arguments

Details

Beyond just a list of xpdb objects, an xpose_set adds hierarchical information.

When using .relationships, these should be expressed as tilde formulas, where the left-hand side is children and the right and side is parents. In the simplest case, this would be child ~ parent, but a child can have multiple parents. This syntax expects that the names for models is either declared as argument names in the call, or that the variable names are directly used (i.e., not spliced or passed as an unnamed list).

Value

A list of class xpose_set

Examples

data("xpdb_ex_pk", package = "xpose")

# Arbitrary copy
xpdb_ex_pk2 <- xpdb_ex_pk

# Simplest call
set1 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2)

# With predefined relationships
set2 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2,
  .relationships = list(xpdb_ex_pk2 ~ xpdb_ex_pk)
  )

# Alternative predefined relationships
set2b <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2,
  .as_ordered = TRUE
  )

# With custom labels
set3 <- xpose_set(mod1 = xpdb_ex_pk, mod2 = xpdb_ex_pk2,
  .relationships = list(mod2 ~ mod1)
  )

# Alternative set3 using dyanmic dots
mod_list <- list(
  mod1 = xpdb_ex_pk,
  mod2 = xpdb_ex_pk2
)
mod_rels <- list(
  mod2 ~ mod1
)
set3b = xpose_set(!!!mod_list, .relationships = mod_rels)

Determine lineage within a set

Description

Determine lineage within a set

Usage

xset_lineage(xpdb_s, ..., .spinner = NULL)

Arguments

Details

This function uses a not-especially-optimized tree-searching algorithm to determine the longest lineage starting from whatever is treated as the base model. It is based loosely on <pluck_depth>, but the values at each depth are maintained. As such, for larger sets this function and, more importantly, functions that use it may take some time.

Value

<character> vector of c('base', 'base child', 'base grandchild', ...) or list thereof, depending on dots arguments.

Examples

xset_lineage(xpdb_set)

set_base_model(xpdb_set, fix1) %>%
  xset_lineage()

xset_lineage(xpdb_set, fix1)

Waterfall plot

Description

Generic function primarily used with wrappers targeting types of values changed between two models.

Usage

xset_waterfall(
  xpdb_s,
  ...,
  .inorder = FALSE,
  type = "bh",
  .cols = NULL,
  max_nind = 0.7,
  scale_diff = TRUE,
  show_n = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "waterfall",
  opt,
  facets = NULL,
  facet_scales = "free_x",
  .problem,
  .subprob,
  .method,
  quiet
)

Arguments

Details

For type-based customization of plots:

• b bar plot (from geom_bar)

• h hline at 0 (from geom_hline)

• t text of change value (from geom_text)

Value

The desired plot