# bg-bibek/master-thesis-volcano-detection architecture

> Architecture diagram of the GitHub repository bg-bibek/master-thesis-volcano-detection, 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/bg-bibek/master-thesis-volcano-detection
- Repository: https://github.com/bg-bibek/master-thesis-volcano-detection

## Overview

This repository is a research toolkit for training and evaluating temporal CNN classifiers on Thalia volcanic-deformation WebDataset shards. The main workflow loads and normalizes shard samples, trains a classifier, and evaluates predictions; separate tools support unseen-data evaluation, threshold selection, permutation test-time augmentation, Grad-CAM localization, and temporal-pattern analysis. The graph also includes shard inspection and results analysis. Relationships are limited to calls or dependencies shown in excerpts and SOURCE INDEX references; some standalone scripts have no evidenced links.

Main entry points: [`train.py`](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/train.py) (Training runner), [`evaluate_unseen.py`](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/evaluate_unseen.py) (Unseen-data evaluation), [`data_loader_fixed.py`](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/data_loader_fixed.py) (Shard data loader), [`analyze_temporal_patterns.py`](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/analyze_temporal_patterns.py) (Temporal pattern analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data handling"]
  node_loader["Shard data loader"]
  node_shard_inspector["Shard inspector<br/>[inspect_shards.py]"]
end

subgraph group_train["Model training"]
  node_trainer["Training runner<br/>[train.py]"]
  node_focal["Focal loss<br/>[focal_loss.py]"]
end

subgraph group_eval["Evaluation"]
  node_unseen_eval["Unseen-data evaluation<br/>[evaluate_unseen.py]"]
  node_threshold["Threshold sweep<br/>[threshold_sweep.py]"]
  node_permutation["Permutation TTA<br/>[permutation_tta.py]"]
end

subgraph group_analysis["Research analysis"]
  node_gradcam["Grad-CAM localization<br/>[gradcam.py]"]
  node_cam_compare["Grad-CAM comparison<br/>[compare_gradcam.py]"]
  node_temporal["Temporal pattern analysis"]
  node_results_table["Results table builder"]
  node_log_parser["Log parser<br/>[parse_logs.py]"]
end

node_researcher(("Researcher"))
node_shards["WebDataset shards"]
node_outputs["Evaluation outputs"]

node_researcher -->|"starts training"| node_trainer
node_shards -->|"supplies samples"| node_loader
node_trainer -->|"loads batches"| node_loader
node_trainer -->|"uses loss"| node_focal
node_researcher -->|"inspects shards"| node_shard_inspector
node_researcher -->|"evaluates checkpoint"| node_unseen_eval
node_unseen_eval -->|"loads samples"| node_loader
node_unseen_eval -->|"reuses model code"| node_trainer
node_researcher -->|"sweeps threshold"| node_threshold
node_threshold -->|"reuses model code"| node_trainer
node_threshold -->|"creates loaders"| node_loader
node_researcher -->|"runs TTA"| node_permutation
node_permutation -->|"uses evaluation utilities"| node_unseen_eval
node_researcher -->|"generates localization"| node_gradcam
node_gradcam -->|"loads samples"| node_loader
node_gradcam -->|"builds classifier"| node_trainer
node_researcher -->|"analyzes patterns"| node_temporal
node_temporal -->|"loads samples"| node_loader
node_temporal -->|"loads model state"| node_trainer
node_temporal -->|"uses evaluation utilities"| node_unseen_eval
node_researcher -->|"compares localization"| node_cam_compare
node_researcher -->|"builds results table"| node_results_table
node_researcher -->|"parses logs"| node_log_parser
node_unseen_eval -.->|"reports metrics"| node_outputs

click node_loader "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/data_loader_fixed.py"
click node_shard_inspector "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/inspect_shards.py"
click node_trainer "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/train.py"
click node_focal "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/focal_loss.py"
click node_unseen_eval "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/evaluate_unseen.py"
click node_threshold "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/threshold_sweep.py"
click node_permutation "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/permutation_tta.py"
click node_gradcam "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/gradcam.py"
click node_cam_compare "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/compare_gradcam.py"
click node_temporal "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/analyze_temporal_patterns.py"
click node_results_table "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/make_results_table.py"
click node_log_parser "https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/parse_logs.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_loader,node_shard_inspector toneBlue
class node_trainer,node_focal toneAmber
class node_unseen_eval,node_threshold,node_permutation toneMint
class node_gradcam,node_cam_compare,node_temporal,node_results_table,node_log_parser toneRose
class node_researcher,node_shards,node_outputs toneIndigo
```

## Components

### Data handling

- [Shard data loader](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/data_loader_fixed.py): `data_loader_fixed.py`
- [Shard inspector](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/inspect_shards.py): `inspect_shards.py`

### Model training

- [Training runner](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/train.py): `train.py`
- [Focal loss](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/focal_loss.py): `focal_loss.py`

### Evaluation

- [Unseen-data evaluation](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/evaluate_unseen.py): `evaluate_unseen.py`
- [Threshold sweep](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/threshold_sweep.py): `threshold_sweep.py`
- [Permutation TTA](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/permutation_tta.py): `permutation_tta.py`

### Research analysis

- [Grad-CAM localization](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/gradcam.py): `gradcam.py`
- [Grad-CAM comparison](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/compare_gradcam.py): `compare_gradcam.py`
- [Temporal pattern analysis](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/analyze_temporal_patterns.py): `analyze_temporal_patterns.py`
- [Results table builder](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/make_results_table.py): `make_results_table.py`
- [Log parser](https://github.com/bg-bibek/master-thesis-volcano-detection/blob/main/parse_logs.py): `parse_logs.py`

### Other components

- **Researcher**
- **WebDataset shards**
- **Evaluation outputs**

## Connections

- Researcher → Training runner: starts training
- WebDataset shards → Shard data loader: supplies samples (evidence: `data_loader_fixed.py`)
- Training runner → Shard data loader: loads batches (evidence: `train.py`)
- Training runner → Focal loss: uses loss (evidence: `train.py`)
- Researcher → Shard inspector: inspects shards (evidence: `inspect_shards.py`)
- Researcher → Unseen-data evaluation: evaluates checkpoint (evidence: `evaluate_unseen.py`)
- Unseen-data evaluation → Shard data loader: loads samples (evidence: `evaluate_unseen.py`)
- Unseen-data evaluation → Training runner: reuses model code (evidence: `evaluate_unseen.py`)
- Researcher → Threshold sweep: sweeps threshold (evidence: `threshold_sweep.py`)
- Threshold sweep → Training runner: reuses model code (evidence: `threshold_sweep.py`)
- Threshold sweep → Shard data loader: creates loaders (evidence: `threshold_sweep.py`)
- Researcher → Permutation TTA: runs TTA (evidence: `permutation_tta.py`)
- Permutation TTA → Unseen-data evaluation: uses evaluation utilities (evidence: `permutation_tta.py`)
- Researcher → Grad-CAM localization: generates localization (evidence: `gradcam.py`)
- Grad-CAM localization → Shard data loader: loads samples (evidence: `gradcam.py`)
- Grad-CAM localization → Training runner: builds classifier (evidence: `gradcam.py`)
- Researcher → Temporal pattern analysis: analyzes patterns (evidence: `analyze_temporal_patterns.py`)
- Temporal pattern analysis → Shard data loader: loads samples (evidence: `analyze_temporal_patterns.py`)
- Temporal pattern analysis → Training runner: loads model state (evidence: `analyze_temporal_patterns.py`)
- Temporal pattern analysis → Unseen-data evaluation: uses evaluation utilities (evidence: `analyze_temporal_patterns.py`)
- Researcher → Grad-CAM comparison: compares localization (evidence: `compare_gradcam.py`)
- Researcher → Results table builder: builds results table (evidence: `make_results_table.py`)
- Researcher → Log parser: parses logs (evidence: `parse_logs.py`)
- Unseen-data evaluation → Evaluation outputs: reports metrics
