--- title: "Package architecture" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Package architecture} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## 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. ```{r, echo = FALSE, fig.width = 8, fig.height = 8, fig.alt = "Diagram showing the function call dependencies in the goldilocks package."} DiagrammeR::grViz(" digraph goldilocks { graph [rankdir = TB, fontsize = 12, nodesep = 0.4, ranksep = 0.6] node [shape = box, style = 'filled, rounded', fontname = Helvetica, fontsize = 10] # Exported functions (blue) sim_trials [label = 'sim_trials()', fillcolor = '#dae8fc', color = '#6c8ebf'] survival_adapt [label = 'survival_adapt()', fillcolor = '#dae8fc', color = '#6c8ebf'] summarise_sims [label = 'summarise_sims()', fillcolor = '#dae8fc', color = '#6c8ebf'] plot_enrollment [label = 'plot_enrollment()', fillcolor = '#dae8fc', color = '#6c8ebf'] summarise_trial_trace [label = 'summarise_trial_trace()', fillcolor = '#dae8fc', color = '#6c8ebf'] plot_trial_trace [label = 'plot_trial_trace()', fillcolor = '#dae8fc', color = '#6c8ebf'] plot_sim_stopping [label = 'plot_sim_stopping()', fillcolor = '#dae8fc', color = '#6c8ebf'] plot_sim_ocs [label = 'plot_sim_ocs()', fillcolor = '#dae8fc', color = '#6c8ebf'] plot_sim_decisions [label = 'plot_sim_decisions()', fillcolor = '#dae8fc', color = '#6c8ebf'] sim_comp_data [label = 'sim_comp_data()', fillcolor = '#dae8fc', color = '#6c8ebf'] enrollment [label = 'enrollment()', fillcolor = '#dae8fc', color = '#6c8ebf'] randomization [label = 'randomization()', fillcolor = '#dae8fc', color = '#6c8ebf'] pwe_sim [label = 'pwe_sim()', fillcolor = '#dae8fc', color = '#6c8ebf'] pwe_impute [label = 'pwe_impute()', fillcolor = '#dae8fc', color = '#6c8ebf'] ppwe [label = 'ppwe()', fillcolor = '#dae8fc', color = '#6c8ebf'] prop_to_haz [label = 'prop_to_haz()', fillcolor = '#dae8fc', color = '#6c8ebf'] # Internal functions (grey) test_stop_success [label = 'test_stop_success()', fillcolor = '#f5f5f5', color = '#999999'] test_final [label = 'test_final()', fillcolor = '#f5f5f5', color = '#999999'] analyse_data [label = 'analyse_data()', fillcolor = '#f5f5f5', color = '#999999'] bayes_binomial_test [label = 'bayes_binomial_test()', fillcolor = '#f5f5f5', color = '#999999'] impute_data [label = 'impute_data()', fillcolor = '#f5f5f5', color = '#999999'] posterior [label = 'posterior()', fillcolor = '#f5f5f5', color = '#999999'] haz_to_prop [label = 'haz_to_prop()', fillcolor = '#f5f5f5', color = '#999999'] logrank_test [label = 'logrank_test()', fillcolor = '#f5f5f5', color = '#999999'] # Edges sim_trials -> survival_adapt sim_trials -> summarise_sims [style = dashed, label = 'output list'] sim_trials -> plot_sim_stopping [style = dashed, label = 'simulation output'] sim_trials -> plot_sim_decisions [style = dashed, label = 'simulation traces'] sim_trials -> plot_enrollment [style = dashed, label = 'stored design'] summarise_sims -> plot_sim_ocs [style = dashed, label = 'scenario summaries'] survival_adapt -> sim_comp_data survival_adapt -> posterior survival_adapt -> test_stop_success survival_adapt -> test_final survival_adapt -> summarise_trial_trace [style = dashed, label = 'optional trace'] survival_adapt -> plot_trial_trace [style = dashed, label = 'optional trace'] survival_adapt -> plot_enrollment [style = dashed, label = 'stored design'] sim_comp_data -> enrollment sim_comp_data -> randomization sim_comp_data -> pwe_sim test_stop_success -> impute_data test_stop_success -> analyse_data test_final -> posterior test_final -> impute_data test_final -> analyse_data analyse_data -> posterior analyse_data -> haz_to_prop analyse_data -> bayes_binomial_test analyse_data -> logrank_test haz_to_prop -> ppwe prop_to_haz -> sim_comp_data [style = dashed, label = 'hazard inputs'] impute_data -> pwe_impute impute_data -> pwe_sim } ") ``` ## 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.