Package architecture

Overview

The goldilocks package implements the Goldilocks adaptive trial design described in Broglio et al. (2014). This vignette provides a visual overview of how the package functions are interconnected.

Function dependency diagram

The diagram below shows the call graph from the top-level simulation function (sim_trials()) down through the core engine (survival_adapt()) and into the internal analysis pipeline.

Exported functions are shown in blue. Internal functions are shown in grey.

Function roles

The functions fall into three layers:

Simulation layer

sim_comp_data(): Generates a complete trial dataset by calling enrollment(), randomization(), and pwe_sim().
survival_adapt(): Simulates a single adaptive trial. Generates data via sim_comp_data(), conducts interim analyses using posterior() and test_stop_success(), and performs the final analysis via test_final(). With return_trace = TRUE, it also retains a compact audit trail for each completed interim look.
sim_trials(): Top-level entry point. Runs survival_adapt() across multiple trials (optionally in parallel) and collates results.

Post-processing functions

summarise_sims(): Summarizes the output of sim_trials(), computing operating characteristics such as power, expected sample size, and stopping probabilities.
plot_enrollment(): Draws the expected enrollment projection, optional simulated trajectories, and interim and maximum-sample-size milestones from explicit arguments or a stored trial design.
summarise_trial_trace(): Condenses an optional single-trial interim trace into a one-row stopping-path summary.
plot_trial_trace(): Visualizes predictive probabilities, thresholds, enrollment, and observed events for an optional single-trial trace.
plot_sim_stopping(): Visualizes marginal, conditional, cumulative, or flowchart stopping outcomes and enrolled sample sizes across simulated trials.
plot_sim_ocs(): Compares success, stopping, and expected-sample-size operating characteristics across treatment-effect scenarios.
plot_sim_decisions(): Maps simulated predictive probabilities into expected-success, continuation, and futility regions at each interim look.

Data generation and analysis utilities

enrollment(): Simulates exact continuous-time arrivals under constant or piecewise-constant enrollment rates.
randomization(): Generates the blocked two-arm treatment allocation.
pwe_sim() and pwe_impute(): Simulate event times from, or conditionally impute them under, the piecewise-exponential model.
ppwe(): Computes cumulative event probabilities under piecewise-exponential hazards.
prop_to_haz(): Converts cumulative event probabilities at specified times to the corresponding piecewise hazards.
posterior(): Estimates the posterior distribution of piecewise exponential hazard rates using a conjugate Gamma model.
analyse_data(): Applies the chosen analysis method (logrank, cox, bayes-surv, bayes-bin, or riskdiff) to an (imputed) dataset.
impute_data(): Imputes missing event times for censored subjects using pwe_impute() or pwe_sim().
haz_to_prop(): Converts posterior hazard rate draws to cumulative incidence proportions via ppwe().

The first five utilities in this section are exported for direct use. The final four are internal components of the adaptive analysis pipeline.