---
title: "Frequentist binary outcome designs"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Frequentist binary outcome designs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
set.seed(6301)
```

```{r setup, message=FALSE}
library(goldilocks)
```

`goldilocks` provides two frequentist analyses for a two-arm binary outcome
measured at a fixed follow-up time:

-   `method = "riskdiff-fm"` uses a Farrington-Manning score test.
-   `method = "riskdiff-wald"` retains the plug-in Wald test.

Both methods estimate the treatment-minus-control event-risk difference,

$$\widehat\Delta = \widehat p_{\text{treatment}} -
  \widehat p_{\text{control}},$$

and compare it with the null value or margin supplied through `h0`. All three
alternatives are supported. For example, when events are undesirable,
`alternative = "less"` asks whether the treatment event risk is lower than the
control event risk by enough to cross the chosen threshold.

## Choosing the analysis

`riskdiff-fm` is the more suitable choice when small samples or rare outcomes
can produce zero events, all events, or little outcome variation in one arm.
Its variance uses maximum likelihood event risks constrained by the null
hypothesis. Under `h0 = 0`, an equal-arm all-zero or all-one table produces a
neutral test result instead of a zero-variance error. A table with events in
only one arm ordinarily retains a positive constrained variance and is analyzed
in the usual way.

`riskdiff-wald` uses the observed arm risks directly in an unpooled plug-in
variance. It is retained for designs that prespecify that analysis and for
reproducing earlier results. The former `method = "riskdiff"` name remains a
deprecated alias for `"riskdiff-wald"` and produces a warning. New analyses
should prespecify one of the two procedures explicitly.

The Farrington-Manning calculation has no continuity correction. If its
null-constrained variance is zero, `goldilocks` defines the score statistic as
zero when the observed risk difference equals `h0`, positive infinity when it
is above `h0`, and negative infinity when it is below `h0`.

## Example design

Suppose the control event probability by 12 months is expected to be 10%, and
the treatment event probability is expected to be 5%. The following small
example uses the score test with a one-sided alternative:

```{r score-design}
end_of_study <- 12

result <- survival_adapt(
  hazard_treatment = prop_to_haz(0.05, endtime = end_of_study),
  hazard_control = prop_to_haz(0.10, endtime = end_of_study),
  N_total = 80,
  lambda = 10,
  interim_look = 40,
  end_of_study = end_of_study,
  alternative = "less",
  h0 = 0,
  Fn = 0.05,
  Sn = 0.90,
  prob_ha = 0.975,
  N_impute = 20,
  method = "riskdiff-fm"
)

result
```

For a non-inferiority design, `h0` can be a nonzero risk-difference margin. If
an increase in undesirable events of no more than 5 percentage points is
acceptable, use `h0 = 0.05` with `alternative = "less"`. The score-test
variance is then calculated from event risks constrained to differ by 0.05.

## Pending and missing endpoint outcomes

At an interim look, each pending endpoint is completed from the
piecewise-exponential predictive model before the selected risk-difference test
is applied. `binary_imputation = "event-time"` samples a conditional event time;
`binary_imputation = "bernoulli"` samples the equivalent fixed-time status
directly.

At the final analysis, subjects lost before complete endpoint ascertainment are
excluded when `imputed_final = FALSE`. With `imputed_final = TRUE`, the package
uses the selected complete-data test directly if no outcomes are missing.
When outcomes require imputation, `riskdiff-wald` combines estimates and
within-imputation variances using Rubin's rules. This requires at least two
imputations and positive total variance; zero total variance produces a
non-estimability error.

Genuine final imputation is unsupported for `riskdiff-fm` because no validated
FM pooling rule is implemented. Simulations with FM and `imputed_final = TRUE`
require `prop_loss = 0` in both arms and reject positive dropout at setup.
The package does not substitute a pooled Wald test for FM.

With nonzero `prop_loss`, the simulator draws dropout independently of event
time from an exponential distribution whose CDF at `end_of_study` equals
`prop_loss`. Actual censoring by dropout can be less frequent because events
can occur first. Independent censoring supports survival inference, but
complete-case binary analysis can still overestimate event probabilities:
early events remain observed while later endpoint outcomes can be missing.
Evaluate final imputation and sensitivity to its event-time model for binary
designs with dropout.

The saved results include the selected method and evaluated design arguments,
providing an auditable record of the analysis specification.

## Reference

Farrington CP, Manning G. Test statistics and sample size formulae for
comparative binomial trials with null hypothesis of non-zero risk difference or
non-unity relative risk. *Statistics in Medicine*. 1990; **9**:1447-1454.
doi:10.1002/sim.4780091208.