docs/methodology.md

Methodology — Congestion Impact Index (CII)

Problem framing

The brief asks us to detect illegal-parking hotspots and quantify their impact on traffic flow. The dataset contains 298k+ parking-enforcement records with location, time, and violation type, but no direct traffic-speed/volume measurement. Rather than claim a flow metric we do not have, we build a transparent proxy for flow impact, derived only from enforcement data, with every weight exposed and defensible.

Pipeline

1. Clean — keep records inside the Bengaluru bounding box with valid timestamps; parse the multi-label violation_type; keep only parking- relevant violations.
2. Spatial unit — index every record to an H3 resolution-9 hexagon (~174 m edge ≈ a block / deployable patrol zone). Deterministic and map-friendly.
3. Per-cell statistics — severity-weighted volume, active-day persistence, peak-hour concentration, junction proximity.
4. CII — combine the components (below).
5. Forecast — a LightGBM model predicts next-day intensity per cell.

Severity weighting

Each violation type is weighted by how much it physically blocks moving traffic (not legal severity):

Violation	Weight	Why
Parking in a main road	1.00	blocks the carriageway
Near road crossing / traffic light	0.90	blocks turning / sightlines
Double parking	0.85	removes a live lane
Near bus-stop / school / hospital	0.70	high-churn frontage
On footpath	0.50	pushes pedestrians into the road
Wrong parking	0.50	partial obstruction
No parking	0.40	designated-clear zone

A record's severity is the max weight across its violations.

The index

For each cell, with rank-normalised components in [0, 1]:

base = 0.45·volume + 0.30·persistence + 0.25·peak_concentration
CII  = base × (1 + 0.50·junction_share)          # then scaled to 0–100

• Volume — total severity-weighted violations (how bad, weighted).
• Persistence — active days ÷ total days. Separates a chronic daily bottleneck from a one-off spike. (In this data the worst cells are active ~149/151 days.)
• Peak concentration — share of violations in commute windows (08–11, 17–20). A blockage that happens exactly at rush hour hurts flow more.
• Junction proximity — amplifies cells near junctions, where a blockage cascades upstream.

All weights live in src/config.py and can be re-tuned in seconds.

Forecast model

LightGBM regression on a (cell × day) panel. Features: cell location + junction share, calendar (day-of-week, month, weekend), and lag/rolling features (1/7/14/28-day lags, 7/28-day rolling mean & max). Target: next-day severity-weighted intensity. Validated on the final 21 days, compared against a naive "same weekday last week" baseline.