# dankscreamer/higgs_boson_classification architecture

> Architecture diagram of the GitHub repository dankscreamer/higgs_boson_classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dankscreamer/higgs_boson_classification
- Repository: https://github.com/dankscreamer/higgs_boson_classification

## Overview

This repository is a reproducible HIGGS particle-event classification study. A researcher prepares the dataset, explores and tunes it, then runs seeded benchmarks that compare feature sets and classical, neural, and hybrid models; the workflow evaluates calibration and statistical significance and records results for interpretation and reporting. The graph also preserves EDA, tuning, ablation, interpretation, and aggregation as distinct study capabilities. Edges follow shown imports/calls or README-documented workflow; some auxiliary script internals were not sampled, so their links rely on the README.

Main entry points: [`scripts/run_benchmark.py`](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_benchmark.py) (Benchmark runner), [`src/higgs/data.py`](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/data.py) (Data and splits), [`scripts/run_ablations.py`](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_ablations.py) (MLP ablations), [`scripts/interpret.py`](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/interpret.py) (Model interpretation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_features["Data and features"]
  node_dataset_pipeline["Dataset preparation<br/>[prepare_data.py]"]
  node_data_splits["Data and splits<br/>[data.py]"]
  node_geometry["Geometric features<br/>[physics.py]"]
end

subgraph group_experiments["Experiment workflows"]
  node_config["Study configuration<br/>[config.yaml]"]
  node_eda["Data quality EDA<br/>[eda.py]"]
  node_eda_run["EDA workflow<br/>[run_eda.py]"]
  node_tuning["Hyperparameter tuning<br/>[tune.py]"]
  node_benchmark["Benchmark runner<br/>[run_benchmark.py]"]
  node_ablation["MLP ablations<br/>[run_ablations.py]"]
end

subgraph group_modeling["Modeling and evaluation"]
  node_models["Model families<br/>[models.py]"]
  node_stacking["Stacking hybrid<br/>[hybrid.py]"]
  node_calibration["Probability calibration<br/>[calibration.py]"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_statistics["DeLong statistics<br/>[stats.py]"]
end

subgraph group_analysis["Analysis and reporting"]
  node_interpretation["Model interpretation<br/>[interpret.py]"]
  node_aggregation["Result aggregation<br/>[aggregate.py]"]
  node_plots["Study plots<br/>[plots.py]"]
  node_tables["Report tables<br/>[make_tables.py]"]
  node_results["Experiment results"]
end

node_researcher(("Researcher"))
node_uci_higgs["UCI HIGGS"]

node_researcher -->|"prepares data"| node_dataset_pipeline
node_uci_higgs -->|"provides dataset"| node_dataset_pipeline
node_dataset_pipeline -->|"converts data"| node_data_splits
node_researcher -->|"runs EDA"| node_eda_run
node_eda_run -->|"loads splits"| node_data_splits
node_eda_run -->|"runs checks"| node_eda
node_researcher -->|"tunes models"| node_tuning
node_tuning -->|"loads training data"| node_data_splits
node_researcher -->|"runs benchmark"| node_benchmark
node_benchmark -->|"loads settings"| node_config
node_benchmark -->|"loads splits"| node_data_splits
node_data_splits -->|"builds features"| node_geometry
node_benchmark -->|"fits models"| node_models
node_benchmark -->|"calibrates predictions"| node_calibration
node_benchmark -->|"fits stacker"| node_stacking
node_benchmark -->|"evaluates predictions"| node_metrics
node_benchmark -->|"tests AUCs"| node_statistics
node_benchmark -->|"creates figures"| node_plots
node_researcher -->|"runs ablations"| node_ablation
node_ablation -->|"loads splits"| node_data_splits
node_ablation -->|"fits MLP variants"| node_models
node_ablation -->|"evaluates variants"| node_metrics
node_ablation -->|"plots results"| node_plots
node_researcher -->|"interprets models"| node_interpretation
node_interpretation -->|"loads data"| node_data_splits
node_interpretation -->|"uses models"| node_models
node_interpretation -->|"plots explanations"| node_plots
node_researcher -->|"aggregates runs"| node_aggregation
node_aggregation -->|"creates figures"| node_plots
node_benchmark -->|"writes run outputs"| node_results
node_aggregation -->|"summarizes runs"| node_results
node_researcher -->|"generates tables"| node_tables
node_tables -->|"uses study outputs"| node_results

click node_dataset_pipeline "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/prepare_data.py"
click node_data_splits "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/data.py"
click node_geometry "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/physics.py"
click node_config "https://github.com/dankscreamer/higgs_boson_classification/blob/main/config.yaml"
click node_eda "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/eda.py"
click node_eda_run "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_eda.py"
click node_tuning "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/tune.py"
click node_benchmark "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_benchmark.py"
click node_ablation "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_ablations.py"
click node_models "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/models.py"
click node_stacking "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/hybrid.py"
click node_calibration "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/calibration.py"
click node_metrics "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/metrics.py"
click node_statistics "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/stats.py"
click node_interpretation "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/interpret.py"
click node_aggregation "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/aggregate.py"
click node_plots "https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/plots.py"
click node_tables "https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/make_tables.py"
click node_results "https://github.com/dankscreamer/higgs_boson_classification/tree/main/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dataset_pipeline,node_data_splits,node_geometry toneBlue
class node_config,node_eda,node_eda_run,node_tuning,node_benchmark,node_ablation toneAmber
class node_models,node_stacking,node_calibration,node_metrics,node_statistics toneMint
class node_interpretation,node_aggregation,node_plots,node_tables,node_results toneRose
class node_researcher,node_uci_higgs toneIndigo
```

## Components

### Data and features

- [Dataset preparation](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/prepare_data.py): `scripts/prepare_data.py`
- [Data and splits](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/data.py): `src/higgs/data.py`
- [Geometric features](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/physics.py): `src/higgs/physics.py`

### Experiment workflows

- [Study configuration](https://github.com/dankscreamer/higgs_boson_classification/blob/main/config.yaml): `config.yaml`
- [Data quality EDA](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/eda.py): `src/higgs/eda.py`
- [EDA workflow](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_eda.py): `scripts/run_eda.py`
- [Hyperparameter tuning](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/tune.py): `scripts/tune.py`
- [Benchmark runner](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_benchmark.py): `scripts/run_benchmark.py`
- [MLP ablations](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/run_ablations.py): `scripts/run_ablations.py`

### Modeling and evaluation

- [Model families](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/models.py): `src/higgs/models.py`
- [Stacking hybrid](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/hybrid.py): `src/higgs/hybrid.py`
- [Probability calibration](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/calibration.py): `src/higgs/calibration.py`
- [Performance metrics](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/metrics.py): `src/higgs/metrics.py`
- [DeLong statistics](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/stats.py): `src/higgs/stats.py`

### Analysis and reporting

- [Model interpretation](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/interpret.py): `scripts/interpret.py`
- [Result aggregation](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/aggregate.py): `scripts/aggregate.py`
- [Study plots](https://github.com/dankscreamer/higgs_boson_classification/blob/main/src/higgs/plots.py): `src/higgs/plots.py`
- [Report tables](https://github.com/dankscreamer/higgs_boson_classification/blob/main/scripts/make_tables.py): `scripts/make_tables.py`
- [Experiment results](https://github.com/dankscreamer/higgs_boson_classification/tree/main/results): `results`

### Other components

- **Researcher**
- **UCI HIGGS**

## Connections

- Researcher → Dataset preparation: prepares data (evidence: `README.md`)
- UCI HIGGS → Dataset preparation: provides dataset (evidence: `README.md`)
- Dataset preparation → Data and splits: converts data (evidence: `scripts/prepare_data.py`)
- Researcher → EDA workflow: runs EDA (evidence: `README.md`)
- EDA workflow → Data and splits: loads splits (evidence: `scripts/run_eda.py`)
- EDA workflow → Data quality EDA: runs checks (evidence: `scripts/run_eda.py`)
- Researcher → Hyperparameter tuning: tunes models (evidence: `README.md`)
- Hyperparameter tuning → Data and splits: loads training data (evidence: `scripts/tune.py`)
- Researcher → Benchmark runner: runs benchmark (evidence: `README.md`)
- Benchmark runner → Study configuration: loads settings (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → Data and splits: loads splits (evidence: `scripts/run_benchmark.py`)
- Data and splits → Geometric features: builds features (evidence: `src/higgs/data.py`)
- Benchmark runner → Model families: fits models (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → Probability calibration: calibrates predictions (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → Stacking hybrid: fits stacker (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → Performance metrics: evaluates predictions (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → DeLong statistics: tests AUCs (evidence: `scripts/run_benchmark.py`)
- Benchmark runner → Study plots: creates figures (evidence: `scripts/run_benchmark.py`)
- Researcher → MLP ablations: runs ablations (evidence: `README.md`)
- MLP ablations → Data and splits: loads splits (evidence: `scripts/run_ablations.py`)
- MLP ablations → Model families: fits MLP variants (evidence: `scripts/run_ablations.py`)
- MLP ablations → Performance metrics: evaluates variants (evidence: `scripts/run_ablations.py`)
- MLP ablations → Study plots: plots results (evidence: `scripts/run_ablations.py`)
- Researcher → Model interpretation: interprets models (evidence: `README.md`)
- Model interpretation → Data and splits: loads data (evidence: `scripts/interpret.py`)
- Model interpretation → Model families: uses models (evidence: `scripts/interpret.py`)
- Model interpretation → Study plots: plots explanations (evidence: `scripts/interpret.py`)
- Researcher → Result aggregation: aggregates runs (evidence: `README.md`)
- Result aggregation → Study plots: creates figures (evidence: `scripts/aggregate.py`)
- Benchmark runner → Experiment results: writes run outputs (evidence: `README.md`)
- Result aggregation → Experiment results: summarizes runs (evidence: `README.md`)
- Researcher → Report tables: generates tables (evidence: `README.md`)
- Report tables → Experiment results: uses study outputs (evidence: `README.md`)
