---
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(
  '[|>](https://search.r-project.org/R/refmans/base/html/pipeOp.html)', 'Forward pipe operator 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, <https://www.ncss.com/software/pass/>', 
  '`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`](https://search.r-project.org/R/refmans/utils/html/methods.html)', '`S3` object oriented system, [`UseMethod`](https://search.r-project.org/R/refmans/base/html/UseMethod.html); [`getS3method`](https://search.r-project.org/R/refmans/utils/html/getS3method.html); <https://adv-r.hadley.nz/s3.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); <https://adv-r.hadley.nz/s4.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'
) |>
  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$ responses 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 = 4L, n1 = 19L, r = 15L, n = 54L, 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)
```
