#' ---
#' title: "Supplementing and enhancing rpact's graphical capabilities with ggplot2"
#' author: "Yannic Schmidt, Stefan Englert, Martina Kron, Gernot Wassmer, and Friedrich Pahlke"
#' date: "`r format(Sys.time(), '%d %B, %Y')`"
#' number: 12
#' header-includes:
#' - \usepackage{fancyhdr}
#' - \pagestyle{fancy}
#' - \setlength{\headheight}{23pt}
#' - \fancyfoot[C]{www.rpact.com}
#' - \fancyfoot[L]{\thepage}
#' output:
#' rmarkdown::html_document:
#' highlight: pygments
#' number_sections: yes
#' self_contained: yes
#' toc: yes
#' toc_depth: 3
#' toc_float: yes
#' css: style.css
#' includes:
#' before_body: header.html
#' after_body: footer.html
#' vignette: >
#' \usepackage[utf8]{inputenc}
#' %\VignetteIndexEntry{Supplementing and enhancing rpact's graphical capabilities with ggplot2}
#' %\VignetteEngine{knitr::rmarkdown}
#' ---
#'
## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(echo = TRUE)
options(scipen=999)
#'
#'
#'
#' # Summary {-}
#'
#' The aim of this [R Markdown](https://rmarkdown.rstudio.com) document is to give a brief description on **how easy it is to supplement and enhance plots** generated in [rpact](https://cran.r-project.org/package=rpact) by use of the [ggplot2](https://ggplot2.tidyverse.org) package and associated language.
#'
#' # Introduction
#'
#' We will illustrate the generation of the plots by assessing the simulated Type I error rate of a group-sequential and adaptive inverse-normal design in a sample size recalculation setting. It is well known that the adaptive inverse-normal designs in contrast to group-sequential designs controls the overall Type I error rate even in a setting of sample size recalculation. The goal of this exercise is to present this fact in a single comprehensive output.
#'
#' With *rpact* it is very convenient to calculate the necessary components: We will analyze both design choices by *rpact*, retrieve the results and arrange them by the means of *ggplot2*.
#'
#' Throughout this document, we will use the default parameter settings from *rpact* which assume a one-sided significance level of 0.025.
#'
#' **Loading the packages**
#'
#' We start by loading the required two packages.
## ----load---------------------------------------------------------------------
library(rpact)
packageVersion("rpact")
library(ggplot2)
#'
#' # Initialize the group-sequential and adaptive inverse-normal design
#'
#' After the two packages were loaded, the group-sequential (dGS) and adaptive inverse-normal (dIN) design can be generated.
## -----------------------------------------------------------------------------
dGS <- getDesignGroupSequential()
dIN <- getDesignInverseNormal()
#'
#' We can now take a look into both designs and inspect their default values.
#'
#'
## -----------------------------------------------------------------------------
dGS
dIN
#'
#' In the output we see some important characteristics like the type of design (OF=O'Brien and Fleming), the maximum number of stages (3), the information rates (0.333, 0.667, 1.000), the significance level (0.025) and the stage level information (0.0002592, 0.0070554, 0.0225331).
#'
#' We can also easily plot the stage level information by means of *rpact*.
#'
## -----------------------------------------------------------------------------
plot(dGS, type = 3)
plot(dIN, type = 3)
#'
#' With these commands, *rpact* creates two plots that show the three stage levels (0.0025, 0.0070554, 0.0225331) visually together with the corresponding information rates (0.333, 0.667, 1.000) and the significance level (0.025, dashed line).
#'
#' # Modification of the rpact base plots with ggplot2 (aesthetic) commands
#'
#' We note that the two prior plots are identical. This is expected as the same boundary type (O'Brien and Fleming) was used for both designs. So, we might want to restrict ourselves to present only one stage level plot. Instead, we can include this information in a custom title. This is achieved by combining the *rpact* "base" plot with *ggplot2* aesthetics commands as follows:
#'
## -----------------------------------------------------------------------------
plot(dGS, type = 3) +
ggtitle("Stage level plot of the adaptive and group-sequential design")
#'
#' All *ggplot2* aesthetic commands which modify an existing plot are initiated by a plus sign "+". Thereafter, we can add the particular command in the *ggplot2* language to specify how we want to modify the plot. Luckily, almost all *rpact* graphics are compatible with *ggplot2*.
#'
#' Modifications are not restriction to additions to existing plots, as demonstrated by adding a new title, but they can also re-model the initial plot. For example, we can change the limits of the x- and y-axis post-hoc.
#'
## -----------------------------------------------------------------------------
plot(dGS, type = 3) + xlim(0, 1) + ylim(0, dGS$alpha + 0.005)
#'
#' Or do both:
## -----------------------------------------------------------------------------
plot(dGS, type = 3) +
ggtitle("Stage level plot of the adaptive- and groupsequential design") +
xlim(0, 1) + ylim(0, dGS$alpha + 0.005)
#'
#' To make the plot more self-explanatory, we might want to further add
#'
#' * a visual highlight for the significance level of a single stage design by using the `geom_point` and `annotate` commands
#' * a better visual illustration of the local stage levels by adding horizontal reference lines by usign `geom_hline` commands
#' * color to the three different stages in the plot by using the aesthetic command `geom_point`
#' * the numerical values of the stage levels to plot by using appropriate `annotate` commands
#'
## -----------------------------------------------------------------------------
plot(dGS, type = 3) +
ggtitle("Stage level plot of the adaptive- and groupsequential design") +
xlim(0, 1) + ylim(0, dGS$alpha + 0.005) +
geom_point(aes(x = 1, y = dGS$alpha), colour = "red", size = 3) +
annotate(geom = "text", label = "Final significance level of single-stage design",
color = "red", x = dGS$informationRates[3], y = dGS$alpha, vjust = -2, hjust = 1) +
geom_hline(yintercept = dGS$stageLevels,linetype = "dashed", color = "grey") +
geom_point(aes_(x = dGS$informationRates[1], y = dGS$stageLevels[1]),
color = "blue", size = 3) +
geom_point(aes_(x = dGS$informationRates[2], y = dGS$stageLevels[2]),
color = "green", size = 3) +
annotate(geom = "text", label = round(dGS$stageLevels[1],5),
x = dGS$informationRates[1], y = dGS$stageLevels[1], vjust = -2) +
annotate(geom = "text", label = round(dGS$stageLevels[2],5),
x = dGS$informationRates[2], y = dGS$stageLevels[2], vjust = -2) +
annotate(geom = "text", label = round(dGS$stageLevels[3],5),
x = dGS$informationRates[3], y = dGS$stageLevels[3], vjust = 3)
#'
#' Note that the commands pull the required information directly from the design object and thus would automatically adjust to design changes like, for example, a switch to Pocock boundaries.
#'
#' # Illustrating Type I error control of adaptive designs with rpact and ggplot2
#'
#' In the last part of this document we investigate the Type I error rate of the chosen group sequential and adaptive inverse normal design in a sample size recalculation setting and present the simulation results visual in the plot.
#'
#' ## Simmulating the Type I error rate
#'
#' Using `getSimulationMeans()` we can easily simulate the operating characteristics of designs. To simulate the Type I error rate, we specify the null hypothesis as an alternative hypothesis with zero therapy effect (`alternative = 0`). The simulated overall rejection rate of the designs then corresponds to the Type I error rate.
#'
#' We assume a scenario with two interim analyses after 20 and 40 subjects and a final analysis after 60 subjects. We allow for a recalculation of the sample size for the next stage based on a conditional power of 80%. The recalculated sample size per stage is limited to be between 20 and 80. We perform a total of 100'000 simulations to get sufficient precision for the simulated Type I error rate. The seed = 12345 ensures that the simulated values are reproduced, e.g., for documentary purposes.
#'
#'
## -----------------------------------------------------------------------------
nsim <- 100000
seed <- 12345
dGSsim <- getSimulationMeans(dGS,
plannedSubjects = c(20,40,60),
conditionalPower = 0.8, alternative = 0,
minNumberOfSubjectsPerStage = c(20,20,20),
maxNumberOfSubjectsPerStage = c(20,80,80),
maxNumberOfIterations = nsim,
seed = 12345)
dGSsim
dINsim <- getSimulationMeans(dIN,
plannedSubjects = c(20,40,60),
conditionalPower = 0.8, alternative = 0,
minNumberOfSubjectsPerStage = c(20,20,20),
maxNumberOfSubjectsPerStage = c(20,80,80),
maxNumberOfIterations = nsim,
seed = 12345)
dINsim
#'
#' ## Extraction of the simulated Type I error rate of both designs
#'
#' Note that we can easily extract the simulated Type I error rate or overall rejection rates under the null hypothesis. This value is stored in the `overallReject` parameter of the simulation outputs.
#'
## -----------------------------------------------------------------------------
dGSalpha <- dGSsim$overallReject
dGSalpha
dINalpha <- dINsim$overallReject
dINalpha
#'
#' The results of the simulation show that, in a setting of sample size recalculation, the group-sequential design does not control the nominal significance level. The overall rejection rate of the group-sequential design (`r dGSalpha`) is bigger than the significance level (`r dGS$alpha`). The inverse normal design controls the Type I error rate as the overall rejection rate (`r dINalpha`) is close to the significance level of `r dIN$alpha`.
#'
#' ## Final Plot
#'
#' In the final plot of this example, we try to present the core learning of the previous section in a single overarching plot. The final plot should be *management ready*, meaning include all relevant information, be visually appealing and self-explanatory. The intention of the plot is to transfer the information that a group sequential design and adaptive inverse normal design with same parameters will feature the same stage levels at the corresponding information rates, the same overall significance level, but different overall rejection rates in a setting of sample size recalculation.
#'
#' For the final plot, we start with all (plot and aesthetic) commands, which we used in the chapter *Modification of the rpact base chart with ggplot2 (aesthetic) commands*. Additional information from the simulation results was subsequently added in.
#'
## -----------------------------------------------------------------------------
# create base ggplot object
g <- plot(dGS, type = 3)
# modify the rpact base plot as described above
g <- g + ggtitle("Stage level plot of the adaptive- and groupsequential design") +
xlim(0, 1) + ylim(0, dGS$alpha + 0.005) +
geom_point(aes(x = 1, y = dGS$alpha), colour = "red", size = 3) +
annotate(geom = "text", label = "Final significance level of single-stage design",
color = "red", x = dGS$informationRates[3], y = dGS$alpha, vjust = -2, hjust = 1) +
geom_hline(yintercept = dGS$stageLevels,linetype = "dashed", color = "grey") +
geom_point(aes_(x = dGS$informationRates[1], y = dGS$stageLevels[1]),
color = "blue", size = 3) +
geom_point(aes_(x = dGS$informationRates[2], y = dGS$stageLevels[2]),
color = "green", size = 3)
# add additional annotations
g <- g + annotate(geom = "text", label = round(dGS$stageLevels[1],5),
x = dGS$informationRates[1], y = dGS$stageLevels[1], vjust = -2) +
annotate(geom = "text", label = round(dGS$stageLevels[2],5),
x = dGS$informationRates[2], y = dGS$stageLevels[2], vjust = -2) +
annotate(geom = "text", label = round(dGS$stageLevels[3],5),
x = dGS$informationRates[3], y = dGS$stageLevels[3], vjust = 3) +
annotate("text", x = 0.55, y = 0.016, label =
paste("Group-sequential design:", dGSalpha), hjust = 1) +
annotate("text", x = 0.55, y = 0.014, label =
paste("Adaptive inverse-normal design:", dINalpha), hjust = 1) +
annotate("text", x = 0.05, y = 0.010, label =
paste("Based on", nsim, "simulations."), hjust = 0) +
annotate("text", x = 0.05, y = 0.020, label =
"Simulated overall Type I error rate with sample size recalculation:", hjust = 0)
# generate and show plot
g
#'
#' # Summary
#'
#' It was shown that *rpact* "base" charts can be modified with standard *ggplot2* commands. The implementation is very easy and intuitive as it follows the normal *ggplot2* syntax. The authors hope that this information is helpful for everyone who wants to further modify graphical outputs from *rpact*.
#'
#' # References
#'
#' 1. Gernot Wassmer and Werner Brannath, *Group Sequential and Confirmatory Adaptive Designs in Clinical Trials*, Springer 2016, ISBN 978-3319325606
#'
#' 2. R-Studio, *Data Visualization with ggplot2 - Cheat Sheet*, version 2.1, 2016, https://www.rstudio.com/wp-content/uploads/2016/11/ggplot2-cheatsheet-2.1.pdf
#'
#' # Disclaimer
#'
#' Yannic Schmidt, Stefan Englert and Martina Kron are employees of AbbVie Inc.
#' Gernot Wassmer and Friedrich Pahlke are employees of RPACT (R Programming for
#' Adaptive Clinical Trials). All opinions and information in this presentation are
#' from the authors and do not necessarily reflect the views of their employers.
#'
#' ***
#'
#' System: rpact `r packageVersion("rpact")`, `r R.version.string`, platform: `r R.version$platform`
#'
## ---- include=TRUE, echo=FALSE, results='asis'--------------------------------
printCitation()
#'