Global Fire Intelligence System

Quick start

1. Activate conda: conda activate ./.conda
2. Start the UI: python scripts/run_webapp.py
3. Open http://127.0.0.1:5050
4. Default AOI is Kuwait–Basra corridor (best FIRMS + OSM overlap in the current data).

cd /Volumes/Projects/FIRMS_Analytics
conda activate ./.conda
python scripts/run_webapp.py
# map  → http://127.0.0.1:5050
# docs → http://127.0.0.1:5050/docs

Using the map

• Area of interest — switch Persian Gulf, Kuwait–Basra, California, or global sample.
• Layers — toggle FIRMS hotspots, OSM industrial/power, and AOI outline.
• Context filters — wildfire candidate, known industrial, unmapped persistent, ocean/coastal review.
• Date range — dual sliders filter by acquisition date (from → to).
• Open in NASA FIRMS — official FIRMS map centered on the same AOI for comparison.
• Click a point — FRP, confidence, product, ocean flag, OSM match.

Marker color = triage context; size scales roughly with FRP (fire radiative power). Teal markers are OSM industrial/power features from a local Overpass cache.

Data sources

Pipeline commands

# Download global NRT CSVs (no MAP_KEY needed for public 24h files)
python scripts/download_firms.py --windows 24h

# Pilot + global summary (Persian Gulf industrial corridor)
python scripts/run_pipeline.py --mode both --skip-download --aoi persian_gulf

# Analyst package (markdown + top alerts CSV)
python scripts/make_analyst_package.py

# Tests
pytest

Outputs land under data/processed/ and output/ (gitignored). After re-running the pipeline, use Reload data on the map (or restart the server).

Important caveats

• Hotspots are thermal anomalies, not burned acreage or fire perimeters.
• Industrial heat is an imperfect utilization proxy (load, efficiency, weather, view angle).
• Ocean / coastal candidates (flares, ships) need analyst review.
• Context labels are triage aids, not ground truth.

Project plan (PDF)

Management one-pager describing the concept, data stack, deliverables, and ~30-hour pilot plan:

More documentation in the repo

• README.md — setup and commands
• AGENTS.md — conventions for AI/human contributors
• PROJECT_LOG.md — what was tried, what worked
• docs/data_dictionary.md — column definitions
• docs/results_snapshot.md — recent pilot numbers

Deploy

Not a static site. Quick EC2 + HTTP today: docs/deploy_ec2_quick.md (FIRMS_HOST=0.0.0.0). Later HTTPS/domain: docs/deploy_aws.md.

Cloud coverage statistics

Separate page (main map unchanged): /cloud-stats. Data from Open-Meteo historical reanalysis (ERA5) sample points per region.

python scripts/download_cloud.py

Multi-year / global archive

Yes, NASA has years of global hotspots (MODIS from ~2000, VIIRS S-NPP from ~2012). Our live map uses only free NRT files (24h–7d). Longer history needs a free FIRMS MAP_KEY and chunked API downloads (max 5 days per request).

export FIRMS_MAP_KEY=your_key
# dry-run a year plan (no download)
python scripts/download_archive.py --source VIIRS_SNPP_SP \
  --start 2024-01-01 --end 2024-12-31 --area world --dry-run
# smaller pilot year first:
python scripts/download_archive.py --source VIIRS_SNPP_SP \
  --start 2024-01-01 --end 2024-12-31 --area 47.8,29.8,50.2,31.6

Details and size warnings: docs/archive_data.md. Global year ≈ multi‑GB.

Admin · download health

Every FIRMS download is logged to logs/download_events.jsonl (success, skip, failure, bytes, sha256, duration). Review at /admin.

For hourly refresh (later production cadence):

python scripts/scheduled_download.py --force
# cron: 0 * * * *  …/scheduled_download.py --force >> logs/cron_download.log 2>&1

Streaming ingest is planned; it will emit the same event schema (stream_tick) so admin stats stay consistent.

Current stack status

• Works: global FIRMS download, normalize, Gulf/Kuwait pilot + OSM join, map UI, analyst package, download event log + admin stats, cloud-stats page
• Next: real land mask, denser cloud grids, multi-week pattern-of-life, FIRMS MAP_KEY area API, hourly cron, streaming worker
• Interesting TODO: correlate X/OSINT posts with FIRMS (e.g. Ukraine/Russia, Iran) — see docs/TODO.md