You can deploy this model and start earning money today!

kiarash-24/
137-glassbox

Name: 137-glassbox
Availability: InStock

Views

No views yet

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)

text

temperature_2m_max        (StandardScaler)
temperature_2m_min        (StandardScaler)
temperature_2m_mean       (StandardScaler)
apparent_temperature_max  (StandardScaler)
apparent_temperature_min  (StandardScaler)
relative_humidity_2m_mean (StandardScaler)
dew_point_2m_mean         (StandardScaler)
pressure_msl_mean         (StandardScaler)
wind_speed_10m_max        (StandardScaler)
wind_gusts_10m_max        (RobustScaler)
cloud_cover_mean          (StandardScaler)
shortwave_radiation_sum   (StandardScaler)
temp_range                (StandardScaler)
precipitation_sum         (RobustScaler)
rain_sum                  (RobustScaler)
snowfall_sum              (RobustScaler)
precip_3d                 (RobustScaler)
precip_7d                 (RobustScaler)
is_freeze_thaw            (binary 0/1)
freeze_thaw_7d            (StandardScaler)
freeze_thaw_14d           (StandardScaler)
freeze_thaw_30d           (StandardScaler)
is_holiday                (binary 0/1)
is_nowruz_break           (binary 0/1)
is_school_season          (binary 0/1)
is_periurban              (binary 0/1)
sin_jalali_month          (−1 … 1)
cos_jalali_month          (−1 … 1)
sin_jalali_week_day       (−1 … 1)
cos_jalali_week_day       (−1 … 1)
sin_jalali_year_day       (−1 … 1)
cos_jalali_year_day       (−1 … 1)
sin_wind_dir              (−1 … 1)
cos_wind_dir              (−1 … 1)
complaint_count_lag_1     (raw count)
complaint_count_lag_2     (raw count)
complaint_count_lag_3     (raw count)
complaint_count_lag_7     (raw count)
urgent_count_lag_1        (raw count)
urgent_count_lag_2        (raw count)
urgent_count_lag_3        (raw count)
urgent_count_lag_7        (raw count)
count_topic_0_lag_1       (raw count)
count_topic_0_lag_7       (raw count)
count_topic_1_lag_1       (raw count)
count_topic_1_lag_7       (raw count)
count_topic_2_lag_1       (raw count)
count_topic_2_lag_7       (raw count)
count_topic_3_lag_1       (raw count)
count_topic_3_lag_7       (raw count)
count_topic_4_lag_1       (raw count)
count_topic_4_lag_7       (raw count)
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

python

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

python

# 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

bibtex

@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}
}

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

kiarash-24/137-glassbox