# angelfdezgetino/adaptive-massive-event-detection architecture

> Architecture diagram of the GitHub repository angelfdezgetino/adaptive-massive-event-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/angelfdezgetino/adaptive-massive-event-detection
- Repository: https://github.com/angelfdezgetino/adaptive-massive-event-detection

## Overview

This repository detects unusual public-transport demand peaks in station time series. A user selects a station and year; the pipeline preprocesses daily demand, estimates seasonal baselines and CEI/PEI behaviour, then applies an adaptive IQR or MAD detector before filtering and exporting candidate events. It can evaluate results against optional ground-truth calendars and plot single-station analyses. A separate heatmap script reads exported detections for calendar-style visualization. The workflow is documented in the README; source excerpts show pipeline internals and heatmap input handling, but not every stage’s implementation details.

Main entry points: [`Python/event_detection_pipeline.py`](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py) (Station-Year Pipeline), [`Python/heatmap.py`](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/heatmap.py) (Event Heatmap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Pipeline"]
  node_runner["Interactive Runner"]
  node_pipeline["Station-Year Pipeline"]
end

subgraph group_analysis["Detection Analysis"]
  node_preprocess["Daily Preprocessing"]
  node_seasonal["Seasonal Baseline"]
  node_indicators["CEI/PEI Indicators"]
  node_hampel_stl["Hampel + STL"]
  node_adaptive["Adaptive Detection"]
  node_filter["Detection Filtering"]
end

subgraph group_results["Evaluation &amp; Results"]
  node_evaluation["Metrics Evaluation"]
  node_event_csv[("Detected Events CSV")]
end

subgraph group_views["Visualization"]
  node_single_plots["Station Plots"]
  node_heatmap["Event Heatmap<br/>[heatmap.py]"]
end

node_user(("User"))
node_station_data["Station Data"]
node_ground_truth["Event Calendars"]

node_user -->|"selects station/year"| node_runner
node_station_data -->|"loads CSV"| node_runner
node_runner -->|"runs station-year"| node_pipeline
node_pipeline -->|"preprocesses demand"| node_preprocess
node_preprocess -->|"decomposes series"| node_seasonal
node_seasonal -->|"estimates behaviour"| node_indicators
node_indicators -->|"assesses behaviour"| node_hampel_stl
node_hampel_stl -->|"supplies residuals"| node_adaptive
node_adaptive -->|"detects candidates"| node_filter
node_ground_truth -->|"provides labels"| node_evaluation
node_filter -->|"supplies detections"| node_evaluation
node_evaluation -->|"exports events"| node_event_csv
node_pipeline -->|"plots single station"| node_single_plots
node_event_csv -->|"reads detections"| node_heatmap

click node_runner "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_pipeline "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_preprocess "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_seasonal "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_indicators "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_hampel_stl "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_adaptive "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_filter "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_evaluation "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_single_plots "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py"
click node_heatmap "https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/heatmap.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_runner,node_pipeline,node_user toneBlue
class node_preprocess,node_seasonal,node_indicators,node_hampel_stl,node_adaptive,node_filter toneAmber
class node_evaluation,node_event_csv toneMint
class node_single_plots,node_heatmap toneRose
class node_station_data,node_ground_truth toneIndigo
```

## Components

### Pipeline

- [Interactive Runner](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Station-Year Pipeline](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`

### Detection Analysis

- [Daily Preprocessing](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Seasonal Baseline](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [CEI/PEI Indicators](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Hampel + STL](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Adaptive Detection](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Detection Filtering](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`

### Evaluation & Results

- [Metrics Evaluation](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- **Detected Events CSV**

### Visualization

- [Station Plots](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/event_detection_pipeline.py): `Python/event_detection_pipeline.py`
- [Event Heatmap](https://github.com/angelfdezgetino/adaptive-massive-event-detection/blob/main/Python/heatmap.py): `Python/heatmap.py`

### Other components

- **User**
- **Station Data**
- **Event Calendars**

## Connections

- User → Interactive Runner: selects station/year (evidence: `README.md`)
- Station Data → Interactive Runner: loads CSV (evidence: `README.md`)
- Interactive Runner → Station-Year Pipeline: runs station-year (evidence: `README.md`)
- Station-Year Pipeline → Daily Preprocessing: preprocesses demand (evidence: `README.md`)
- Daily Preprocessing → Seasonal Baseline: decomposes series (evidence: `README.md`)
- Seasonal Baseline → CEI/PEI Indicators: estimates behaviour (evidence: `README.md`)
- CEI/PEI Indicators → Hampel + STL: assesses behaviour (evidence: `README.md`)
- Hampel + STL → Adaptive Detection: supplies residuals (evidence: `README.md`)
- Adaptive Detection → Detection Filtering: detects candidates (evidence: `README.md`)
- Event Calendars → Metrics Evaluation: provides labels (evidence: `README.md`)
- Detection Filtering → Metrics Evaluation: supplies detections (evidence: `README.md`)
- Metrics Evaluation → Detected Events CSV: exports events (evidence: `README.md`)
- Station-Year Pipeline → Station Plots: plots single station (evidence: `README.md`)
- Detected Events CSV → Event Heatmap: reads detections (evidence: `Python/heatmap.py`)
