ONLINE RESOURCE 1 — REPRODUCIBILITY PACKAGE
=================================

This package supports the manuscript:
"Equivalence-Aware Controls for Hypergraph Machine Learning in Scientific Signal Modeling"

Journal: Machine Learning for Computational Science and Engineering
Authors: Advik Mishra; Daniel Edward Pitts
Corresponding author: Advik Mishra
Location: Edison, New Jersey, United States; E-mail: advikm048@gmail.com

This package contains no private participant data or private repository links.

DIRECTORY MAP
-------------
code/run_sleep_eeg_analysis.py
    End-to-end Sleep-EDF download, preprocessing, feature extraction, temporal
    hypergraph/graph/null construction, subject-wise evaluation, statistics,
    and figure/result generation. This script downloads public Sleep-EDF data
    through MNE/PhysioNet when run with network access.

code/run_incidence_null_audit.py
    Reproduces the 1,000-draw size-preserving incidence-randomization audit.
    Extract Supplementary_Data_S2.zip into the working directory, or place
    subject_stage_hyperedge_weights.csv beside the script before running.

code/run_exact_projection_audit.py
    Reproduces the exact induced-graph versus incidence-form propagation audit.
    It automatically reads data/Supplementary_Data_S1.zip.

code/run_depth_equivalence_audit.py
    Independently forms the incidence operator and the normalized A* graph
    operator, then verifies their agreement through three shared propagation
    layers with elementwise nonlinearities on 200 Sleep-EDF epochs.

code/run_external_benchmarks_and_positive_control.py
    Reproduces the Wisconsin Diagnostic Breast Cancer, Digits, and secondary
    third-order parity software-sanity experiment using datasets distributed
    with scikit-learn.

code/run_external_operator_distance_audit.py
    Measures relative Frobenius and spectral distances between P_H and the
    conventional clique operator for every held-out external-benchmark sample.

code/run_external_prediction_agreement_audit.py
    Counts held-out graph/hypergraph label disagreements and decision-score
    differences, and fits a train-fold least-squares representation map as a
    descriptive relatedness diagnostic.

code/run_theory_and_equivalence_audit.py
    Verifies the Pasch-trade/scaffold non-injectivity construction, reproduces
    the corrected practical-equivalence analysis for the external benchmarks,
    and computes the paired Sleep-EDF minimum-detectable-effect estimate.

requirements.txt
    Python dependencies.

data/Supplementary_Data_S1.zip
    Sanitized Sleep-EDF recording manifest, epoch-level features, and temporal
    context features used by the analysis. These are derived features, not raw
    participant recordings.

data/Supplementary_Data_S2.zip
    Machine-readable Sleep-EDF outputs: fold and subject metrics, OOF
    predictions, stage-specific results, topology/hyperedge tests, randomized
    incidence draws, and result summaries.

results/
    Saved outputs from exact and depth-wise graph-equivalence audits, two
    external benchmark stress tests, operator-distance measurements,
    practical-equivalence statistics, the incidence-structure construction,
    and the secondary parity sanity check.

figures/
    Supplementary confusion matrices for the primary linear graph and
    hypergraph readouts.

QUICK REPRODUCTION
------------------
From the package root, create an environment and install dependencies:

    python -m pip install -r requirements.txt

Exact one-step projection identity:

    python code/run_exact_projection_audit.py

Three-layer fixed-operator architecture audit:

    python code/run_depth_equivalence_audit.py

External benchmarks + secondary parity sanity check:

    python code/run_external_benchmarks_and_positive_control.py

External operator distances:

    python code/run_external_operator_distance_audit.py

External prediction agreement / representation-map diagnostic:

    python code/run_external_prediction_agreement_audit.py

Theory/equivalence/MDE audit:

    python code/run_theory_and_equivalence_audit.py

Incidence randomization:

    unzip data/Supplementary_Data_S2.zip -d data/Supplementary_Data_S2
    cd data/Supplementary_Data_S2
    python ../../code/run_incidence_null_audit.py

Full Sleep-EDF pipeline (downloads public source data and may take substantial
runtime):

    python code/run_sleep_eeg_analysis.py

CLAIM-TO-FILE MAP
-----------------
42,308 epochs / 20 subjects / primary model results:
    data/Supplementary_Data_S2.zip -> MANUSCRIPT_RESULTS.json,
    Table1_main_performance.csv, subject_metrics.csv,
    paired_subject_statistics.csv

Hypergraph - clique graph subject-level macro-F1 difference and paired test:
    data/Supplementary_Data_S2.zip -> paired_subject_statistics.csv

Stage-conditioned hyperedge and topology tests:
    data/Supplementary_Data_S2.zip -> hyperedge_stage_tests.csv,
    topology_stage_tests.csv, holm_adjusted_topology_posthoc_tests.csv

1,000-draw incidence specificity audit:
    data/Supplementary_Data_S2.zip -> randomized_incidence_null_draws.csv,
    randomized_incidence_audit_summary.csv

Exact one-step operator-equivalence audit:
    results/exact_projection_equivalence.csv

Three-layer architecture-equivalence audit:
    results/depth_equivalence_audit.json

Auxiliary Breast Cancer and Digits benchmarks:
    results/additional_benchmark_fold_metrics.csv,
    additional_benchmark_summary.csv, additional_benchmark_paired.csv

Distance between P_H and the conventional clique operator:
    results/external_operator_distances.csv,
    external_operator_distance_summary.csv

Held-out prediction agreement and representation-map diagnostic:
    results/external_prediction_agreement.csv,
    external_prediction_agreement_summary.csv,
    external_representation_linear_map.csv

Corrected practical-equivalence analysis for graph versus hypergraph:
    results/equivalence_statistics.csv

Explicit incidence structures with identical A* and P_H:
    results/noninjectivity_summary.json, noninjectivity_pair_counts.csv

Sleep-EDF paired 80%-power minimum detectable effect:
    results/sleep_paired_mde.json

Secondary synthetic three-way parity software sanity check:
    results/synthetic_positive_control.csv

DATA PROVENANCE
---------------
The Sleep-EDF source is a public PhysioNet dataset. This supplement distributes
only the derived tables used in the manuscript; the public raw EEG is obtained
from its source by the end-to-end script. Dataset citation and licensing
information are given in the manuscript and the data archive README.

STATISTICAL / SCOPE NOTES
-------------------------
- Subject is the inferential unit for the Sleep-EDF paired test.
- External split-level graph/hypergraph comparisons use corrected-resampled
  equivalence analysis where variance is nonzero; exact split-wise equality is
  reported directly when all paired differences are zero.
- The +/-0.005 macro-F1 equivalence margin was chosen before computing the
  equivalence analysis, but was not preregistered before the study.
- The parity experiment is only a software sanity check, not evidence for a
  hypergraph-native architecture.
- The incidence audit preserves hyperedge sizes and observed weight trajectories,
  so it tests membership conditional on those trajectories.
- Histogram gradient boosting is an exploratory shared-configuration robustness
  readout. Practical-equivalence claims rely on the primary linear readout.

Author locations (unaffiliated):
- Advik Mishra — Edison, New Jersey, United States
- Daniel Edward Pitts — Dubai, United Arab Emirates
