# Cascade Simulation Results Explorer

This directory contains a deployment-ready R Shiny application for the verified primary cascade-simulation study (Watts–Strogatz rewiring probability \(\beta=.10\)). The read-only app organizes the archived results around the manuscript’s five research questions. It presents one bounded comparison at a time rather than displaying the complete factorial design on a single page.

## Guided research-question views

The app has seven top-level tabs:

1. **Start** introduces the five questions and provides direct links to each guided view.
2. **Graph family** compares the high–low target difference across Erdős–Rényi, Barabási–Albert, and Watts–Strogatz graphs.
3. **Density** compares sparse and denser graphs and can display either the high–low difference or absolute final cascade extent, with all three graph families visible together.
4. **Centrality metric** compares degree, strength, harmonic closeness, and betweenness.
5. **Thresholds** compares the sensitive, moderate, elevated, and resilient regimes across all three graph families and can display either the high–low difference or final extent.
6. **Total failure** compares graph families and high- versus low-centrality targets, with separate displays for completion frequency and conditional synchronous updates.
7. **Study & downloads** explains the data flow and provides the reproduction script, verified output bundle, data dictionary, and technical verification record.

Each research-question page keeps its comparison dimension open and shows all three graph families whenever family comparisons are relevant. Graph family is therefore a visual comparison, not a selector. The remaining single-choice controls are limited to density, centrality metric, and threshold regime when those conditions are needed for the current question. In particular, the Thresholds view requires only density and centrality metric selections. The default context is denser graphs, strength centrality, and the moderate threshold regime.

Graph families use a consistent color-and-marker key throughout the app. In plots that show both endpoint targets, the most-central target is solid and the least-central target is dashed; family color and marker remain unchanged. This repeated visual grammar keeps the six family-by-target series distinguishable without adding another control.

The public hovers are intentionally concise: they identify the displayed condition, report the focal estimate, and include one additional quantity only when it is needed for interpretation. High–low contrast plots show 95% Monte Carlo interval error bars; final-extent intervals remain available in the hover without adding six overlapping sets of error bars. A short finding beneath each plot highlights a result for the selected conditions.

## Run locally

From this directory:

```r
shiny::runApp()
```

Or from a shell:

```sh
Rscript -e "shiny::runApp('.', launch.browser = TRUE)"
```

The app was built and verified with R 4.4.2. Deployment dependencies are declared in `DESCRIPTION` and recorded in `renv.lock`.

The prepared runtime data are stored in `data/cascade_results_explorer.rds`. To regenerate that object from the bundled verified outputs, install the preparation dependencies (`dplyr`, `readr`, and `tidyr`) and run:

```sh
Rscript prepare_app_data.R
```

## Share a guided view

The active research-question tab, density, centrality metric, threshold regime, and the display toggles on the Density, Thresholds, and Total failure pages are stored in a versioned query string. The **Copy view link** button copies that URL when the browser permits clipboard access. A shared URL therefore restores the same question, condition snapshot, and display mode.

## Download results and provenance

Every research-question page offers **Download this snapshot**, which exports the rows underlying the current plot as a CSV file. The **Study & downloads** page separately provides:

- the complete R reproduction script;
- a ZIP archive of the verified source results and code;
- the compact data dictionary; and
- the technical reproducibility record displayed within the app.

The app reads archived outputs and never reruns or modifies the simulation in response to user input.

## Host the app

A Shiny application requires an R process; it cannot be hosted as a purely static HTML file. Deploy this directory to shinyapps.io, Posit Connect, or a server running Shiny Server. Once deployed, link to it from an ordinary website or embed it in an iframe. See `DEPLOYMENT.md` for commands and an embedding example.

## Scientific interpretation

The high–low contrast is the paired difference in final cascade extent between cascades initiated at the most- and least-central eligible vertices under matched simulated conditions. Monte Carlo intervals describe simulation precision around a condition mean; they are not empirical-population confidence intervals or significance tests.

Total-failure update counts are calculated only among replications in which all 20 vertices activated. A condition with no complete cascades is shown as **not estimable**, never as zero updates. Completion percentages use all replications and provide the denominator needed to interpret those conditional means.

## Directory map

```text
app.R                    Guided Shiny interface and server logic
R/                       Plot, display, and versioned URL-state helpers
data/                    Prepared app data and compact data dictionary
source-data/             Verified summaries, replication data, code, and provenance
www/                     Responsive styles and representative manuscript figures
prepare_app_data.R       Rebuilds prepared app data from verified outputs
tests/                   Scientific-integrity, plot-contract, and URL-state tests
DEPLOYMENT.md             Hosting and website-embedding instructions
```
