Model card

How AirTrace works

AirTrace starts from the Copernicus CAMS global atmospheric-composition forecast — available everywhere, but often far off at city scale — and learns how to correct it from reference-grade ground monitors. It is validated only on cities it never saw during training, explains every forecast, and estimates where the pollution comes from.

Pipeline

From a global model to a city forecast

  1. 1

    Data sources

    CAMS global composition forecast (PM2.5, PM10, dust, aerosol optical depth, CO, NO₂, SO₂, O₃), ERA5 / forecast weather, AirNow reference monitors and NASA FIRMS fires.

  2. 2

    Daily features

    Hourly data become local-day features: CAMS means, night and peak values, day-over-day change, PM2.5/PM10 and SO₂/CO ratios, wind and air stagnation, humidity, rain, temperature, season and location. Mixing height was dropped after an ablation: the weather archive lacks it before July 2024, and removing it cost no accuracy.

  3. 3

    LightGBM correction

    Gradient-boosted trees predict log(1 + PM2.5) from those features. Two quantile models (10th and 90th percentile) give an 80% prediction range.

  4. 4

    SHAP drivers

    TreeSHAP splits every prediction into feature contributions, summed into human-readable groups such as “Wind & air stagnation” or “Desert dust”.

  5. 5

    Source attribution

    A chemical-mass-balance receptor model splits eight CAMS tracers into six fixed source fingerprints by non-negative least squares; mass yields calibrated on observed PM2.5 turn them into source shares.

  6. 6

    Website

    Forecasts, drivers and sources are written as static JSON and served by GitHub Pages — no server, no tracking.

A GitHub Actions workflow re-runs steps 1–6 every 6 hours with the latest CAMS and weather forecasts.

Headline results

Better than the global model, on cities it never saw

All numbers below are computed by the training pipeline (metrics.json) with leave-location-out cross-validation.

Validation design

Tested the way it is used: on places without a monitor

Leave-location-out cross-validation

■ held-out locations   ■ training locations (one of the folds)

Monitors are grouped into spatial clusters (any two monitors closer than 150 km share a cluster, e.g. Los Angeles–Riverside or Dubai–Abu Dhabi), and each cluster is held out in turn. Every headline score on this page comes from a model that had never seen that city, or any monitor within 150 km of it — the situation of a city without a monitor.

New places and future months

The strictest check: each fold trains on the earlier months of its training clusters only and is scored on the last three months at the held-out clusters — a new place and a season the model has not seen.

How far does the correction travel?

We also held out whole countries and whole world regions, and measured monitors the model had already learned on later months. AirTrace helps most where it has learned from monitors in the same region — and most of all for the cities whose own embassy monitor it learned from before it went dark. It does not beat CAMS in a world region with no training monitor at all, which is why every city page shows a confidence level.

Model comparison

AirTrace against the baselines

Daily 24-hour PM2.5, leave-location-out cross-validation. Errors in µg/m³; bias = mean(prediction − observation). Best value per column in bold.

Accuracy

Where the correction helps

Observed vs. predicted daily PM2.5

Cross-validated predictions at held-out locations (random sample), log–log axes. Points on the diagonal are perfect; the thin lines mark a factor of 2.

Per site

Error change at every training monitor

Each dot is a reference monitor; colour shows how much AirTrace changed the mean absolute error relative to raw CAMS when that site was held out.

Explainability

What the model relies on

Global importance (share of total split gain). For each individual forecast the site shows TreeSHAP contributions grouped the same way (“Why this forecast”).

Uncertainty

Honest ranges, not just a number

Source attribution

Where the pollution comes from

A receptor model on modelled tracers: an indicative split of PM2.5 into source types, not an emissions inventory.

Limitations & responsible AI

What AirTrace cannot do

Known limitations

  • City scale, not street scale. CAMS runs on a grid tens of kilometres wide. AirTrace forecasts a city-wide 24-hour average; a busy road or a local fire can be far worse.
  • Uneven training data. The monitors are mostly in North America and in capital cities with a US embassy. Regions with few training sites (see the per-region table) have larger and less certain errors.
  • Frozen in time. The model learned from one year. Where the embassy monitors went dark, we can no longer check whether it still holds — which is why every forecast carries an 80% range and the monitor status is always shown.
  • Sources are estimates. The attribution decomposes modelled tracer patterns, so it inherits CAMS emission-inventory errors; some validation checks fail and are shown as failing.
  • Forecast skill fades with lead time. Days 4–5 depend on weather forecasts that are themselves uncertain; the ranges widen accordingly.

Responsible use

  • Not medical advice. Health messages follow the US EPA AQI guidance. Always follow official advisories from local authorities.
  • Transparent by design. Every number on this site comes from the pipeline’s JSON output; validation failures are shown, not hidden. The code and model artifacts are public.
  • No personal data. The site is static: no accounts, cookies or tracking. It only uses open environmental data.
  • Equity. The people who lost their only reference monitor are the ones who most need a trustworthy estimate. AirTrace says clearly when a number is an estimate without a ground truth nearby.
  • Light footprint. Gradient-boosted trees train and run on an ordinary CPU — no GPU is needed for training or for the forecast runs.
Data & credits

Training data and sources

Credits