---
title: "Single-arm phase II trials with binary endpoints"
author: "Jiangyan Zhao and Rongji Mu"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Single-arm phase II trials with binary endpoints}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(BayesianTrial)
```

## Clinical question and trial design

Consider a hypothetical single-arm phase II trial evaluating the objective
response rate (ORR) of a new treatment. The historical ORR is 20%, while
40% is considered a promising response rate. The study uses a binary
endpoint (response or no response) and a Beta(0.2, 0.8) prior.

The trial plans one interim analysis after 20 patients, with a maximum
sample size of 40. Efficacy and futility decisions are based on the
posterior probability that the ORR exceeds the historical rate of 20%:

| Analysis | Decision rule |
|:--|:--|
| Interim | Stop for efficacy if the posterior probability is > 0.98 |
| Interim | Stop for futility if the posterior probability is <= 0.50 |
| Interim | Otherwise, continue enrollment |
| Final, if continued | Declare success if the posterior probability is > 0.95 |

These sample sizes and thresholds are illustrative. In practice, they
should be specified before enrollment and assessed against the trial's
desired type I error rate and power.

## Evaluate the design before enrollment

Use `oc_singlearm_binary()` to estimate the operating characteristics
of this two-stage design. We consider a true ORR of 20% for the null
scenario and 40% for the alternative scenario.

```{r operating-characteristics}
true_rates <- c(0.20, 0.40)

oc_results <- lapply(true_rates, function(theta) {
  oc_singlearm_binary(
    theta_true = theta,
    n_current = 20,
    N_total = 40,
    alpha0 = 0.2,
    beta0 = 0.8,
    theta0_null = 0.20,
    gamma_early = 0.98,
    gamma_futility = 0.50,
    gamma_final = 0.95,
    ntrial = 10000,
    seed = 666
  )
})

oc_table <- data.frame(
  true_ORR = true_rates,
  do.call(rbind, lapply(oc_results, unlist)),
  row.names = NULL
)
knitr::kable(oc_table, digits = 3)
```

The `power_null_post` column gives the overall probability of declaring
the trial successful, including early efficacy stopping. It estimates
the **type I error rate** when the true ORR is 20%, and **power** when
the true ORR is 40%. The two remaining columns give the probabilities
of stopping early for futility or efficacy.

The 40% rate is used here to evaluate power, **not** as an additional
requirement for declaring trial success. If the operating characteristics
do not meet the design targets, revise the sample sizes or thresholds
and evaluate the design again. The function evaluates specified designs;
it does not calibrate them automatically.

## Analyze the interim results

Suppose 9 of the first 20 patients respond. At the interim analysis,
calculate the posterior probability that the ORR exceeds the historical
reference rate of 20%:

```{r interim-posterior}
posterior <- posterior_predictive_singlearm_binary(
  x_obs = 9,
  n_current = 20,
  N_total = 40,
  alpha0 = 0.2,
  beta0 = 0.8,
  theta0_null = 0.20
)

posterior$p_null
```

The posterior distribution is Beta(9.2, 11.8), and the probability of
exceeding 20% is approximately 0.992. Apply the prespecified interim
stopping rules to the observed data:

```{r interim-decision}
decision <- if (posterior$p_null > 0.98) {
  "Stop for efficacy"
} else if (posterior$p_null <= 0.50) {
  "Stop for futility"
} else {
  "Continue to the final analysis"
}

decision
```

The posterior probability exceeds the efficacy stopping threshold
of 0.98, so the trial stops early for efficacy under this design.
For trials that continue, final success requires the posterior
probability of exceeding 20% to be greater than 0.95.

## Predictive probability if enrollment continues

For illustration, we also assess the probability of meeting the final
success criterion **if the trial were to continue to 40 evaluable
patients**, despite meeting the early efficacy stopping rule:

```{r interim-predictive}
predictive <- posterior_predictive_singlearm_binary(
  x_obs = 9,
  n_current = 20,
  N_total = 40,
  alpha0 = 0.2,
  beta0 = 0.8,
  theta0_null = 0.20,
  gamma_final = 0.95,
  type = "predictive",
  S = 10000,
  seed = 666
)

predictive$ppos_null
```

Here, `ppos_null` is the posterior predictive probability that the
final posterior probability will exceed 0.95. This is a supplementary
assessment and does not determine stopping in the current design.
The function defaults to `type = "posterior"`; setting
`type = "both"` returns posterior summaries and predictive
probabilities together.

## Additional clinical-target assessment

The predictive function also reports `ppos_clin`, the probability of
meeting a separate posterior criterion for a clinically relevant ORR
(`theta0_clin`, default 0.40). Its final posterior threshold is
`gamma_clin_final` (default 0.90). This output can be used as an
additional summary but is **not** included in the success and stopping
rules evaluated by `oc_singlearm_binary()`.

To adapt the example to another study, specify its historical response
rate, prior, interim and maximum sample sizes, and decision thresholds.
Reassess operating characteristics before using the design in a trial.
