---
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: source
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)) documents the visualization of probabilities and operating characteristics of Simon's two-stage Phase II design.


## Getting Started

Examples in this vignette require that the `search` path has

```{r}
library(VisualizeSimon2Stage)
library(clinfun)
library(flextable)
library(ggplot2)
```

```{r}
#| echo: false
theme_minimal() |>
  theme_set()
```

# 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`](https://www.ncss.com/software/pass/) and of the function [`clinfun::ph2simon()`](https://search.r-project.org/CRAN/refmans/clinfun/html/ph2simon.html).

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()`](https://search.r-project.org/CRAN/refmans/clinfun/html/ph2simon.html)
-   `'all'`, all `type`s listed above

## `S3` class `'ph2simon'`

The function [`clinfun::ph2simon()`](https://search.r-project.org/CRAN/refmans/clinfun/html/ph2simon.html) 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'`

The 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: 4
#| fig-height: 4
x |> 
  autoplot(type = 'optimal')
```

or from an `S4` object `'ph2simon4'`.

```{r}
#| fig-width: 4
#| fig-height: 4
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: 4
#| fig-height: 4
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))
```

The Type-I error rate is controlled at $\alpha\leq 5\%$ when $p=p_u=.2$ at a sufficiently large simulated sample size.  The Type-II error rate is controlled at $\beta\leq 10\%$, or power $(1-\beta)\geq 90\%$, when $p=p_a=.4$.


```{r}
#| code-fold: true
#| code-summary: 'R code: Type-I-error rate at $p_u$, `1e4L` simulated copies'
set.seed(31); x |> 
  r_simon(R = 1e4L, prob = .2) |> 
  attr(which = 'dx', exact = TRUE) |> 
  table(Decision = _) |>
  as_flextable() |> 
  highlight(i = 3L, j = 3L) |>
  add_header_lines(values = 'pu = .2')
```

```{r}
#| code-fold: true
#| code-summary: 'R code: power at $p_a$, `1e4L` simulated copies'
set.seed(24); x |> 
  r_simon(R = 1e4L, prob = .4) |>
  attr(which = 'dx', exact = TRUE) |>
  table(Decision = _) |>
  as_flextable() |> 
  highlight(i = 3L, j = 3L) |>
  add_header_lines(values = 'pa = .4')
```

```{r}
#| eval: false
#| echo: false
#| results: hide
summary(x)
summary(x, type = 'all')
```


# Power Curve

```{r}
#| fig-width: 4
#| fig-height: 3
x |> 
  powerCurve.ph2simon()
```

```{r}
#| fig-width: 4
#| fig-height: 3
x |> 
  ph2simon4() |>
  powerCurve.ph2simon4()
```

# 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 simulate `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: 4
#| fig-height: 4
set.seed(52); x |> 
  simon_oc(prob = p, R = 1e4L, type = 'optimal')
```

or from an `S4` object `'ph2simon4'`,

```{r}
#| fig-width: 4
#| fig-height: 4
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: 4
#| fig-height: 4
set.seed(52); simon_oc.ph2simon4(prob = p, R = 1e4L, r1 = 4L, n1 = 19L, r = 15L, n = 54L)
```