---
title: "Inspecting adaptive decision paths"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Inspecting adaptive decision paths}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

An adaptive trial is easier to assess when the final result can be connected
back to the interim decisions that led to it. By default, `survival_adapt()`
returns a one-row trial summary. Set `return_trace = TRUE` to retain the summary
together with one record for each completed interim look.

## Reviewing one trial's interim history

This small Bayesian survival design has two interim looks. The treatment arm is assumed to have a lower cumulative failure probability by 24 months.

The common `prop_loss = 0.05` specifies a 5% dropout-time CDF at 24 months.
Dropout is exponential and independent of event time within each arm; an event
before dropout remains observed. Actual dropout censoring can therefore be
below 5%, with additional incomplete follow-up at interim looks due to staged
enrollment.

```{r traced-trial}
end_of_study <- 24
hazard_control <- prop_to_haz(c(0.20, 0.35), 12, end_of_study)
hazard_treatment <- prop_to_haz(c(0.12, 0.24), 12, end_of_study)

trial <- survival_adapt(
  hazard_treatment = hazard_treatment,
  hazard_control = hazard_control,
  cutpoints = 12,
  N_total = 80,
  lambda = 8,
  lambda_time = NULL,
  interim_look = c(40, 60),
  end_of_study = end_of_study,
  prior_surv = c(0.1, 0.1),
  block = 2,
  rand_ratio = c(control = 1, treatment = 1),
  prop_loss = 0.05,
  alternative = "less",
  h0 = 0,
  Fn = c(0.05, 0.05),
  Sn = c(0.95, 0.90),
  Qn = c(0.99, 0.99),
  prob_ha = 0.95,
  N_impute = 20,
  N_mcmc = 20,
  method = "bayes-surv",
  empty_interval = "prior",
  return_trace = TRUE
)

trial
```

The trial summary reports the official outcome and final analysis, when one is
required. The interim history provides an audit trail of the predictive
probabilities and decisions.

```{r trace-table}
trial$summary
trial$trace
summarise_trial_trace(trial)
```

For each completed look, `ppp_stop_now` is the predictive probability of
success if enrollment stops at that look. It is compared first with
`immediate_success_threshold` and then with `success_threshold`.
`ppp_success_at_max` is the predictive probability of success if enrollment
continues to the maximum sample size and is compared with
`futility_threshold`. The `decision` column records whether the design declared
immediate success, stopped accrual for expected success, stopped for binding
futility, or continued.

The interim history retains Monte Carlo summaries rather than every posterior
draw or completed imputation. It is therefore concise enough to include in a
simulation review or interim-analysis record.

## Visualizing the enrollment plan

Trial and simulation results retain their evaluated enrollment design, so the
enrollment projection can be drawn without repeating `lambda`, `N_total`, or
the interim looks:

```{r enrollment-plot, fig.width = 7, fig.height = 4.8}
plot_enrollment(
  trial,
  n_sim = 20,
  seed = 20260727,
  time_unit = "months"
)
```

The blue line is expected cumulative enrollment and the grey step functions
are newly simulated enrollment trajectories. Dashed guides mark the two
interim looks and the maximum sample size. Because this design has a constant
enrollment rate, each displayed milestone time is its mean arrival time,
$(N - 1) / \lambda$. For piecewise enrollment rates, the plot instead labels
the time at which expected cumulative enrollment reaches the milestone.
Supplying `seed` makes the displayed enrollment trajectories reproducible.

## Plotting the interim decision path

```{r trace-plot, fig.width = 7, fig.height = 8}
plot_trial_trace(trial)
```

The first two panels show the two predictive probabilities alongside their decision thresholds. The final panel shows enrollment and observed events by arm at each look. Warnings raised during a look, such as empty-interval handling, are recorded in `warning_messages` and remain visible as ordinary R warnings.

## Summarizing many simulated trials

Interim histories are intended for examining individual trial paths. By
default, `sim_trials()` retains the trial-level outcomes needed to estimate
operating characteristics. Set `return_trace = TRUE` to retain the interim
paths as well. `plot_sim_stopping()` summarizes
where and why enrollment stopped through marginal, conditional, cumulative, or
flowchart views, while `plot_sim_decisions()` shows how the two predictive
probabilities map to the decision regions at each look. Supplying the complete
traced result ensures that stopping views include reached looks at which no
trial stopped.

```{r simulation-summary, eval = FALSE}
sims <- sim_trials(
  hazard_treatment = hazard_treatment,
  hazard_control = hazard_control,
  cutpoints = 12,
  N_total = 80,
  lambda = 8,
  lambda_time = NULL,
  interim_look = c(40, 60),
  end_of_study = end_of_study,
  prior_surv = c(0.1, 0.1),
  block = 2,
  rand_ratio = c(control = 1, treatment = 1),
  prop_loss = 0.05,
  alternative = "less",
  h0 = 0,
  Fn = c(0.05, 0.05),
  Sn = c(0.95, 0.90),
  Qn = c(0.99, 0.99),
  prob_ha = 0.95,
  N_impute = 20,
  N_mcmc = 20,
  N_trials = 500,
  method = "bayes-surv",
  return_trace = TRUE,
  seed = 5702
)

summarise_sims(sims)
plot_sim_stopping(sims)
plot_sim_stopping(sims, type = "flowchart")
plot_sim_decisions(sims)
```

The three simulation plotting functions answer different questions.
`plot_sim_stopping()` describes the terminal sample-size distribution and can
re-express the same stopping paths conditionally, cumulatively, or as a flow;
`plot_sim_decisions()` explains how interim predictive probabilities produced
those decisions. To compare operating characteristics across a grid of true
treatment effects, summarize the scenarios together and supply their numeric
effect values to `plot_sim_ocs()`:

```{r simulation-oc-curve, eval = FALSE}
scenario_oc <- summarise_sims(list(
  "null" = sims_null,
  "moderate" = sims_moderate,
  "target" = sims
))
effect_by_scenario <- c(null = 0, moderate = -0.05, target = -0.10)
scenario_oc$true_event_probability_difference <- unname(
  effect_by_scenario[scenario_oc$scenario]
)

plot_sim_ocs(
  scenario_oc,
  effect = "true_event_probability_difference",
  xlab = "True treatment-control event-probability difference"
)
```

For reproducible simulations, prespecify `seed` in `sim_trials()`. Results are
then reproducible whether the trials are evaluated sequentially or in parallel.
For a detailed explanation of the decision algorithm and calibration, see the
"Technical details of the Goldilocks design" vignette.