README.md

---
license: mit
library_name: xgboost
tags:
  - tabular-regression
  - traffic-prediction
  - geospatial
  - xgboost
metrics:
  - r2
---

# Flipkart Gridlock 2.0 — Spatial Traffic Demand Model

An `XGBRegressor` checkpoint (native XGBoost JSON format) trained for the
**Flipkart Gridlock 2.0** traffic demand prediction competition. Predicts a
0–1 traffic demand score for a given geohash location and 15-minute time
slot.

Code, feature engineering, and training pipeline: [github.com/adarshcod30/Flipkart-Gridlock-2.0](https://github.com/adarshcod30/Flipkart-Gridlock-2.0)

## Why this lives here instead of on GitHub

The repo's git history originally shipped a much larger (148MB), differently
trained checkpoint that GitHub's 100MB file-size limit rejects outright — and
that checkpoint was trained on a feature set that didn't even match the
inference code shipped alongside it (see the GitHub repo's `docs/APPROACH.md`
for the full story). This is the retrained, verified, and correctly-matched
replacement: small enough to version normally, and its accuracy is backed by
real cross-validation rather than a bare leaderboard number.

## Model details

- **Architecture:** XGBoost gradient-boosted trees (`max_depth=6`, `n_estimators=600`, `learning_rate=0.05`, L1/L2 regularized)
- **Input:** 109 features — decoded lat/lon, cyclical time index, a 96-slot day-48 historical demand profile per geohash, plus road/vehicle/weather covariates
- **Output:** predicted `demand` ∈ [0, 1]
- **Training data:** 7,872 day-49 rows from the competition's `train.csv` (day 48 is used only as a historical-profile feature, never trained on directly, to avoid leaking a row's own label into its own inputs)

## Performance

5-fold cross-validated R² on the training rows:

| Fold | R² |
|---|---|
| 1 | 0.9589 |
| 2 | 0.9608 |
| 3 | 0.9578 |
| 4 | 0.9518 |
| 5 | 0.9593 |
| **Mean ± std** | **0.9577 ± 0.0031** |

Full fold-by-fold output: `metrics.json` in this repo.

## Usage

```python
from huggingface_hub import hf_hub_download
from xgboost import XGBRegressor

model_path = hf_hub_download(repo_id="adarshcod30/flipkart-gridlock-2.0", filename="spatial_model.json")
model = XGBRegressor()
model.load_model(model_path)

# Feature order and construction must match src/gridlock/features.py
# in the GitHub repo (ALL_FEATURES) — this checkpoint has no meaning
# outside that exact 109-feature pipeline.
predictions = model.predict(X)
```

## Limitations

- Trained on exactly two days of one competition's traffic data (days 48–49); not a general-purpose traffic model.
- The 96-column historical profile feature requires day-48 demand data for the same geohash set — it will not generalize to unseen cities or geohash grids without rebuilding that profile from new historical data.