---
title: "Simulation studies with the native pipe"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Simulation studies with the native pipe}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r load-pkg}
library(FastSurvival)
```

# Overview

A simulation study of a time-to-event trial has three steps: generate the
trials, analyze each of them at its looks, and summarize the operating
characteristics over the trials. In FastSurvival these steps are
`simdata_fast()`, `analysis_fast()`, and `simsummary_fast()`, the simulation
trio, and each of them takes the result of the previous step as its first
argument. A study can therefore be written as one chain with the native pipe
`|>` of R, read from top to bottom in the order of the steps.
`cutoff_fast()`, `switch_fast()`, and `pairwise_fast()` fit into the same
chain.

The pipe changes only how the calls are written: `x |> f(y)` is the call
`f(x, y)`, so a chain gives the same results as nested calls or calls with
intermediate objects, and the tests of the package check this for every
function. The code below uses only syntax of R 4.1, the version that the
package requires: the pipe `|>`, functions written as `function(x)` or in
the short form `\(x)`, and no placeholder `_`, which needs R 4.2 and is not
needed here because the data always go to the first argument.

# One chain from data to operating characteristics

The trial randomizes 150 patients per group over 12 months. The median time
to event is 12 months in the control group (group 1) and 18 months in the
experimental group (group 2), and 1 percent of the patients per month drop
out. The log-rank test is performed at 120 and 180 events, one-sided, with
the nominal levels 0.003 and 0.024 at the two looks. These levels are only
for illustration; the vignette *Group sequential design with the simulation
trio* obtains such levels from a spending function with gsDesign.

```{r chain}
oc <- simdata_fast(nsim = 1000, n = c(150, 150), a.time = c(0, 12),
                   a.rate = 300 / 12, e.median = list(12, 18),
                   d.hazard = 0.01, seed = 1) |>
  analysis_fast(control = 1, event.looks = c(120, 180), side = 1) |>
  simsummary_fast(p.col = "logrank.p", alpha = c(0.003, 0.024))
oc
```

The probability of rejecting the null hypothesis at one of the looks, the
power, is `r round(oc$cum.reject[oc$look == "overall"], 3)`. The summary is
given a name so that it can be printed, plotted, and quoted; the `plot()`
method continues the chain and draws the cumulative probability of stopping
for efficacy against the expected number of events.

```{r chain-plot, fig.width = 6, fig.height = 4.5}
oc |> plot(xaxis = "events")
```

# Looks from event and calendar-time rules

The looks of a trial are often defined by a combination of rules, such as a
number of events or a calendar time, whichever comes first. `cutoff_fast()`
computes the calendar time of each look in every simulated trial from such
rules, and `analysis_fast()` accepts a function of the data in
`cutoff.looks`, which it applies to the data it receives. The rule is then
written inside the chain. Here the interim analysis is at 120 events or at
month 18, and the final analysis at 180 events or at month 30, whichever
comes first.

The data are generated with the same arguments and seed as in the previous
section, so they are the same data. They are given a name, `sims`, because
the following sections analyze them in several ways.

```{r rule}
sims <- simdata_fast(nsim = 1000, n = c(150, 150), a.time = c(0, 12),
                     a.rate = 300 / 12, e.median = list(12, 18),
                     d.hazard = 0.01, seed = 1)

oc_rule <- sims |>
  analysis_fast(control = 1, side = 1,
                cutoff.looks = \(x) cutoff_fast(x, event.looks = c(120, 180),
                                                max.time = c(18, 30))) |>
  simsummary_fast(p.col = "logrank.p", alpha = c(0.003, 0.024))
oc_rule
```

With the calendar limits the power is
`r round(oc_rule$cum.reject[oc_rule$look == "overall"], 3)` and the mean
calendar time of the final analysis is
`r round(oc_rule$cutoff.mean[oc_rule$look == "2"], 1)` months; with the event
targets alone they are `r round(oc$cum.reject[oc$look == "overall"], 3)` and
`r round(oc$cutoff.mean[oc$look == "2"], 1)` months.

# Several statistics from one analysis

When the same analysis is summarized in several ways, the analysis is done
once and its result is given a name; each summary then starts from it with
the pipe. Here the log-rank test and the restricted mean survival time
(RMST) up to month 12 are computed at the same looks and summarized with the
same nominal levels.

```{r two-stats}
res <- sims |>
  analysis_fast(control = 1, event.looks = c(120, 180), side = 1,
                stat = c("logrank", "rmst"), tau = 12)

oc_lr   <- res |> simsummary_fast(p.col = "logrank.p",
                                  alpha = c(0.003, 0.024))
oc_rmst <- res |> simsummary_fast(p.col = "rmst.p", alpha = c(0.003, 0.024))

c(log_rank = oc_lr$cum.reject[oc_lr$look == "overall"],
  RMST     = oc_rmst$cum.reject[oc_rmst$look == "overall"])
```

The log-rank result is that of the first section, because the data and the
looks are the same:

```{r same-as-chain}
all.equal(oc_lr$cum.reject, oc$cum.reject)
```

# One simulated trial

The estimation and testing functions take a data frame piped into their
formula interface. Below, the first simulated trial is taken from `sims`
with its whole follow-up, that is, without the administrative censoring of
an analysis, and analyzed with the Cox model and with the Kaplan-Meier
curves. The control group is the first level of `group`.

```{r one-trial, fig.width = 7, fig.height = 5}
one <- sims |> subset(sim == 1)

one |> coxph_fast(Surv(tte, event) ~ group, side = 1) |> as.data.frame()

one |> kmcurve_fast(Surv(tte, event) ~ group) |> plot(risk_table = TRUE)
```

Inside a simulation loop, the vector interface of these functions, with
presorted data, remains the faster choice (see the vignette *Speed
comparison*).

# Illness-death data and treatment switching

The design of the vignette *Treatment switching and crossover after an
interim analysis* is written here as chains. The trial randomizes 300
patients per group over 18 months, progression-free survival (PFS) and
overall survival (OS) follow an illness-death model, PFS is analyzed at 380
PFS events, and OS at 350 deaths. In the data of `simdata_fast()` PFS is in
the columns `e1_tte` and `e1_event` and OS in `e2_tte` and `e2_event`;
`cutoff_fast()` and `analysis_fast()` select them with `tte.col` and
`event.col`. The two cutoff rules are written once as functions, because they
are used several times.

```{r ids-data}
pfs_cut <- \(x) cutoff_fast(x, event.looks = 380, tte.col = "e1_tte",
                            event.col = "e1_event")
os_cut  <- \(x) cutoff_fast(x, event.looks = 350, tte.col = "e2_tte",
                            event.col = "e2_event")

ids <- simdata_fast(nsim = 1000, n = c(300, 300), a.time = c(0, 18),
                    a.rate = 600 / 18, h01.median = list(8, 12),
                    h02.median = list(30, 36), h12.median = list(12, 12),
                    d.hazard = -log(1 - 0.05) / 12, seed = 20261007)
```

In the first scenario, crossover opens at the PFS analysis of every trial:
the control patients who are alive and on study switch at progression, but
not before the PFS analysis, and their remaining survival time is multiplied
by 1.3. `switch_fast()` applies the function `pfs_cut` to the data it
receives, and `analysis_fast()` applies `os_cut` to the switched data, so the
OS analysis is triggered by the deaths after switching.

```{r ids-all}
ids |>
  switch_fast(group = 1, when = "later", cutoff = pfs_cut,
              aft.factor = 1.3) |>
  analysis_fast(control = 1, side = 1, cutoff.looks = os_cut,
                tte.col = "e2_tte", event.col = "e2_event") |>
  simsummary_fast(p.col = "logrank.p", alpha = 0.025)
```

In the second scenario, crossover opens only in the trials with a
significant PFS result. The decision needs the PFS analysis of the same data,
so the chain starts from the named data `ids` twice: once for the PFS
analysis, and once for the switch and the OS analysis, with the same rule
`pfs_cut`.

```{r ids-gated}
pfs <- ids |>
  analysis_fast(control = 1, side = 1, cutoff.looks = pfs_cut,
                tte.col = "e1_tte", event.col = "e1_event")
pfs_pos <- (pfs$reached & pfs$logrank.p <= 0.025) %in% TRUE

ids |>
  switch_fast(group = 1, when = "later", cutoff = pfs_cut, sims = pfs_pos,
              aft.factor = 1.3) |>
  analysis_fast(control = 1, side = 1, cutoff.looks = os_cut,
                tte.col = "e2_tte", event.col = "e2_event") |>
  simsummary_fast(p.col = "logrank.p", alpha = 0.025)
```

Switching rules that belong to the data-generating process are given to
`simdata_fast()` itself, and the chain then has no switching step. Here 30
percent of the control patients switch at progression, after which their
median survival is 18 months instead of 12.

```{r ids-rules}
simdata_fast(nsim = 1000, n = c(300, 300), a.time = c(0, 18),
             a.rate = 600 / 18, h01.median = list(8, 12),
             h02.median = list(30, 36), h12.median = list(12, 12),
             switch.prop = list(0.3, 0), h12.switch.median = 18,
             d.hazard = -log(1 - 0.05) / 12, seed = 20261007) |>
  analysis_fast(control = 1, side = 1, cutoff.looks = os_cut,
                tte.col = "e2_tte", event.col = "e2_event") |>
  simsummary_fast(p.col = "logrank.p", alpha = 0.025)
```

# Multi-arm trials

`pairwise_fast()` takes the place of `analysis_fast()` in a trial with
several experimental arms and a shared control. Here three arms of 150
patients have median survival times of 12 (control), 16, and 20 months; the
200th event of the control and the third arm fixes the cutoff of both
comparisons, and the Bonferroni-adjusted p-values are compared with the
one-sided level 0.025. `simsummary_fast()` summarizes each arm separately.

```{r multi-arm}
simdata_fast(nsim = 1000, n = c(150, 150, 150), a.time = c(0, 12),
             a.rate = 450 / 12, e.median = list(12, 16, 20), seed = 2) |>
  pairwise_fast(control = 1, event.looks = 200, primary = 3, side = 1,
                adjust = "bonferroni") |>
  simsummary_fast(p.col = "p.adj", alpha = 0.025)
```

# Large studies in batches

The data of all simulated trials are held in memory at once, so a large
study is run in batches. Each batch below is one chain from the data to the
analysis results; the batches use the same seed and their own random-number
streams (`stream = b`), so the data of a batch do not depend on the other
batches or on the order in which the batches are run. The simulated trials
are numbered from 1 in every batch and are renumbered before the results are
combined and summarized. With `parallel::mclapply()` or the future framework
in place of `lapply()`, the batches run in parallel and give the same
results.

```{r batches}
run_batch <- function(b, nsim = 250) {
  res_b <- simdata_fast(nsim = nsim, n = c(150, 150), a.time = c(0, 12),
                        a.rate = 300 / 12, e.median = list(12, 18),
                        d.hazard = 0.01, seed = 2026, stream = b) |>
    analysis_fast(control = 1, event.looks = c(120, 180), side = 1)
  res_b$sim <- res_b$sim + (b - 1) * nsim
  res_b
}

oc_batch <- do.call(rbind, lapply(1:4, run_batch)) |>
  simsummary_fast(p.col = "logrank.p", alpha = c(0.003, 0.024))
oc_batch
```

The `r 4 * 250` trials of the four batches give a power of
`r round(oc_batch$cum.reject[oc_batch$look == "overall"], 3)`, which differs
from the value of the first section only by Monte Carlo error, because the
batches are drawn from other random-number streams. The max-combo p-values of
`analysis_fast()` with four or more weights, or with a two-sided test, use
R's own random-number generator; for p-values that are identical across runs,
each batch then also calls `set.seed()` before the analysis.

# Remarks

The examples above follow a few rules. Each function of the chain receives
the data, or the result of the previous step, as its first argument, so the
placeholder `_` of R 4.2 is never needed, and the code runs with R 4.1. An
intermediate result is given a name when it is used more than once, as the
data `sims` and `ids` and the analysis results `res` and `pfs` above; a chain
then starts from the name. Rules that depend on the data, such as the cutoffs
of `cutoff_fast()`, are passed as functions, so that they are applied to the
data at that point of the chain.
