#' ---
#' 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
#' ---
#'
#'
#'
#'
#' This R markdown file provides examples for designing trials with continuous endpoints using rpact. 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.
#'
#' # Load rpact package.
## ---- include=TRUE, echo=TRUE--------------------------------------------
# Load rpact
library(rpact)
packageVersion("rpact") # version should be version 2.0.1 or later
#'
#' # Sample size calculation for a superiority trial without interim analyses
#' **Sample size** for a trial with continuous endpoints can be calculated using the function `getSampleSizeMeans`. This function is fully document 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 gives an error. 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
#' 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)
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, allocationRatioPlanned=2,
maxNumberOfSubjects = 206, sided=2, 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`.
#'
#' `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 file [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, allocationRatioPlanned=2,
maxNumberOfSubjects = 206, sided=2, alpha=0.05)
plot(powerResult,type=7) # one of several possible plots
#'
#' # Sample size calculation for a non-inferiority trial without interim analyses
#' 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
# - Test 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-sequntial 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
#'
#'
#' ***
#'
#' System: rpact `r packageVersion("rpact")`, `r R.version.string`, platform: `r R.version$platform`
#'
## ---- include=TRUE, echo=FALSE, results='asis'---------------------------
print(citation("rpact"), bibtex = FALSE)