toxFigures {ProAE}

Create PRO-CTCAE severity frequency distribution figures for individual survey items and composite scores

Description

Data format should be in 'long' format, where each PRO-CTCAE item is a variable/column.

Usage

toxFigures(
  dsn,
  id_var,
  cycle_var,
  baseline_val,
  arm_var = NA,
  plot_limit = NA,
  colors = 1,
  bar_label = 0,
  cycle_label = FALSE,
  cycle_vals = NA,
  cycle_labs = NA,
  summary_only = FALSE,
  summary_highlight = FALSE,
  cycles_only = TRUE,
  x_lab_angle = 0,
  x_lab_vjust = 1,
  x_lab_hjust = 0,
  x_label = "Randomized Treatment Assignment",
  y_label = "Percent of Total Frequency",
  footnote_break = FALSE,
  suppress_legend = FALSE,
  add_item_title = FALSE
)

Arguments

dsn

A data.frame object with PRO-CTCAE data

id_var

A character string.Name of ID variable differentiating each PRO-CTCAE survey/participant entered as a quoted string.

cycle_var

A character string. Name of variable differentiating one longitudinal/repeated PRO-CTCAE survey from another, within an individual ID.

baseline_val

A number indicating the expected baseline cycle/time point.

arm_var

A character string. Name of arm variable differentiating treatment groups. Must be character or factor class. Overall AUC will be reported if no arm/grouping variable is provided. Defaults to NA.

plot_limit

A number. Limit the number of cycles to be plotted up to and including a given cycle number. All available cycle time points are plotted if no cycle number is provided. Defaults to NA.

colors

A number. Specify the coloring scheme of symptom scores within frequency bars. Options include: 1 = Blue and red color shading, 2 = qualitative color shades (color blind friendly), 3 = black and white. Defaults to 1.

bar_label

A number. Label frequency bars with sample size (n) or percent shown on the y-axis. Label options include: 1 = sample size (n) within each cycle (symptom score 0 or higher), 2 = sample size (n) within each cycle with present symptoms (symptom score > 0), 3 = sample size (n) within each cycle with severe symptoms (symptom score >= 3), 4 = percent of subjects within each cycle with present symptoms (symptom score > 0), 5 = percent of subjects within each cycle with severe symptoms (symptom score >= 3). No labels will be applied if not specified. Defaults to NA.

cycle_label

Logical. Assign custom labels to cycles/time point. If TRUE, the cycle_vals and cycle_labs must also be specified.

cycle_vals

Numeric column vector. Vector of values seen within the cycle_var variable. Must be same length of cycle_labs. Defaults to NA.

cycle_labs

Character column vector. Vector of labels to be mapped to the associated cycle_vals. Must be same length of cycle_vals. Defaults to NA.

summary_only

Logical. Only display the summary measures in figures / Suppress the individual time points from plotting. Defaults to FALSE.

summary_highlight

Logical. Add black box around summary measure bar chart. Defaults to FALSE.

cycles_only

Logical. Only display the longitudinal time points in figures / Suppress the summary measures from plotting. Defaults to TRUE.

x_lab_angle

A integer between 0 and 360. Allows the user to rotate the x axis labels in order to fit long arm names (0 or 45 recommended). Defaults to 0.

x_lab_vjust

A number. A ggplot2 object option. Allows the user to vertically adjusts the x axis labels in order to fit arm names. Defaults to 1.

x_lab_hjust

A number. A ggplot2 object option. Allows the user to horizontally adjusts the x axis labels in order to fit arm names. Defaults to 0.

x_label

A character string. Label for the x axis of the plot. Defaults to "Randomized Treatment Assignment" if arm_var is specified, defaults to "Overall" if not arm_var is specified.

y_label

A character string. Label for the y axis of the plot. Defaults to "Percent of Total Frequency".

footnote_break

Logical. Add a line break to the footnote Defaults to FALSE.

suppress_legend

Logical. Suppress the legend from appearing in figure. Defaults to FALSE.

add_item_title

Logical. Add the symptom item name as a title to the figure. Defaults to FALSE.

Value

A list object. The returned object is a (k X 2) or (k x 3) nested list. Where k is the number of PRO-CTCAE item groups (e.g. pain, fatigue, nausea); list[[1 ... i ... k]]. For each list item there are 2 or 3 elements. The 1st element of each list item is the name of the PRO-CTCAE item group returned as a string. The 2nd element is the PRO-CTCAE figure as a ggplot object. These objects can be modified as such.

Examples

## Not run: 
fig_acute = toxFigures(dsn = ProAE::tox_acute,
 cycle_var = "Cycle",
 baseline_val = 1,
 arm_var = "arm",
 id_var = "id",
 x_lab_angle = -45,
 x_lab_vjust =  .3,
 x_lab_hjust = .2,
 colors = 2)
fig_acute[[1]]

## End(Not run)