VPC package

Description

Create Visual Predictive Checks in R

Author(s)

Ron Keizer ronkeizer@gmail.com

Add noise / residual error to data

Description

Add noise / residual error to data

Usage

add_noise(x, ruv = list(proportional = 0, additive = 0, exponential = 0))

Arguments

Examples

library(dplyr)
ipred <- c(10, 8, 6, 4, 2, 0) %>% add_noise(ruv = list(proportional = 0.1, additive = 0.2))

Add sim index number

Description

Add simulation index number to simulation when not present

Usage

add_sim_index_number(sim, id = "id", sim_label = "sim")

Arguments

Adds stratification to data set

Description

Adds stratification to data set

Usage

add_stratification(dat, strat, verbose = FALSE)

Arguments

Calculate appropriate bin separators for vpc

Description

This function calculates bin separators either using R's native binning approaches available in the classInt library such as 'kmeans', 'jenks', 'pretty' etc. Alternatively, a custom approach is available which is based on finding the nadirs in the density functions for the independent variable. Default approach is k-means clustering.

Usage

auto_bin(dat, type = "kmeans", n_bins = 8, verbose = FALSE, ...)

## S3 method for class 'numeric'
auto_bin(dat, type = "kmeans", n_bins = 8, verbose = FALSE, ...)

## S3 method for class 'data.frame'
auto_bin(dat, type = "kmeans", n_bins = 8, verbose = FALSE, ...)

Arguments

Value

A vector of bin separators

Function to bin data based on a vector of bin separators, e.g. for use in VPC

Description

Function to bin data based on a vector of bin separators, e.g. for use in VPC

Usage

bin_data(x, bins = c(0, 3, 5, 7), idv = "time", labeled = F)

Arguments

Check whether stratification columns are available

Description

Check whether stratification columns are available

Usage

check_stratification_columns_available(data, stratify, type = "observation")

Arguments

Compute Kaplan-Meier statistics

Description

Compute Kaplan-Meier statistics

Usage

compute_kaplan(
  dat,
  strat = "strat",
  reverse_prob = FALSE,
  rtte_conditional = TRUE,
  ci = NULL
)

Arguments

Compute KMMC statistics

Description

Kaplan-Meier Mean Covariate plots are a simulation-based diagnostic to study the influence of covariates and identify potential model misspecification.

Usage

compute_kmmc(dat, strat = NULL, reverse_prob = FALSE, kmmc = "DOSE")

Arguments

Create new vpc theme

Description

Create new vpc theme

Usage

create_vpc_theme(...)

Arguments

Define data column defaults for various softwares

Description

Define data column defaults for various softwares

Usage

define_data_columns(sim, obs, sim_cols, obs_cols, software_type)

Arguments

Draw parameters from multivariate distribution

Description

Draw parameters from multivariate distribution

Usage

draw_params_mvr(ids, n_sim, theta, omega_mat, par_names = NULL)

Arguments

Calculate percentiles below / above lloq / uloq

Description

Calculate percentiles below / above lloq / uloq

Usage

loq_perc(x, limit = 1, cens = "left")

Arguments

Create a customized VPC theme

Description

Create a customized VPC theme

Usage

new_vpc_theme(update = NULL)

Arguments

Details

This function creates a theme that customizes how the VPC looks, i.e. colors, fills, transparencies, linetypes an sizes, etc. The following arguments can be specified in the input list:

• obs_color: color for observations points

• obs_size: size for observation points

• obs_median_color: color for median observation line

• obs_median_linetype: linetype for median observation line

• obs_median_size: size for median observation line

• obs_ci_fill: color for observation CI fill

• obs_ci_color: color for observation CI lines

• obs_ci_linetype: linetype for observation CI lines

• obs_ci_size: size for observations CI lines

• sim_pi_fill: fill color for simulated prediction interval areas

• sim_pi_alpha: transparency for simulated prediction interval areas

• sim_pi_color: color for simulated prediction interval lines

• sim_pi_linetype: linetype for simulated prediction interval lines

• sim_pi_size: size for simulated prediction interval lines

• sim_median_fill: fill color for simulated median area

• sim_median_alpha: transparency for simulated median area

• sim_median_color: color for simulated median line

• sim_median_linetype: linetype for simulated median line

• sim_median_size: size for simulated median line

• bin_separators_color: color for bin separator lines, NA for don't plot

• bin_separators_location: where to plot bin separators ("t" for top, "b" for bottom)

• loq_color: color of line showing limit of quantification

Value

A list with vpc theme specifiers

Examples

theme1 <- new_vpc_theme(update = list(
  obs_color = "red",
  obs_ci_color = "#aa0000",
  obs_alpha = .3,
  sim_pi_fill = "#cc8833",
  sim_pi_size = 2
))
vpc(simple_data$sim, simple_data$obs, vpc_theme = theme1)

Simulate PK data from a 1-compartment iv model

Description

Simulate PK data from a 1-compartment iv model

Usage

pk_iv_1cmt(
  t,
  t_inf = 1,
  tau = 24,
  dose = 120,
  CL = 0.345,
  Vc = 1.75,
  ruv = NULL
)

Arguments

Value

A vector of predicted values, with or without added residual variability

Examples

dat1 <- vpc:::pk_iv_1cmt(t = c(0:72), tau = 24, dose = 120, 
                   CL = 5, Vc = 50)
dat2 <- vpc:::pk_iv_1cmt(t = c(0:72), tau = 24, dose = 120, 
                   CL = 5, Vc = 50, 
                   ruv = list(proportional = 0.1, additive = 0.1))

Simulate PK data from a 1-compartment oral model

Description

Simulate PK data from a 1-compartment oral model

Usage

pk_oral_1cmt(t, tau = 24, dose = 120, ka = 1, ke = 1, cl = 10, ruv = NULL)

Arguments

Value

A vector of predicted values, with or without added residual variability

Examples

dat1 <- vpc:::pk_oral_1cmt(t = c(0:72), tau = 24, dose = 120, 
                     ka = 1, ke = 1, cl = 10)
dat2 <- vpc:::pk_oral_1cmt(t = c(0:72), tau = 24, dose = 120, 
                     ka = 1, ke = 1, cl = 10, 
                     ruv = list(proportional = 0.1, additive = 0.1))

VPC plotting function

Description

This function performs no parsing of data, it just plots the already calculated statistics generated using one of the 'vpc' functions.

Usage

plot_vpc(
  db,
  show = NULL,
  vpc_theme = NULL,
  smooth = TRUE,
  log_x = FALSE,
  log_y = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  verbose = FALSE
)

Arguments

See Also

sim_data, vpc_cens, vpc_tte, vpc_cat

Examples

## See vpc.ronkeizer.com for more documentation and examples

library(vpc)
vpc_db <- vpc(sim = simple_data$sim, obs = simple_data$obs, vpcdb = TRUE)
plot_vpc(vpc_db, title = "My new vpc", x = "Custom x label")

Calculate quantiles respecting the censored data

Description

Calculate quantiles respecting the censored data

Usage

quantile_cens(x, p = 0.5, limit = 1, cens = "left")

Arguments

NONMEM output table import function

Description

Quickly import NONMEM output tables into R. Function taken from 'modelviz' package by Benjamin Guiastrennec. When both skip and header are NULL, read_nmtab will automatically detect the optimal settings to import the tables. When more than one files are provided for a same NONMEM run, they will be combined into a single data.frame.

Usage

read_table_nm(
  file = NULL,
  skip = NULL,
  header = NULL,
  rm_duplicates = FALSE,
  nonmem_tab = TRUE
)

Arguments

Value

A data.frame

Examples

## Not run: 
data <- read_table_nm(file = '../models/pk/sdtab101')

## End(Not run)

Replace list elements by name

Description

Replace list elements by name

Usage

replace_list_elements(list, replacement)

Arguments

Details

Finds and replaces list elements by name and throws an error if an element is not available in the original list. This is a local duplicate of the PKPDmisc copy for the VPC package to reduce dependency on PKPDmisc at this time.

Examples

## Not run: 
list <- list(ipred = "ipred", dv = "dv", idv = "idv", "pred" = "pred")
replacement <- list(dv = "conc", idv = "time")
list <- replace_list_elements(list, replacement)

## End(Not run)

Simulated RTTE data (1x)

Description

An example dataset with simulated repeated time-to-event data

Usage

rtte_obs_nm

Format

An object of class data.frame with 573 rows and 6 columns.

Simulated RTTE data (100x)

Description

An example dataset with simulated repeated time-to-event data (100 simulations)

Usage

rtte_sim_nm

Format

An object of class data.frame with 2000000 rows and 7 columns.

Defaults for show argument

Description

Defaults for show argument

Usage

show_default

Format

An object of class list of length 11.

Defaults for show argument for TTE VPC

Description

Defaults for show argument for TTE VPC

Usage

show_default_tte

Format

An object of class list of length 11.

Simulate data based on a model and parameter distributions

Description

Simulate data based on a model and parameter distributions

Usage

sim_data(
  design = cbind(id = c(1, 1, 1), idv = c(0, 1, 2)),
  model = function(x) {     return(x$alpha + x$beta) },
  theta,
  omega_mat,
  par_names,
  par_values = NULL,
  draw_iiv = "mvrnorm",
  error = list(proportional = 0, additive = 0, exponential = 0),
  n = 100
)

Arguments

Details

This function generates the simulated dependent values for use in the VPC plotting function.

Value

a vector of simulated dependent variables (for us in the VPC plotting function)

See Also

vpc

A small rich dataset

Description

A small rich dataset

Usage

simple_data

Format

An object of class list of length 2.

Details

a list containing the obs and sim data for an example dataset to run a simple vpc.

Examples

## Not run: 
vpc(simple_data$sim, simple_data$obs)

## End(Not run)

Empty ggplot2 theme

Description

Empty ggplot2 theme

Usage

theme_empty()

Examples

vpc(simple_data$sim, simple_data$obs) + theme_empty()

A nicer default theme for ggplot2

Description

A nicer default theme for ggplot2

Usage

theme_plain()

Examples

vpc(simple_data$sim, simple_data$obs) + theme_plain()

Lower to full triangle

Description

Convert the lower triangle of a covariance matrix to a full matrix object

Usage

triangle_to_full(vect)

Arguments

VPC function

Description

Creates a VPC plot from observed and simulation data

Usage

vpc(sim, ...)

## Default S3 method:
vpc(sim, ...)

vpc_vpc(
  sim = NULL,
  obs = NULL,
  psn_folder = NULL,
  bins = "jenks",
  n_bins = "auto",
  bin_mid = "mean",
  obs_cols = NULL,
  sim_cols = NULL,
  software = "auto",
  show = NULL,
  stratify = NULL,
  pred_corr = FALSE,
  pred_corr_lower_bnd = 0,
  pi = c(0.05, 0.95),
  ci = c(0.05, 0.95),
  uloq = NULL,
  lloq = NULL,
  log_y = FALSE,
  log_y_min = 0.001,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  smooth = TRUE,
  vpc_theme = NULL,
  facet = "wrap",
  scales = "fixed",
  labeller = NULL,
  vpcdb = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Value

a list containing calculated VPC information (when vpcdb=TRUE), or a ggplot2 object (default)

See Also

sim_data, vpc_cens, vpc_tte, vpc_cat

Examples

## See vpc.ronkeizer.com for more documentation and examples
library(vpc)

# Basic commands:
vpc(sim = simple_data$sim, obs = simple_data$obs)
vpc(sim = simple_data$sim, obs = simple_data$obs, lloq = 20)

VPC function for categorical

Description

Creates a VPC plot from observed and simulation data for categorical variables.

Usage

vpc_cat(
  sim = NULL,
  obs = NULL,
  psn_folder = NULL,
  bins = "jenks",
  n_bins = "auto",
  bin_mid = "mean",
  obs_cols = NULL,
  sim_cols = NULL,
  software = "auto",
  show = NULL,
  ci = c(0.05, 0.95),
  uloq = NULL,
  lloq = NULL,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  smooth = TRUE,
  vpc_theme = NULL,
  facet = "wrap",
  labeller = NULL,
  plot = TRUE,
  vpcdb = FALSE,
  verbose = FALSE
)

Arguments

Value

a list containing calculated VPC information (when vpcdb=TRUE), or a ggplot2 object (default)

See Also

sim_data, vpc, vpc_tte, vpc_cens

Examples

## See vpc.ronkeizer.com for more documentation and examples
library(vpc)

# simple function to simulate categorical data for single individual
sim_id <- function(id = 1) {
  n <- 10
  logit <- function(x) exp(x) / (1+exp(x))
  data.frame(id = id, time = seq(1, n, length.out = n),
             dv = round(logit((1:n) - n/2 + rnorm(n, 0, 1.5))) )
}
## simple function to simulate categorical data for a trial
sim_trial <- function(i = 1, n = 20) { # function to simulate categorical data for a trial
  data.frame(sim = i, do.call("rbind", lapply(1:n, sim_id)))
}

## simulate single trial for 20 individuals
obs <- sim_trial(n = 20)

## simulate 200 trials of 20 individuals
sim <- do.call("rbind", lapply(1:200, sim_trial, n = 20))

## Plot categorical VPC
vpc_cat(sim = sim, obs = obs)

VPC function for left- or right-censored data (e.g. BLOQ data)

Description

Creates a VPC plot from observed and simulation data for censored data. Function can handle both left- (below lower limit of quantification) and right-censored (above upper limit of quantification) data.

Usage

vpc_cens(
  sim = NULL,
  obs = NULL,
  psn_folder = NULL,
  bins = "jenks",
  n_bins = 8,
  bin_mid = "mean",
  obs_cols = NULL,
  sim_cols = NULL,
  software = "auto",
  show = NULL,
  stratify = NULL,
  stratify_color = NULL,
  ci = c(0.05, 0.95),
  uloq = NULL,
  lloq = NULL,
  plot = FALSE,
  xlab = "Time",
  ylab = "Probability of <LOQ",
  title = NULL,
  smooth = TRUE,
  vpc_theme = NULL,
  facet = "wrap",
  labeller = NULL,
  vpcdb = FALSE,
  verbose = FALSE
)

Arguments

Value

a list containing calculated VPC information, and a ggplot2 object

See Also

sim_data, vpc, vpc_tte, vpc_cat

Examples

## See vpc.ronkeizer.com for more documentation and examples
library(vpc)

vpc_cens(sim = simple_data$sim, obs = simple_data$obs, lloq = 30)
vpc_cens(sim = simple_data$sim, obs = simple_data$obs, uloq = 120)

VPC function for time-to-event (survival) data

Description

This function can be used for either single time-to-event (TTE) or repeated time-to-event (RTTE) data.

Usage

vpc_tte(
  sim = NULL,
  obs = NULL,
  psn_folder = NULL,
  rtte = FALSE,
  rtte_calc_diff = TRUE,
  rtte_conditional = TRUE,
  events = NULL,
  bins = FALSE,
  n_bins = 10,
  software = "auto",
  obs_cols = NULL,
  sim_cols = NULL,
  kmmc = NULL,
  reverse_prob = FALSE,
  stratify = NULL,
  stratify_color = NULL,
  ci = c(0.05, 0.95),
  plot = FALSE,
  xlab = "Time",
  ylab = "Survival (%)",
  show = NULL,
  as_percentage = TRUE,
  title = NULL,
  smooth = FALSE,
  vpc_theme = NULL,
  facet = "wrap",
  labeller = NULL,
  verbose = FALSE,
  vpcdb = FALSE
)

Arguments

Details

Creates a VPC plot from observed and simulation survival data

Value

a list containing calculated VPC information, and a ggplot2 object

See Also

sim_data, vpc, vpc_tte, vpc_cens

Examples

## See vpc-docs.ronkeizer.com for more documentation and examples.

## Example for repeated) time-to-event data
## with NONMEM-like data (e.g. simulated using a dense grid)

data(rtte_obs_nm)
data(rtte_sim_nm)

# treat RTTE as TTE, no stratification
vpc_tte(sim = rtte_sim_nm[rtte_sim_nm$sim <= 20,],
       obs = rtte_obs_nm,
       rtte = FALSE,
       sim_cols=list(dv = "dv", idv = "t"), obs_cols=list(idv = "t"))