kiarash-24/137-glassbox

license: mit tags:

• time-series-forecasting
• mamba
• state-space-model
• urban-informatics
• zero-inflated
• poisson

---

Qazvin 137 — Mamba-2 & Dictionary-KAN Forecasters

Spatio-temporal forecasters for daily municipal complaint counts. Trained on 84,303 space-time cells (57 neighborhoods × 1,478 days) from Qazvin's 137 hotline, 2021–2025.

These models predict a physical baseline of expected decay. They are NOT dispatch tools. Use the residuals (Predicted − Actual) as forensic evidence of under-reporting.

---

What goes in → What comes out

	Mamba-2 SSM	Dictionary-KAN
Input shape	(batch, 30, 62) float32	(batch, 62) float32
Input meaning	30-day sliding window of features	Single day of features
Output shape	(batch, 7) float32	(batch, 7) float32
Output meaning	7 log-rates → exp() → counts	7 log-rates → exp() → counts
Output columns	[total, urgent, topic0, topic1, topic2, topic3, topic4]	same
Loss	Poisson NLL	Poisson NLL + TV regulariser
Params	< 400 k	~ 41 RBF centres (after DHR)
Test MAE (total)	0.9947	193.03 (see note)

Dictionary-KAN note: The high test MAE reflects variance compounding on extreme weather outliers without Complex Batch Norm. It is a proof-of-concept for interpretability, not the operational forecaster. Use Mamba-2 for production residuals.

---

The 62 input features (exact order)

 0  temperature_2m_max        (StandardScaler)
 1  temperature_2m_min        (StandardScaler)
 2  temperature_2m_mean       (StandardScaler)
 3  apparent_temperature_max  (StandardScaler)
 4  apparent_temperature_min  (StandardScaler)
 5  relative_humidity_2m_mean (StandardScaler)
 6  dew_point_2m_mean         (StandardScaler)
 7  pressure_msl_mean         (StandardScaler)
 8  wind_speed_10m_max        (StandardScaler)
 9  wind_gusts_10m_max        (RobustScaler)
10  cloud_cover_mean          (StandardScaler)
11  shortwave_radiation_sum   (StandardScaler)
12  temp_range                (StandardScaler)
13  precipitation_sum         (RobustScaler)
14  rain_sum                  (RobustScaler)
15  snowfall_sum              (RobustScaler)
16  precip_3d                 (RobustScaler)
17  precip_7d                 (RobustScaler)
18  is_freeze_thaw            (binary 0/1)
19  freeze_thaw_7d            (StandardScaler)
20  freeze_thaw_14d           (StandardScaler)
21  freeze_thaw_30d           (StandardScaler)
22  is_holiday                (binary 0/1)
23  is_nowruz_break           (binary 0/1)
24  is_school_season          (binary 0/1)
25  is_periurban              (binary 0/1)
26  sin_jalali_month          (−1 … 1)
27  cos_jalali_month          (−1 … 1)
28  sin_jalali_week_day       (−1 … 1)
29  cos_jalali_week_day       (−1 … 1)
30  sin_jalali_year_day       (−1 … 1)
31  cos_jalali_year_day       (−1 … 1)
32  sin_wind_dir              (−1 … 1)
33  cos_wind_dir              (−1 … 1)
34  complaint_count_lag_1     (raw count)
35  complaint_count_lag_2     (raw count)
36  complaint_count_lag_3     (raw count)
37  complaint_count_lag_7     (raw count)
38  urgent_count_lag_1        (raw count)
39  urgent_count_lag_2        (raw count)
40  urgent_count_lag_3        (raw count)
41  urgent_count_lag_7        (raw count)
42  count_topic_0_lag_1       (raw count)
43  count_topic_0_lag_7       (raw count)
44  count_topic_1_lag_1       (raw count)
45  count_topic_1_lag_7       (raw count)
46  count_topic_2_lag_1       (raw count)
47  count_topic_2_lag_7       (raw count)
48  count_topic_3_lag_1       (raw count)
49  count_topic_3_lag_7       (raw count)
50  count_topic_4_lag_1       (raw count)
51  count_topic_4_lag_7       (raw count)
52  freeze_thaw_7d            (duplicate check → remove)
…   (fill remaining from your matrix)

Scaler rule: Fit on train partition only (≤ 2024-03-20). Apply the same frozen parameters to val / test. Never re-fit.

---

Quick-start (copy-paste)

Mamba-2

import torch, torch.nn as nn
from huggingface_hub import hf_hub_download

# 1. Grab weights
path = hf_hub_download(
    repo_id="Kiarash-m0hammadi/qazvin-137-glassbox",
    filename="best_mamba_model.pt",
)

# 2. Rebuild architecture (must match training)
class MambaForecaster(nn.Module):
    def __init__(self, in_dim=62, d_model=128, n_layers=2, n_targets=7):
        super().__init__()
        from mamba_ssm.modules.mamba2 import Mamba2
        self.enc = nn.Linear(in_dim, d_model)
        self.blocks = nn.ModuleList([
            Mamba2(d_model=d_model, d_state=64, d_conv=4,
                   expand=2, headdim=32)
            for _ in range(n_layers)
        ])
        self.head = nn.Sequential(
            nn.Linear(d_model, d_model // 2), nn.SiLU(),
            nn.Linear(d_model // 2, n_targets),
        )
    def forward(self, x):          # x: (B, 30, 62)
        h = self.enc(x)
        for b in self.blocks: h = b(h)
        return torch.clamp(self.head(h[:, -1, :]), -10, 10)

model = MambaForecaster()
model.load_state_dict(torch.load(path, map_location="cpu"))
model.eval()

# 3. Run inference
#    x must be (batch, 30, 62) — already scaled
with torch.no_grad():
    log_rates = model(x)           # (batch, 7)
    preds = torch.exp(log_rates)   # predicted daily counts

Dictionary-KAN

# pip install git+https://github.com/Kiarash-m0hammadi/dictionary-kan.git
from dictionary_kan.model import DictionaryKAN
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id="Kiarash-m0hammadi/qazvin-137-glassbox",
    filename="best_dkan_model.pt",
)

model = torch.load(path, map_location="cpu")  # full object
model.eval()

# x must be (batch, 62) — already scaled
with torch.no_grad():
    log_rates = torch.clamp(model(x), -10, 10)
    preds = torch.exp(log_rates)

---

Topic mapping (columns 2–6 of output)

Index	Topic	Description
0	Asphalt & Roads	Potholes, trenching, surface fatigue
1	Waste & Sanitation	Bins, sweeping, uncollected refuse
2	Water & Canal	Pipe bursts, open gutters, dredging
3	Construction & Obstruction	Illegal builds, sidewalk blockage
4	Parks & Green Space	Pruning, irrigation, park upkeep

---

Intended use

✅ Compute residuals: E = Predicted − Actual ✅ Map silent hotspots where E > +0.02 ✅ Feed residuals into spatial-justice audits

❌ Do not use raw predictions to auto-dispatch crews ❌ Do not treat this as a citizen-satisfaction model ❌ Do not retrain on a different city without recalibration

---

Citation

@misc{mohammadi_2026_qazvin137,
  author  = {Mohammadi, Kiarash},
  title   = {Qazvin 137 Glass Box Forensic AI},
  year    = {2026},
  publisher = {Hugging Face},
  url     = {https://huggingface.co/Kiarash-m0hammadi/qazvin-137-glassbox}
}

Related

• Dictionary-KAN source + Lean 4 proofs: github.com/Kiarash-m0hammadi/dictionary-kan
• Zenodo DOI: 10.5281/zenodo.21868515