plot_blrm {OncoBayes2}

Plot a fitted model

Description

Warning: these methods are at an experimental stage of development, and may change with future releases.

Plotting methods for blrmfit and blrm_trial objects.

Usage

plot_toxicity_curve(object, ...)

plot_toxicity_intervals(object, ...)

plot_toxicity_intervals_stacked(object, ...)

## S3 method for class 'blrmfit'
plot_toxicity_curve(
  object,
  newdata,
  x,
  group,
  xlim,
  ylim,
  transform = TRUE,
  prob = 0.5,
  prob_outer = 0.95,
  size = 0.75,
  alpha = 1,
  facet_args = list(),
  hline_at = c(0.16, 0.33),
  grid_length = 100,
  ...
)

## S3 method for class 'blrm_trial'
plot_toxicity_curve(
  object,
  newdata,
  x,
  group,
  xlim,
  ylim,
  transform = TRUE,
  prob = 0.5,
  prob_outer = 0.95,
  size = 0.75,
  alpha = 1,
  facet_args = list(),
  hline_at,
  grid_length = 100,
  ewoc_shading = TRUE,
  ...
)

## S3 method for class 'blrmfit'
plot_toxicity_intervals(
  object,
  newdata,
  x,
  group,
  interval_prob = c(0, 0.16, 0.33, 1),
  interval_max_mass = c(NA, NA, 0.25),
  ewoc_colors = c("green", "red"),
  ...
)

## S3 method for class 'blrm_trial'
plot_toxicity_intervals(
  object,
  newdata,
  x,
  group,
  interval_prob,
  interval_max_mass,
  ewoc_colors = c("green", "red"),
  ...
)

## S3 method for class 'blrmfit'
plot_toxicity_intervals_stacked(
  object,
  newdata,
  x,
  group,
  xlim,
  ylim = c(0, 0.5),
  predictive = FALSE,
  transform = !predictive,
  interval_prob,
  grid_length = 100,
  facet_args = list(),
  ...
)

## S3 method for class 'blrm_trial'
plot_toxicity_intervals_stacked(
  object,
  newdata,
  x,
  group,
  xlim,
  ylim = c(0, 0.5),
  predictive = FALSE,
  transform = !predictive,
  interval_prob,
  grid_length = 100,
  ewoc_shading = TRUE,
  facet_args = list(),
  ...
)

Arguments

object

fitted model object

...

currently unused

newdata

optional data frame specifying for what to predict; if missing, then the data of the input model object is used. If object is a blrmfit object, newdata defaults to the data argument. If object is a blrm_trial, it defaults to summary(object, "dose_info").

x

Character giving the parameter name to be mapped to the x-axis. This also supports 'tidy' parameter selection by specifying x = vars(...), where ... is specified the same way as in dplyr::select() and similar functions. Examples of using x in this way can be found in the examples. For blrm_trial methods, it defaults to the first entry in summary(blrm_trial, "drug_info")$drug_name.

group

Grouping variable(s) whose levels will be mapped to different facets of the plot. group can be a character vector, tidy parameter(s) of the form group = vars(...), or a formula to be passed directly to ggplot2::facet_wrap(). For blrm_trial methods, it defaults to group_id, plus all entries of summary(blrm_trial, "drug_info")$drug_name except the first, which is mapped to x.

xlim

x-axis limits

ylim

y-axis limits on the probability scale

transform

logical (defaults to FALSE) indicating if the linear predictor on the logit link scale is transformed with inv_logit to the 0-1 response scale.

prob

central probability mass to report for the inner ribbon, i.e. the quantiles 0.5-prob/2 and 0.5+prob/2 are displayed.

prob_outer

central probability mass to report for the outer ribbon, i.e. the quantiles 0.5-prob/2 and 0.5+prob/2 are displayed.

alpha, size

Arguments passed to geoms. For this plot, alpha is passed to ggplot2::geom_ribbon(), and size is passed to ggplot2::geom_line().

facet_args

A named list of arguments (other than 'facets') passed to ggplot2::facet_wrap().

hline_at

Location(s) of horizontal guide lines (passed to bayesplot::hline_at()).

grid_length

Number of grid points within xlim for plotting.

ewoc_shading

logical indicates if doses violating EWOC should be shaded in gray. Applies only to blrm_trial methods. Defaults to TRUE.

interval_prob

defines the interval probabilities reported in the standard outputs. Defaults to c(0, 0.16, 0.33, 1), when predictive = FALSE and/or transform = TRUE, or to intervals giving 0, 1, or 2+ DLTs when predictive = TRUE and transform = FALSE. For blrm_trial methods, this is taken from summary(blrm_trial, "interval_prob") by default.

interval_max_mass

vector defining for each interval of the interval_prob vector a maximal admissible probability mass for a given dose level. Whenever the posterior probability mass in a given interval exceeds the threshold, then the Escalation With Overdose Control (EWOC) criterion is considered to be not fulfilled. Dose levels not fulfilling EWOC are ineligible for the next cohort of patients. The default restricts the overdose probability to less than 0.25. For blrm_trial methods, this is taken from summary(blrm_trial, "interval_max_mass") by default.

ewoc_colors

Fill colors used for bars indicating EWOC OK or not. Vector of two characters, each of which must correspond to bayesplot-package color schemes (see ?bayesplot::color_scheme_get())

predictive

logical indicates if the posterior predictive is being summarized. Defaults to FALSE.

Details

plot_toxicity_curve plots continuous profiles of the dose-toxicity curve.

plot_toxicity_intervals plots the posterior probability mass in subintervals of [0,1], at a discrete set of provisional doses.

plot_toxicity_intervals_stacked is similar to plot_toxicity_intervals, but over a continuous range of doses.

Value

A ggplot object that can be further customized using the ggplot2 package.

Examples

## Setting up dummy sampling for fast execution of example
## Please use 4 chains and 100x more warmup & iter in practice
.user_mc_options <- options(OncoBayes2.MC.warmup=10, OncoBayes2.MC.iter=20, OncoBayes2.MC.chains=1,
                            OncoBayes2.MC.save_warmup=FALSE)


example_model("combo2", silent=TRUE)

# Plot the dose-toxicity curve
plot_toxicity_curve(blrmfit,
                    x = "drug_A",
                    group = ~ group_id * drug_B,
                    newdata = subset(dose_info_combo2, group_id == "trial_AB"),
                    facet_args = list(ncol = 4))

# Plot posterior DLT-rate-interval probabilities at discrete dose levels
plot_toxicity_intervals(blrmfit,
                        x = "drug_A",
                        group = ~ group_id * drug_B,
                        newdata = subset(dose_info_combo2, group_id == "trial_AB"))

# Plot posterior DLT-rate-interval probabilities over continuous dose
plot_toxicity_intervals_stacked(blrmfit,
                                x = "drug_A",
                                group = ~ group_id * drug_B,
                                newdata = subset(dose_info_combo2, group_id == "trial_AB"))

# Plot predictive distribution probabilities over continuous dose
plot_toxicity_intervals_stacked(blrmfit,
                                x = "drug_A",
                                group = ~ group_id * drug_B,
                                predictive = TRUE,
                                interval_prob = c(-1, 0, 1, 6),
                                newdata = transform(subset(dose_info_combo2,
                                                           group_id == "trial_AB"),
                                                    num_patients = 6,
                                                    num_toxicities = 0))
## Recover user set sampling defaults
options(.user_mc_options)