Wildfire Risk (Next-Day)

End-to-end pipeline to predict next-day wildfire risk at grid-cell level and visualize alerts on an interactive Streamlit map.

⚠️ Important: This project is for research/educational use only. It does not replace official forecasts, warnings, or agency products.

---

Contents

• Overview
• Results (current run)
• Quickstart
• How it works
• Repository layout
• Configuration
• Troubleshooting
• Data sources & attribution
• Roadmap
• Contributing
• License
• Citation

---

Overview

• Data
  • NASA FIRMS (active fire detections; NRT + archive)
  • Meteostat (daily weather: temperature, precipitation, wind, pressure)
• Model: Gradient-boosted trees (LightGBM) with time-aware (chronological) split
• Outputs: Per-cell risk scores, operating thresholds, metrics, calibration, feature importances, and a Streamlit app for exploratory visualization

---

Results (current run)

Metric	Value
ROC-AUC	0.939
PR-AUC	0.499
Brier score	0.079

Threshold suggestions (from models/thresholds.json):

• Top-10% alerts (≈0.637): P=0.202, R=0.847, F1=0.326, alerts ≈10%
• Best-F1 (≈0.937): P=0.490, R=0.514, F1=0.502, alerts ≈2.5%

Curves & calibration

---

Quickstart

0) Environment

# Create & activate a virtual environment
python -m venv .venv

# Windows PowerShell
. .venv/Scripts/Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

If LightGBM fails to install on your platform, train.py falls back to XGBoost automatically.

1) Configure

Edit src/config.py:

• REGION / BBOX: geographic extent
• GRID_DEG: grid resolution in degrees
• RECENT_DAYS: trailing window of data for training
• Path constants (already aligned to this repo)

2) Build data & features

2.1 Build grid (once per region)

python -m src.make_grid

2.2 Fetch Meteostat daily weather

python -m src.fetch_weather

2.3 Ingest FIRMS (NRT + archive CSVs in data/raw/firms_archive)

python -m src.fetch_firms

2.4 Build next-day labels from FIRMS

python -m src.build_labels

2.5 Join everything into modeling features

python -m src.make_features

3) Train, evaluate, diagnose

# Train with time-aware (chronological) split
python -m src.train

# Metrics, curves, thresholds, calibration plot/table
python -m src.evaluate

# Extra checks: feature importances, calibration CSV, etc.
python -m src.diagnostics

4) Run the UI

streamlit run ui/app_streamlit.py
# If you changed config or data:
# streamlit cache clear

The app renders an interactive heatmap, top-K risky cells, CSV downloads, and quick point-queries.

---

How it works

• Grid – tiles the configured region and stores cell centers
• Ingest – loads daily weather per station (Meteostat), maps each cell to its nearest station, and loads FIRMS detections
• Labels – counts fires per (cell, fire_date) and shifts one day back so each (cell, date) means “fire tomorrow”
• Features – seasonality (year, month, doy), dryness (no_rain, dry_streak), rolling weather (tmax_7d_mean, tavg_7d_mean, prcp_7d), and recent-fire history (fire_7d, fire_30d, fire_prev1d)
• Train – LightGBM with class balancing; last ~20% days held out for validation
• Evaluate – ROC/PR curves, calibration, and two operating thresholds (Top-10% & Best-F1)
• Serve – Streamlit map showing per-cell risk and downloadable tables

---

Repository layout

wildfire-risk/
├─ api/
│  └─ app.py                      # optional FastAPI/REST entrypoint
├─ data/
│  ├─ raw/
│  │  ├─ firms_archive/           # NASA FIRMS CSVs + Readme.txt
│  │  ├─ firms_nrt.parquet
│  │  ├─ stations.parquet
│  │  └─ weather_daily.parquet
│  └─ processed/
│     ├─ grid_cells.parquet
│     ├─ features_cell_day.parquet
│     └─ labels_cell_day.parquet
├─ models/
│  ├─ lgbm_wildfire.pkl
│  ├─ metrics.json
│  ├─ thresholds.json
│  ├─ valid_scores.parquet
│  ├─ roc_curve.png
│  ├─ pr_curve.png
│  ├─ calibration.png
│  ├─ feature_importance.csv
│  ├─ calibration.csv
│  └─ confusion_at_thresholds.json
├─ notebooks/
│  └─ EDA.ipynb
├─ src/
│  ├─ config.py
│  ├─ make_grid.py
│  ├─ fetch_weather.py
│  ├─ fetch_firms.py
│  ├─ build_labels.py
│  ├─ make_features.py
│  ├─ train.py
│  ├─ evaluate.py
│  ├─ diagnostics.py
│  └─ utils.py
└─ ui/
   └─ app_streamlit.py

---

Configuration

Key fields in src/config.py:

• REGION, BBOX: controls where the grid is built and data are filtered
• GRID_DEG: grid resolution (smaller → more cells)
• RECENT_DAYS: trailing window used for training/evaluation
• *_PARQ, MODEL_PATH, MODELS: file locations used across the pipeline

---

Troubleshooting

• ModuleNotFoundError: No module named 'src' – run from the repo root or add root to PYTHONPATH.
• Streamlit / PyDeck JSON errors – map layer expects arrays like ["lon_c", "lat_c"] and JSON-serializable values. If schema changed, run streamlit cache clear.
• Too few positives – increase RECENT_DAYS or adjust BBOX.

---

Data sources & attribution

• NASA FIRMS: https://firms.modaps.eosdis.nasa.gov/
• Meteostat: https://meteostat.net/

---

Follow each provider’s terms of use. This repo stores small, derived subsets for demo/research.

---

Roadmap

• CI workflow (lint, unit tests, scheduled data refresh)
• Dockerfile for fully reproducible runs
• Optional FastAPI service (api/app.py) with /predict endpoint
• Model card & risk considerations

---

Contributing

• Issues and PRs are welcome (even if this repo is private). In your PR, please include:
• What changed and why
• How you validated it (commands, metrics, screenshots)
• Any data or assumption caveats

---

License

No license selected yet. All rights reserved by the repository owner. If you prefer open reuse, add an MIT License:

Create LICENSE with the MIT text from https://choosealicense.com/licenses/mit/

Update this section to: Licensed under the MIT License.

Citation

If you use this work in academic or technical writing, please cite:

Sivarohitk (2025). wildfire-risk: Next-day wildfire risk prediction and visualization. GitHub repository. https://github.com/<your-user>/wildfire-risk

If you’d like, I can also add a **shield for “No License”**, a **table of badges** at the top, or a **collapsible “Details” section** for the long Quickstart steps. This version is shaped explicitly for GitHub’s renderer and matches the structure of your repo. :contentReference[oaicite:0]{index=0}
::contentReference[oaicite:1]{index=1}