#' ---
#' title: "Designing group-sequential trials with two groups and a continuous endpoint with rpact"
#' author: "Dietmar Volz, Marcel Wolbers, Gernot Wassmer, and Friedrich Pahlke"
#' date: "Last change: `r format(Sys.time(), '%d %B, %Y')`"
#' number: 2
#' 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: footer3.html
#' ---
#'
#'
#'
#' # Summary {-}
#'
#' This [R Markdown](https://rmarkdown.rstudio.com) document provides examples for
#' designing trials with continuous endpoints using [rpact](https://cran.r-project.org/package=rpact).
#'
#' # Introduction
#'
#' These examples are not intended to replace the official
#' rpact documentation and help pages but rather to supplement them. They also only
#' cover a selection of all rpact features.
#'
#' General convention: In rpact, arguments containing the **index "2"** always refer
#' to the **control group**, **"1"** refer to the **intervention group**, and
#' **treatment effects compare treatment versus control**.
#'
#' **First, load the rpact package**
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
library(rpact)
packageVersion("rpact") # version should be version 2.0.5 or later
#'
#' # Sample size calculation for a superiority trial without interim analyses
#' The **sample size** for a trial with continuous endpoints can be calculated
#' using the function `getSampleSizeMeans()`. This function is fully documented in
#' the relevant help page (`?getSampleSizeMeans`). Some examples are provided
#' below.
#'
#' `getSampleSizeMeans()` requires that the mean difference between the two arms is
#' larger under the alternative than under the null hypothesis. For superiority
#' trials, this implies that **rpact requires that the targeted mean difference is
#' >0 under the alternative hypothesis**. If this is not the case, the function
#' produces an error message. To circumvent this and power for a negative mean
#' difference, **one can simply switch the two arms** (leading to a positive mean
#' difference) as the situation is perfectly symmetric.
#'
#' By default, `getSampleSizeMeans()` tests hypotheses about the mean
#' difference. rpact also supports testing hypotheses about mean ratios if the
#' argument `meanRatio` is set to `TRUE` but this will not be discussed further in
#' this document.
#'
#' By default, rpact uses sample size formulas for the $t$-test, i.e., it
#' assumes that the standard deviation in the two groups is equal but unknown and
#' estimated from the data. If sample size calculations for the $z$-test are
#' desired, one can set the argument `normalApproximation` to `TRUE` but this is
#' usually not recommended.
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Example of a standard trial:
# - targeted mean difference is 10 (alternative = 10)
# - standard deviation in both arms is assumed to be 24 (stDev = 24)
# - two-sided test (sided = 2), Type I error 0.05 (alpha = 0.05) and power 80%
# - (beta = 0.2)
sampleSizeResult <- getSampleSizeMeans(alternative = 10, stDev = 24, sided = 2,
alpha = 0.05, beta = 0.2)
sampleSizeResult
#'
#' The generic `summary()` function produces the output
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
summary(sampleSizeResult)
#'
#' As per the output above, the required **total sample size** for the trial is
#' `r ceiling(sampleSizeResult$nFixed)` and the critical value corresponds to a
#' minimal detectable mean difference of approximately
#' `r formatC(sampleSizeResult$criticalValuesEffectScaleUpper,format = "f",digits = 2)`.
#'
#' Unequal randomization between the treatment groups can be defind with
#' `allocationRatioPlanned`, for example,
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Extension of standard trial:
# - 2(intervention):1(control) randomization (allocationRatioPlanned = 2)
summary(getSampleSizeMeans(alternative = 10, stDev = 24,
allocationRatioPlanned = 2, sided = 2, alpha = 0.05, beta = 0.2))
#'
#' **Power** for a given sample size can be calculated using the function
#' `getPowerMeans()` which has the same arguments as `getSampleSizeMeans()` except
#' that the maximum total sample is given (`maxNumberOfSubjects`) instead of the
#' Type II error (`beta`).
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Calculate power for the 2:1 rendomized trial with total sample size 206
# (as above) assuming a larger difference of 12
powerResult <- getPowerMeans(alternative = 12, stDev = 24, sided = 2,
allocationRatioPlanned = 2, maxNumberOfSubjects = 206, alpha = 0.05)
powerResult
#'
#' The calculated **power** is provided in the output as **"Overall reject"** and is
#' `r formatC(powerResult$overallReject,format = "f",digits = 2)` for the example `alternative = 12`.
#'
#' The `summary()` function produces
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
summary(powerResult)
#'
#' `getPowerMeans()` (as well as `getSampleSizeMeans()`) can also be called with a
#' vector argument for the mean difference under the alternative H1
#' (`alternative`). This is illustrated below via a plot of power depending on
#' these values. For examples of all available plots, see the R Markdown document [How
#' to create admirable plots with
#' rpact](https://vignettes.rpact.org/html/rpact_plot_examples.html).
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Example: Calculate power for design with sample size 206 as above
# alternative values ranging from 5 to 15
powerResult <- getPowerMeans(alternative = 5:15, stDev = 24, sided = 2,
allocationRatioPlanned = 2, maxNumberOfSubjects = 206, alpha = 0.05)
plot(powerResult,type = 7) # one of several possible plots
#'
#' # Sample size calculation for a non-inferiority trial without interim analyses
#' The sample size calculation proceeds in the same fashion as for superiority trials
#' except that the role of the null and the alternative hypothesis are reversed and
#' the test is always one-sided. In this case, the non-inferiority margin $\Delta$
#' corresponds to the treatment effect under the null hypothesis (`thetaH0`) which
#' one aims to reject.
#'
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Example: Non-inferiority trial with margin delta = 10, standard deviation = 14
# - One-sided alpha = 0.05, 1:1 randomization
# - H0: treatment difference <= -12 (i.e., = -12 for calculations, thetaH0 = -1)
# vs. alternative H1: treatment difference = 0 (alternative = 0)
sampleSizeNoninf <- getSampleSizeMeans(thetaH0 = -12,alternative = 0,
stDev = 14,alpha = 0.025,beta = 0.2,sided = 1)
sampleSizeNoninf
#'
#' # Sample size calculation for group-sequential designs
#' Sample size calculation for a group-sequential trials is performed in **two steps**:
#'
#' 1. **Define the (abstract) group-sequential design** using the function
#' `getDesignGroupSequential()`. For details regarding this step, see the R
#' markdown file "Defining group-sequential boundaries with rpact".
#' 2. **Calculate sample size** for the continuous endpoint by feeding the abstract
#' design into the function `getSampleSizeMeans()`.
#'
#' In general, rpact supports both one-sided and two-sided group-sequential
#' designs. However, if futility boundaries are specified, only one-sided tests are
#' permitted. **For simplicity, it is often preferred to use one-sided tests for
#' group-sequential designs** (typically, with $\alpha = 0.025$).
#'
#' R code for a simple example is provided below:
## ---- include = TRUE, echo = TRUE---------------------------------------------
# Example: Group-sequential design with O'Brien & Fleming type alpha-spending
# and one interim at 60% information
design <- getDesignGroupSequential(sided = 1, alpha = 0.025, beta = 0.2,
informationRates = c(0.6,1), typeOfDesign = "asOF")
# Trial assumes an effect size of 10 as above, a stDev = 24, and an allocation
# ratio of 2
sampleSizeResultGS <- getSampleSizeMeans(
design, alternative = 10, stDev = 24, allocationRatioPlanned = 2)
# Standard rpact output (sample size object only, not design object)
sampleSizeResultGS
# Summary rpact output for sample size object
summary(sampleSizeResultGS)
#'
#' ***
#'
#' System: rpact `r packageVersion("rpact")`, `r R.version.string`, platform: `r R.version$platform`
#'
## ---- include = TRUE, echo = FALSE, results = 'asis'--------------------------
printCitation()