# souvik-dey-2029/margganit architecture

> Architecture diagram of the GitHub repository souvik-dey-2029/margganit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souvik-dey-2029/margganit
- Repository: https://github.com/souvik-dey-2029/margganit

## Overview

MargGanit is a NumPy road-safety analytics engine. Its main workflow loads accident records, removes duplicates and builds a validated numerical feature matrix, calculates and ranks risk for occupied 10-km road segments, then prints the top results. The risk indicator combines spatial concentration, mean severity, and hourly-entropy-based temporal concentration, with reliability adjustments for severity and temporal estimates. The README also documents notebook analyses and visualizations; their internal wiring is not shown in the sampled source.

Main entry points: [`src/main.py`](https://github.com/souvik-dey-2029/margganit/blob/main/src/main.py) (Analysis runner), [`src/risk_engine.py`](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py) (Segment risk engine), [`src/preprocessing.py`](https://github.com/souvik-dey-2029/margganit/blob/main/src/preprocessing.py) (Dedup and features), [`src/data_loader.py`](https://github.com/souvik-dey-2029/margganit/blob/main/src/data_loader.py) (CSV loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Data preparation"]
  node_dataset["Accident CSV"]
  node_loader["CSV loader<br/>[data_loader.py]"]
  node_preprocessing["Dedup and features<br/>[preprocessing.py]"]
  node_validation["Feature validation<br/>[preprocessing.py]"]
end

subgraph group_analytics["Risk analytics"]
  node_risk["Segment risk engine<br/>[risk_engine.py]"]
  node_concentration["Spatial concentration<br/>[risk_engine.py]"]
  node_severity["Adjusted severity<br/>[risk_engine.py]"]
  node_temporal["Temporal concentration<br/>[risk_engine.py]"]
  node_ranking["Composite ranking<br/>[risk_engine.py]"]
end

subgraph group_runtime["Analysis runtime"]
  node_main["Analysis runner<br/>[main.py]"]
  node_results["Printed top segments<br/>[main.py]"]
end

subgraph group_notebooks["Exploratory analysis"]
  node_exploration["Data exploration"]
  node_cleaning["NumPy cleaning"]
  node_risknotebook["Risk analysis"]
  node_analysis["Results and plots<br/>[04_analysis.ipynb]"]
end

node_analyst(("Analyst"))

node_analyst -->|"runs analysis"| node_main
node_dataset -->|"loaded from"| node_loader
node_main -->|"loads data"| node_loader
node_main -->|"preprocesses data"| node_preprocessing
node_preprocessing -->|"builds features"| node_validation
node_main -->|"validates matrix"| node_validation
node_main -->|"calculates risk"| node_risk
node_risk -->|"calculates counts"| node_concentration
node_risk -->|"adjusts severity"| node_severity
node_risk -->|"calculates entropy"| node_temporal
node_risk -->|"ranks segments"| node_ranking
node_main -->|"prints results"| node_results
node_analyst -->|"explores records"| node_exploration
node_analyst -->|"reviews cleaning"| node_cleaning
node_analyst -->|"examines risk"| node_risknotebook
node_analyst -->|"reviews analysis"| node_analysis

click node_dataset "https://github.com/souvik-dey-2029/margganit/blob/main/data/ETP_4_New_Data_Accidents.csv"
click node_loader "https://github.com/souvik-dey-2029/margganit/blob/main/src/data_loader.py"
click node_preprocessing "https://github.com/souvik-dey-2029/margganit/blob/main/src/preprocessing.py"
click node_validation "https://github.com/souvik-dey-2029/margganit/blob/main/src/preprocessing.py"
click node_risk "https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py"
click node_concentration "https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py"
click node_severity "https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py"
click node_temporal "https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py"
click node_ranking "https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py"
click node_main "https://github.com/souvik-dey-2029/margganit/blob/main/src/main.py"
click node_results "https://github.com/souvik-dey-2029/margganit/blob/main/src/main.py"
click node_exploration "https://github.com/souvik-dey-2029/margganit/blob/main/notebook/01_data_exploration.ipynb"
click node_cleaning "https://github.com/souvik-dey-2029/margganit/blob/main/notebook/02_numpy_cleaning.ipynb"
click node_risknotebook "https://github.com/souvik-dey-2029/margganit/blob/main/notebook/03_risk_engine.ipynb"
click node_analysis "https://github.com/souvik-dey-2029/margganit/blob/main/notebook/04_analysis.ipynb"

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,node_loader,node_preprocessing,node_validation toneBlue
class node_risk,node_concentration,node_severity,node_temporal,node_ranking toneAmber
class node_main,node_results toneMint
class node_exploration,node_cleaning,node_risknotebook,node_analysis toneRose
class node_analyst toneIndigo
```

## Components

### Data preparation

- [Accident CSV](https://github.com/souvik-dey-2029/margganit/blob/main/data/ETP_4_New_Data_Accidents.csv): `data/ETP_4_New_Data_Accidents.csv`
- [CSV loader](https://github.com/souvik-dey-2029/margganit/blob/main/src/data_loader.py): `src/data_loader.py`
- [Dedup and features](https://github.com/souvik-dey-2029/margganit/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Feature validation](https://github.com/souvik-dey-2029/margganit/blob/main/src/preprocessing.py): `src/preprocessing.py`

### Risk analytics

- [Segment risk engine](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py): `src/risk_engine.py`
- [Spatial concentration](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py): `src/risk_engine.py`
- [Adjusted severity](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py): `src/risk_engine.py`
- [Temporal concentration](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py): `src/risk_engine.py`
- [Composite ranking](https://github.com/souvik-dey-2029/margganit/blob/main/src/risk_engine.py): `src/risk_engine.py`

### Analysis runtime

- [Analysis runner](https://github.com/souvik-dey-2029/margganit/blob/main/src/main.py): `src/main.py`
- [Printed top segments](https://github.com/souvik-dey-2029/margganit/blob/main/src/main.py): `src/main.py`

### Exploratory analysis

- [Data exploration](https://github.com/souvik-dey-2029/margganit/blob/main/notebook/01_data_exploration.ipynb): `notebook/01_data_exploration.ipynb`
- [NumPy cleaning](https://github.com/souvik-dey-2029/margganit/blob/main/notebook/02_numpy_cleaning.ipynb): `notebook/02_numpy_cleaning.ipynb`
- [Risk analysis](https://github.com/souvik-dey-2029/margganit/blob/main/notebook/03_risk_engine.ipynb): `notebook/03_risk_engine.ipynb`
- [Results and plots](https://github.com/souvik-dey-2029/margganit/blob/main/notebook/04_analysis.ipynb): `notebook/04_analysis.ipynb`

### Other components

- **Analyst**

## Connections

- Analyst → Analysis runner: runs analysis (evidence: `README.md`)
- Accident CSV → CSV loader: loaded from (evidence: `README.md`)
- Analysis runner → CSV loader: loads data (evidence: `src/main.py`)
- Analysis runner → Dedup and features: preprocesses data (evidence: `src/main.py`)
- Dedup and features → Feature validation: builds features (evidence: `src/preprocessing.py`)
- Analysis runner → Feature validation: validates matrix (evidence: `src/main.py`)
- Analysis runner → Segment risk engine: calculates risk (evidence: `src/main.py`)
- Segment risk engine → Spatial concentration: calculates counts (evidence: `src/risk_engine.py`)
- Segment risk engine → Adjusted severity: adjusts severity (evidence: `src/risk_engine.py`)
- Segment risk engine → Temporal concentration: calculates entropy (evidence: `src/risk_engine.py`)
- Segment risk engine → Composite ranking: ranks segments (evidence: `src/risk_engine.py`)
- Analysis runner → Printed top segments: prints results (evidence: `src/main.py`)
- Analyst → Data exploration: explores records (evidence: `README.md`)
- Analyst → NumPy cleaning: reviews cleaning (evidence: `README.md`)
- Analyst → Risk analysis: examines risk (evidence: `README.md`)
- Analyst → Results and plots: reviews analysis (evidence: `README.md`)
