---
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 its compact, one-row final summary. Set `return_trace = TRUE` to request a `goldilocks_trial` object with that summary and a tidy row for each interim look.

## A traced trial

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

```{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(1, 1),
  prop_loss = 0.05,
  alternative = "less",
  h0 = 0,
  Fn = c(0.05, 0.05),
  Sn = c(0.95, 0.90),
  prob_ha = 0.95,
  N_impute = 20,
  N_mcmc = 20,
  method = "bayes-surv",
  empty_interval = "prior",
  return_trace = TRUE
)

trial
```

The summary element is the familiar final analysis output. The trace element is an audit trail of the interim path.

```{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 with `success_threshold`. `ppp_success_at_max` is the predictive probability of success if enrollment continues to the maximum sample size. It is compared with `futility_threshold`. The decision column records whether the design continued, stopped for expected success, or stopped for futility.

The trace does not retain posterior draws or completed imputed data sets. That keeps a traced trial small enough to inspect and share while leaving the underlying random-number path unchanged.

## 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 trajectories reproducible without changing
the caller's random-number state.

## Visualizing the 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

Traces are intended for examining individual trial paths. By default,
`sim_trials()` keeps only its compact result data frame, which is more suitable
for large operating characteristic simulations. Set `return_trace = TRUE` to
retain the interim paths across simulations. `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(1, 1),
  prop_loss = 0.05,
  alternative = "less",
  h0 = 0,
  Fn = c(0.05, 0.05),
  Sn = c(0.95, 0.90),
  prob_ha = 0.95,
  N_impute = 20,
  N_mcmc = 20,
  N_trials = 500,
  method = "bayes-surv",
  return_trace = TRUE,
  seed = 5702
)

summarise_sims(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$sims,
  "moderate" = sims_moderate$sims,
  "target" = sims$sims
))
scenario_oc$true_event_probability_difference <- c(0, -0.05, -0.10)

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

For reproducible simulations, set `seed` in `sim_trials()`. The per-trial random streams make the compact simulation results reproducible across supported parallel backends. For a detailed explanation of the decision algorithm and calibration, see the "Technical details of the Goldilocks design" vignette.