--- title: "Visualize Simon\\'s Two-Stage Phase II Design" author: Tingting Zhan format: html: page-layout: full html-math-method: katex toc: true toc-location: left toc-depth: 4 toc-title: '' editor: visual vignette: > %\VignetteIndexEntry{intro} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8} --- # Introduction This vignette of package **`VisualizeSimon2Stage`** ([CRAN](https://cran.r-project.org/package=VisualizeSimon2Stage), [Github](https://github.com/tingtingzhan/VisualizeSimon2Stage), [RPubs](https://rpubs.com/tingtingzhan/VisualizeSimon2Stage)) documents the visualization of probabilities and operating characteristics of Simon's two-stage Phase II design. ## Note to Users Examples in this vignette require that the `search` path has ```{r} #| message: false library(VisualizeSimon2Stage) library(clinfun) library(flextable) library(ggplot2) ``` ```{r} #| echo: false library(knitr) # for tables in this vignette #options(mc.cores = 1L) # for CRAN submission ``` ## Terms and Abbreviations ```{r} #| echo: false #| results: asis c( '', 'Forward [pipe operator](https://search.r-project.org/R/refmans/base/html/pipeOp.html) introduced in `R` 4.1.0', '`$`', '[Extract](https://search.r-project.org/R/refmans/base/html/Extract.html) parts of an object', '[`binom`](https://search.r-project.org/R/refmans/stats/html/Binomial.html)', '[Binomial](https://en.wikipedia.org/wiki/Binomial_distribution) density and distribution', '`CRAN`, `R`', '[The Comprehensive R Archive Network](https://cran.r-project.org)', '[`class`](https://search.r-project.org/R/refmans/base/html/class.html)', 'Object class', '[`flextable`](https://search.r-project.org/CRAN/refmans/flextable/html/flextable.html)', 'Flexible tables', '`PASS`', 'Power Analysis & Sample Size, ', '`PET`', 'Probability of early termination', '[`ph2simon`](https://search.r-project.org/CRAN/refmans/clinfun/html/ph2simon.html)', 'Simon\'s 2-stage Phase II design', '`S3`, `generic`, `methods`', '`S3` object oriented system, [`UseMethod`](https://search.r-project.org/R/refmans/base/html/UseMethod.html); [`methods`](https://search.r-project.org/R/refmans/utils/html/methods.html); [`getS3method`](https://search.r-project.org/R/refmans/utils/html/getS3method.html); ', '`S4`, `generic`, `methods`', '`S4` object oriented system, [`isS4`](https://search.r-project.org/R/refmans/base/html/isS4.html); [`setClass`](https://search.r-project.org/R/refmans/methods/html/setClass.html); [`getMethod`](https://search.r-project.org/R/refmans/methods/html/getMethod.html); ', '[`search`](https://search.r-project.org/R/refmans/base/html/search.html)', 'Search path', '[`seed`](https://search.r-project.org/R/refmans/base/html/Random.html)', 'Random number generation seed', '[`table`](https://search.r-project.org/R/refmans/base/html/table.html)', 'Cross tabulation' ) |> matrix(nrow = 2L, dimnames = list(c('Term / Abbreviation', 'Description'), NULL)) |> t.default() |> as.data.frame.matrix() |> kable() ``` # Simon's Two-Stage Phase II Design ## Notations Simon's two-stage design tests the one-sided hypothesis $H_0: p\leq p_u$ vs. $H_a: p>p_u$ for a binary response in the following steps. 1. Enroll $n_1$ subjects. - **Early termination**, or **frail**, if $\leq r_1$ positive responses are observed. - Move to next stage if $>r_1$ response are observed. 2. Enroll an additional $(n-n_1)$ subjects. - **Fail**, if $\leq r$ total responses are observed. - **Success**, or $H_0$ rejected, if $>r$ total responses are observed. In this vignette, $p_u$ denotes the unacceptable response rate, and $p_a$ denotes the acceptable response rate. The parameter nomenclature of $r_1$, $n_1$, $r$ and $n$ follows that of `PASS` and of function `clinfun::ph2simon()`. Types of Simon's two-stage design include - `'minimax'` (default), minimum total sample size $n$ - `'optimal'`, minimum expected total sample size $\textrm{E}(n|p=p_u)$ - `'n1'`, minimum Stage-1 sample size $n_1$ - `'maximax'`, to use up the user-provided maximum total sample size, i.e., parameter `nmax` of function `clinfun::ph2simon()` - `'all'`, all `type`s listed above ## `S3` class `'ph2simon'` Function `clinfun::ph2simon()` returns an object of `S3` class `'ph2simon'`. The output is printed in the `R` console using `S3` method dispatch `clinfun:::print.ph2simon()`. Example below provides the various Simon's two-stage designs for hypotheses $p_u=.2$, $p_a=.4$, with Type-I error rate $\alpha=5\%$ and Type-II error rate $\beta=10\%$. ```{r} (x = ph2simon(pu = .2, pa = .4, ep1 = .05, ep2 = .1)) ``` ## `S4` class `'ph2simon4'` Function `ph2simon4()` converts an `S3` object `'ph2simon'` to an `S4` object `'ph2simon4'`. The output is printed in the `R` console using `S4` method dispatch `getMethod(f = 'show', signature = 'ph2simon4')`. ```{r} x |> ph2simon4(type = 'all') ``` # Probabilities ## Math Given a Simon's two-stage design $(r_1,n_1,r,n)$ and a true response rate $p$, we have - the number of Stage-1 positive responses $X_1 \sim \textrm{binom}(n_1, p)$. - the number of Stage-2 positive responses $X_2 \sim \textrm{binom}(n-n_1, p)$. - $X_1$ and $X_2$ are independent. The probability of early termination is $$ p_{\textrm{frail}} = \textrm{Pr}(X_1 \leq r_1) $$ The probability of failure to reject $H_0$ is $$ p_{\textrm{fail}} = \sum_{s_1 = r_1+1}^{n_1} \textrm{Pr}(X_1=s_1)\cdot\textrm{Pr}\left(X_2 \leq (r-s_1)\right) $$ The probability of successfully rejecting $H_0$ is $$ p_{\textrm{success}} = \sum_{s_1 = r_1+1}^{n_1} \textrm{Pr}(X_1=s_1)\cdot\textrm{Pr}(X_2 > (r-s_1)) $$ The expected sample size is $$ \textrm{E}(n) = p_{\textrm{frail}} \cdot n_1 + (1 - p_{\textrm{frail}}) \cdot n $$ ## Numbers The S3 generic `simon_pr()` calculates the probabilities of early termination, fail and success at one-or-more response rates $p$, either from an `S3` object `'ph2simon'`, ```{r} x |> simon_pr(prob = c(.2, .3, .4)) |> as_flextable() ``` or from an `S4` object `'ph2simon4'`, ```{r} x |> ph2simon4() |> simon_pr(prob = c(.2, .3, .4)) |> as_flextable() ``` or from the design parameters $(r_1, n_1, r, n)$. In such case the user must call the `S3` method dispatch `simon_pr.ph2simon4()` explicitly. ```{r} simon_pr.ph2simon4(prob = c(.2, .3, .4), r1 = 5L, n1 = 24L, r = 13L, n = 45L) |> as_flextable() ``` ## Visualization S3 methods dispatches for the generic `ggplot2::autoplot()` visualize the probabilities of early termination, fail and success at $p=p_u$ and $p=p_a$. The donut slices for success are colored with the highest opacity, indicating that they represent the Type-I error rate $\alpha$ if $p=p_u$, and the power $1-\beta$ if $p=p_a$. The probabilities are visualized either from an `S3` object `'ph2simon'`, ```{r} #| fig-width: 5 x |> autoplot(type = 'optimal') ``` or from an `S4` object `'ph2simon4'`. ```{r} #| fig-width: 5 x |> ph2simon4(type = 'optimal') |> autoplot() ``` or from the design parameters $(r_1, n_1, r, n)$ and `type`. In such case the user must call the `S3` method dispatch `autoplot.ph2simon4()` explicitly. ```{r} #| fig-width: 5 autoplot.ph2simon4(pu = .2, pa = .4, r1 = 5L, n1 = 24L, r = 13L, n = 45L, type = 'optimal') ``` ## Simulation The S3 generic `r_simon()` simulates the number of positive responses in Simon's two-stage design. Following examples show simulations of `1e4L` trials at $p=.3$, either from an `S3` object `'ph2simon'`, ```{r} set.seed(15); s = x |> r_simon(R = 1e4L, prob = .3, type = 'optimal') ``` or from an `S4` object `'ph2simon4'`, ```{r} set.seed(15); s1 = x |> ph2simon4(type = 'optimal') |> r_simon(R = 1e4L, prob = .3) stopifnot(identical(s, s1)) ``` or from the design parameters $(r_1, n_1, r, n)$. In such case the user must call the `S3` method dispatch `r_simon.ph2simon4()` explicitly. ```{r} set.seed(15); s2 = r_simon.ph2simon4(R = 1e4L, prob = .3, r1 = 4L, n1 = 19L, r = 15L, n = 54L) stopifnot(identical(s, s2)) ``` Obviously, at a sufficiently large simulated sample size, the Type-I error rate is controlled at $\alpha<5\%$ when $p=p_u=.2$, ```{r} set.seed(31); x |> r_simon(R = 1e4L, prob = .2) |> attr(which = 'dx', exact = TRUE) |> as_flextable() |> set_caption(caption = 'pu = .2') ``` and the Type-II error rate is controlled at $\beta<10\%$, or power $(1-\beta)>90\%$, when $p=p_a=.4$. ```{r} set.seed(24); x |> r_simon(R = 1e4L, prob = .4) |> attr(which = 'dx', exact = TRUE) |> as_flextable() |> set_caption(caption = 'pa = .4') ``` ```{r} #| eval: false #| echo: false #| results: hide summary(x) summary(x, type = 'all') ``` # Operating Characteristics Suppose we have three drugs $A$, $B$ and $C$, with true response rate $p^A=.3$, $p^B=.2$ and $p^C=.15$, respectively. ```{r} p = c(A = .3, B = .2, C = .15) ``` We simulated `1e4L` Simon's two-stage trials of each drug to obtain the **operating characteristics**, i.e., the percentage of trials in which each drug - having the highest number of responses - both having the highest number of responses *and* successfully rejecting the null hypothesis. The operating characteristics are visualized either from an `S3` object `'ph2simon'`, ```{r} #| fig-width: 5 set.seed(52); x |> simon_oc(prob = p, R = 1e4L, type = 'optimal') ``` or from an `S4` object `'ph2simon4'`, ```{r} #| fig-width: 5 set.seed(52); x |> ph2simon4(type = 'optimal') |> simon_oc(prob = p, R = 1e4L) ``` or from the design parameters $(r_1, n_1, r, n)$. In such case the user must call the `S3` method dispatch `simon_oc.ph2simon4()` explicitly. ```{r} #| fig-width: 5 set.seed(52); simon_oc.ph2simon4(prob = p, R = 1e4L, r1 = 4L, n1 = 19L, r = 15L, n = 54L) ```