Reproducibility code and data for the manuscript:
Satellite-supported daily PM2.5 mapping for Pakistan under sparse monitoring Rehan Ahmad, Mahad Naveed, and Abid Omar Pakistan Air Quality Initiative (PAQI)
This repository contains the scientific pipeline used for the manuscript, including predictor construction, support-aware temporal-dropout training, evaluation, inference, the held-out 2025 station-day validation table, and daily 0.1° gridded PM2.5 prediction outputs for 2024–2025.
The manuscript evaluates three archive-quality model settings:
- a national-predictor backbone using satellite, chemistry, and meteorology;
- a standard temporal model using recent PM2.5 history; and
- a support-aware temporal-dropout model trained to operate with and without recent local PM2.5 history.
A separate operational configuration is used by PAQI's Hawanama platform. That production configuration is documented separately and should not be used to reproduce the manuscript's primary tables and figures.
- Manuscript reproduction
- Manuscript model configurations
- Manuscript evaluation results
- Data and outputs
- Running manuscript evaluation
- Separate Hawanama operational configuration
- License and citation
| Model setting | Local-history MAE | No-history MAE |
|---|---|---|
| National-predictor backbone | 22.9 | 22.9 |
| Standard temporal model | 14.2 | 32.4 |
| Support-aware temporal dropout | 14.3 | 23.2 |
All values are in µg m⁻³ and are evaluated on the held-out 2025 station-day test set.
The held-out 2025 validation table is included under validation/
(validation/pm25_2025_station_day_validation.csv) together with the script
that rebuilds the reported metrics from it. Daily gridded 0.1° PM2.5
prediction fields for 2024–2025 are under
data/gridded_predictions_2024_2025/.
All three settings use a LightGBM estimator on a fixed 0.1° national grid (141 × 175, 24,675 cells) with a strictly temporal split: trained on 2020–2023 station-days, tuned on 2024, evaluated on the held-out 2025 test year.
- National-predictor backbone — satellite aerosol retrievals (MODIS MAIAC AOD), atmospheric composition (TROPOMI), chemistry (GEOS-CF), and meteorology (ERA5/ERA5-Land); available for every grid cell.
- Standard temporal model — adds the recent ground PM2.5-history feature block as ordinary predictors; degrades sharply where no local history exists.
- Support-aware temporal dropout — the full PM2.5-history feature block is
withheld for a random subset of training rows (dropout rate
p = 0.2, selected on the 2024 development split) so that a single estimator learns to operate both with and without recent local history.
See MODEL_CARD.md for the model card covering the relationship between the
manuscript and operational configurations.
The manuscript evaluation reports, on the held-out 2025 station-day test set:
- Support-aware model: MAE 14.3 µg m⁻³ where local PM2.5 history exists and 23.2 µg m⁻³ where it does not, versus 32.4 µg m⁻³ for the standard temporal model without history and 22.9 µg m⁻³ for the national-predictor backbone.
- Severe-episode detection: F1 at 150 µg m⁻³ rises from 0.729 to 0.838 when local history is available.
Evaluation utilities live in training/utils/, and the recorded tuning and
evaluation metrics in training/results/.
| Source | Resolution | Cadence | Variables |
|---|---|---|---|
| TROPOMI (Sentinel-5P) | ~5.5 km | Daily | NO2, SO2, CO, HCHO, O3, AAI, ALH, CH4, Cloud |
| GEOS-CF (NASA) | ~25 km | Daily | NH3 |
| MODIS AOD (MCD19A2.061) | 1 km | Daily | Optical depth @ 470 nm, 550 nm |
| ERA5 / ERA5-Land | ~31 km / ~9 km | Monthly | T2m, d2m, wind, pressure, BLH, cloud cover, humidity |
| Ground stations | Point | Hourly | PM2.5, PM10 |
See DATA.md for access terms (public inputs vs. the restricted
ground-station stream).
Included outputs:
validation/pm25_2025_station_day_validation.csv— held-out 2025 station-day validation table (anonymized station identifiers).data/gridded_predictions_2024_2025/— daily gridded 0.1° PM2.5 fields, 2024–2025.training/results/— tuning and evaluation metrics (JSON).
Trained model weights are not committed (see .gitignore); they are
distributed with the archived release (Zenodo DOI
10.5281/zenodo.20824536; see
ZENODO.md) or available on request.
# With hyperparameter tuning
python -m training.main --do_tuning --tuning_trials 25
# Without tuning
python -m training.main --no_tuning --dev_year 2024 --test_year 2025python -m inference.feature_store.run_grid_inference_from_store \
--date 2026-01-15 \
--model <path/to/model.joblib> \
--format all \
--output_dir output/Ingestion of satellite/reanalysis inputs requires NASA Earthdata, Google Earth Engine, and Copernicus CDS credentials, supplied through environment variables (no secrets are stored in this repository).
Object-store locations and credentials are read from environment variables;
code defaults are neutral placeholders, so set these to your own
infrastructure. Copy .env.example to .env and fill in the values:
| Variable | Purpose |
|---|---|
GCP_PROJECT |
Google Cloud project id |
PAQI_RAW_BUCKET |
raw satellite/station data bucket (e.g. gs://your-raw-bucket) |
PAQI_DERIVED_BUCKET |
feature-store bucket |
PAQI_LAKE_PATH |
training data-lake path |
PAQI_GEOSCF_PATTERN |
GEOS-CF baseline raster path pattern |
EARTHDATA_USERNAME / EARTHDATA_PASSWORD |
NASA Earthdata (MODIS AOD) |
CDS_API_KEY |
Copernicus CDS (ERA5) |
├── feature_engineering/ Feature computation & data lake
│ ├── feature_family/ Per-modality feature modules (MET, AOD, TROPOMI)
│ ├── feature_store/ Parquet store builders (station, grid, master)
│ └── main_feature_pipeline.py Orchestrator
│
├── inference/ Inference engine
│ └── feature_store/ Grid reader & main inference script
│ └── run_grid_inference_from_store.py
│
├── training/ Model development
│ ├── main.py Benchmark trainer (tuning + rolling CV)
│ ├── baselines/ Climatology, persistence, GEOS-CF baselines
│ ├── results/ Tuning & evaluation metrics (JSON)
│ └── utils/ Metrics, evaluation, dataset prep, trainer
│
├── extraction_and_preprocessing/ Raw data scripts & station labels
├── shared_features/ Shared feature definitions
├── scripts/ Data-lake / sync helper scripts
├── requirements.txt Dependencies
├── MODEL_CARD.md Model card (manuscript + operational configurations)
├── DATA.md Data sources and availability
├── CITATION.cff How to cite
└── LICENSE MIT
Scope note: This operational configuration is related to, but distinct from, the support-aware configuration evaluated in the manuscript. Its feature set, fitted model, evaluation sample, and reported metrics should not be used to reproduce the manuscript's Tables 7–10.
This repository is also the estimation engine behind Hawanama, PAQI's air quality intelligence platform. The cloud-deployment/orchestration code has been omitted from this public release. The operational system ingests satellite imagery, meteorological reanalysis, and ground-station observations, engineers 305 features on the regular grid covering Pakistan, and runs a LightGBM model to predict PM2.5 concentrations for every 0.1° cell (~10 km):
- Ingest raw data from TROPOMI (Sentinel-5P), GEOS-CF, MODIS AOD, ERA5/ERA5-Land, and the ground-station network
- Build per-date Parquet partitions in a grid feature store (MET, AOD, TROPOMI stages)
- Merge stages into a master feature table — one row per grid cell, 305 columns
- Predict PM2.5 with a tuned LightGBM model, masked to Pakistan's boundary
- Publish outputs as Cloud Optimized GeoTIFF (COG, with Gaussian smoothing), JSON, and CSV
Meteorological (~100 features). Core variables from ERA5/ERA5-Land (T2m, dewpoint, u/v wind at 10 m and 100 m, surface pressure, boundary layer height, cloud cover, relative humidity, specific humidity, VPD) plus temporal engineering: 1-day and 3-day lags (wind speed, BLH); 3-day and 7-day rolling statistics (wind, BLH, RH, VPD, ventilation coefficient); stagnation flags and calm-wind counts; BLH/MSLP/surface-pressure tendencies; wind-direction sin/cos encodings with 7d/14d rolling means; calendar harmonics and season flags.
TROPOMI gas columns (~160 features). For each of 10 products (NO2, SO2, CO, HCHO, O3, AAI, ALH, CH4, Cloud, NH3): robust statistics (median, mean, std, min, max, percentiles, IQR, MAD, range, CV), spatial texture (skewness, kurtosis), and multiscale gradients between 0.5°, 1°, and 2° neighborhoods.
Aerosol optical depth (~6 features). Optical depth at 470 nm and 550 nm (QA-filtered), AOD uncertainty, QA cloud mask, QA adjacency, QA AOD flags.
Calendar (~8 features). Day-of-year harmonics, heating season and burning season flags.
| Detail | Value |
|---|---|
| Model type | LightGBM |
| Features | 305 |
| Trees (n_estimators) | 12,000 |
| Max depth | 12 |
| Num leaves | 255 |
| Learning rate | 0.01 |
| Subsample | 1.0 |
| Column sample | 0.5 |
| Regularization | L2=10.0, min split gain=0.05 |
| Tuning | RandomSearch with rolling year-wise CV |
Top 10 features by importance (split count):
| Rank | Feature | Importance |
|---|---|---|
| 1 | blh_lag1d |
4,608 |
| 2 | sp |
4,561 |
| 3 | blh_lag3d |
4,509 |
| 4 | WS10_lag3d |
4,106 |
| 5 | WS10_lag1d |
3,878 |
| 6 | aai_skew |
3,474 |
| 7 | aai_delta_median_r1_r05 |
3,413 |
| 8 | WD10_cos_rm_14d |
3,205 |
| 9 | WS10_rollmin_7d |
3,180 |
| 10 | aai_delta_std_r2_r05 |
3,164 |
These are operational production-model metrics. The manuscript evaluation
reports separate numbers for the support-aware temporal-dropout experiments
(see MODEL_CARD.md and Manuscript reproduction).
Production test set (2025, Jan–Jul, n = 15,261):
| Metric | Value |
|---|---|
| MAE | 18.6 µg/m³ |
| RMSE | 28.4 µg/m³ |
| R² | 0.623 |
| Bias | +1.6 µg/m³ |
| F1 @ 150 µg/m³ | 0.528 |
Cross-validation (rolling year-wise, 2021–2024):
| Metric | Mean | Std |
|---|---|---|
| MAE | 27.7 µg/m³ | 2.4 |
| RMSE | 44.3 µg/m³ | 2.9 |
| R² | 0.658 | 0.023 |
| F1 @ 150 | 0.691 | 0.008 |
Seasonal breakdown (production test):
| Season | MAE | RMSE | R² |
|---|---|---|---|
| Winter (Nov–Feb) | 30.6 | 44.1 | 0.446 |
| Pre-monsoon (Mar–May) | 14.5 | 19.3 | 0.417 |
| Monsoon (Jun–Sep) | 11.6 | 14.7 | 0.249 |
If you use this software or data, please cite the archived software release
(see CITATION.cff; Zenodo concept DOI
10.5281/zenodo.20824536).
Code is released under the MIT License (LICENSE). Derived data products are
released under CC-BY-4.0 (see DATA.md).
See DATA.md. Public inputs are available from their providers (NASA
Earthdata, Copernicus C3S, NASA GMAO). The ground-station PM2.5 stream is
available from PAQI on reasonable request; derived, quality-controlled tables
and gridded predictions are released as a versioned data package.