# ism-ail11/snap-uq architecture

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

- Interactive diagram: https://gitdiagram.com/ism-ail11/snap-uq
- Repository: https://github.com/ism-ail11/snap-uq

## Overview

SNAP-UQ is a research toolkit for training compact image/audio classifiers, fitting self-supervised next-activation predictors, and evaluating uncertainty offline or on streams. The typical workflow configures data and a backbone, trains the backbone, trains SNAP-UQ heads, optionally calibrates scores, then evaluates detection or selective risk. Baselines and experiment runners support the paper’s comparisons and ablations. Source-index references and README statements support the unsampled branches; those branches are represented at their exact enclosing directories rather than implying inspected implementation details.

Main entry points: [`scripts/preprocess`](https://github.com/ism-ail11/snap-uq/tree/main/scripts/preprocess) (Data preprocessing), [`snapuq/data/vision.py`](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/data/vision.py) (Vision datasets), [`configs/experiments`](https://github.com/ism-ail11/snap-uq/tree/main/configs/experiments) (Experiment configs), [`snapuq/snapuq.py`](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/snapuq.py) (SNAP-UQ predictors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data"]
  node_preprocessing["Data preprocessing"]
  node_vision_data["Vision datasets<br/>[vision.py]"]
  node_audio_data["Audio datasets<br/>[audio.py]"]
  node_corruptions["Corruption suites"]
end

subgraph group_models["Models and training"]
  node_backbones["Backbone models"]
  node_model_factory["Model factory<br/>[factory.py]"]
  node_backbone_training["Classifier training<br/>[train.py]"]
  node_posthoc_training["Predictor training<br/>[train.py]"]
  node_utilities["Runtime utilities"]
end

subgraph group_uq["Uncertainty and evaluation"]
  node_snapuq_method["SNAP-UQ predictors<br/>[snapuq.py]"]
  node_baselines["Uncertainty baselines<br/>[baselines.py]"]
  node_calibration["Score calibration<br/>[calibration.py]"]
  node_offline_eval["Offline evaluation<br/>[eval.py]"]
  node_metrics["Detection metrics<br/>[metrics.py]"]
  node_streaming["Streaming evaluation<br/>[streaming.py]"]
end

subgraph group_experiments["Research workflows"]
  node_configs["Experiment configs"]
  node_ablations["Ablation runner<br/>[run_ablations.py]"]
  node_appendix["Appendix runner<br/>[run_appendix.py]"]
  node_results["Results runner<br/>[run_results.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures"| node_configs
node_researcher -->|"prepares data"| node_preprocessing
node_configs -->|"selects model"| node_model_factory
node_model_factory -->|"constructs"| node_backbones
node_preprocessing -.->|"prepares inputs"| node_vision_data
node_preprocessing -.->|"prepares inputs"| node_audio_data
node_vision_data -.->|"supports corruption data"| node_corruptions
node_audio_data -->|"imports safe helpers"| node_utilities
node_vision_data -->|"imports safe helpers"| node_utilities
node_backbone_training -->|"trains classifier"| node_backbones
node_backbone_training -->|"uses training helpers"| node_utilities
node_configs -->|"configures through builder"| node_snapuq_method
node_posthoc_training -->|"optimizes predictors"| node_snapuq_method
node_researcher -->|"trains heads"| node_posthoc_training
node_snapuq_method -.->|"maps scores"| node_calibration
node_offline_eval -->|"computes measures"| node_metrics
node_streaming -.->|"reports event measures"| node_metrics
node_researcher -->|"evaluates offline"| node_offline_eval
node_researcher -->|"evaluates streams"| node_streaming
node_researcher -->|"compares methods"| node_baselines
node_researcher -->|"runs ablations"| node_ablations
node_researcher -->|"runs experiments"| node_appendix
node_researcher -.->|"runs results"| node_results

click node_configs "https://github.com/ism-ail11/snap-uq/tree/main/configs/experiments"
click node_preprocessing "https://github.com/ism-ail11/snap-uq/tree/main/scripts/preprocess"
click node_vision_data "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/data/vision.py"
click node_audio_data "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/data/audio.py"
click node_corruptions "https://github.com/ism-ail11/snap-uq/tree/main/snapuq/data/corruptions"
click node_backbones "https://github.com/ism-ail11/snap-uq/tree/main/snapuq/models"
click node_model_factory "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/models/factory.py"
click node_backbone_training "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/train.py"
click node_snapuq_method "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/snapuq.py"
click node_posthoc_training "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/train.py"
click node_baselines "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/baselines.py"
click node_calibration "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/calibration.py"
click node_offline_eval "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/eval.py"
click node_metrics "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/metrics.py"
click node_streaming "https://github.com/ism-ail11/snap-uq/blob/main/snapuq/streaming.py"
click node_utilities "https://github.com/ism-ail11/snap-uq/tree/main/snapuq/utils"
click node_ablations "https://github.com/ism-ail11/snap-uq/blob/main/scripts/ablations/run_ablations.py"
click node_appendix "https://github.com/ism-ail11/snap-uq/blob/main/scripts/appendix/run_appendix.py"
click node_results "https://github.com/ism-ail11/snap-uq/blob/main/scripts/results/run_results.py"

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_preprocessing,node_vision_data,node_audio_data,node_corruptions toneBlue
class node_backbones,node_model_factory,node_backbone_training,node_posthoc_training,node_utilities toneAmber
class node_snapuq_method,node_baselines,node_calibration,node_offline_eval,node_metrics,node_streaming toneMint
class node_configs,node_ablations,node_appendix,node_results toneRose
class node_researcher toneIndigo
```

## Components

### Data

- [Data preprocessing](https://github.com/ism-ail11/snap-uq/tree/main/scripts/preprocess): `scripts/preprocess`
- [Vision datasets](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/data/vision.py): `snapuq/data/vision.py`
- [Audio datasets](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/data/audio.py): `snapuq/data/audio.py`
- [Corruption suites](https://github.com/ism-ail11/snap-uq/tree/main/snapuq/data/corruptions): `snapuq/data/corruptions`

### Models and training

- [Backbone models](https://github.com/ism-ail11/snap-uq/tree/main/snapuq/models): `snapuq/models`
- [Model factory](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/models/factory.py): `snapuq/models/factory.py`
- [Classifier training](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/train.py): `snapuq/train.py`
- [Predictor training](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/train.py): `snapuq/train.py`
- [Runtime utilities](https://github.com/ism-ail11/snap-uq/tree/main/snapuq/utils): `snapuq/utils`

### Uncertainty and evaluation

- [SNAP-UQ predictors](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/snapuq.py): `snapuq/snapuq.py`
- [Uncertainty baselines](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/baselines.py): `snapuq/baselines.py`
- [Score calibration](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/calibration.py): `snapuq/calibration.py`
- [Offline evaluation](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/eval.py): `snapuq/eval.py`
- [Detection metrics](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/metrics.py): `snapuq/metrics.py`
- [Streaming evaluation](https://github.com/ism-ail11/snap-uq/blob/main/snapuq/streaming.py): `snapuq/streaming.py`

### Research workflows

- [Experiment configs](https://github.com/ism-ail11/snap-uq/tree/main/configs/experiments): `configs/experiments`
- [Ablation runner](https://github.com/ism-ail11/snap-uq/blob/main/scripts/ablations/run_ablations.py): `scripts/ablations/run_ablations.py`
- [Appendix runner](https://github.com/ism-ail11/snap-uq/blob/main/scripts/appendix/run_appendix.py): `scripts/appendix/run_appendix.py`
- [Results runner](https://github.com/ism-ail11/snap-uq/blob/main/scripts/results/run_results.py): `scripts/results/run_results.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment configs: configures (evidence: `README.md`)
- Researcher → Data preprocessing: prepares data (evidence: `README.md`)
- Experiment configs → Model factory: selects model
- Model factory → Backbone models: constructs (evidence: `snapuq/models/factory.py`)
- Data preprocessing → Vision datasets: prepares inputs (evidence: `README.md`)
- Data preprocessing → Audio datasets: prepares inputs (evidence: `README.md`)
- Vision datasets → Corruption suites: supports corruption data (evidence: `README.md`)
- Audio datasets → Runtime utilities: imports safe helpers (evidence: `snapuq/data/audio.py`)
- Vision datasets → Runtime utilities: imports safe helpers (evidence: `snapuq/data/vision.py`)
- Classifier training → Backbone models: trains classifier (evidence: `snapuq/train.py`)
- Classifier training → Runtime utilities: uses training helpers (evidence: `snapuq/train.py`)
- Experiment configs → SNAP-UQ predictors: configures through builder
- Predictor training → SNAP-UQ predictors: optimizes predictors (evidence: `snapuq/train.py`)
- Researcher → Predictor training: trains heads (evidence: `README.md`)
- SNAP-UQ predictors → Score calibration: maps scores
- Offline evaluation → Detection metrics: computes measures (evidence: `snapuq/eval.py`)
- Streaming evaluation → Detection metrics: reports event measures (evidence: `README.md`)
- Researcher → Offline evaluation: evaluates offline (evidence: `README.md`)
- Researcher → Streaming evaluation: evaluates streams (evidence: `README.md`)
- Researcher → Uncertainty baselines: compares methods (evidence: `README.md`)
- Researcher → Ablation runner: runs ablations (evidence: `README.md`)
- Researcher → Appendix runner: runs experiments (evidence: `README.md`)
- Researcher → Results runner: runs results
