# Petrel Ignition Density Layer — v0.3 Global ML

**A free Petrel Layer for non-commercial use.** Account required, distributed via API.

Where fires start — not how they spread. This Layer ships three global rasters
at **native ~5 km (0.05°)**: an anthropic ignition susceptibility, a physical
a lightning-ignition relative index, and a combined total ignition propensity. It feeds
the ignition sampler of the Petrel Wildfire Hazard (Cell2Fire), and is useful
standalone for landscape-scale wildfire risk screening, prescribed-burn
planning, and conservation risk assessment.

## Layers (3 × ~5 km global GeoTIFF)

| File | Description | Units / range | Dtype | NoData |
|---|---|---|---|---|
| `ignition_density_anthro_0p05deg.tif` | Anthropic ignition susceptibility — P(fire \| human context) | probability, 0–1 | uint16 | 65535 |
| `ignition_density_lightning_0p05deg.tif` | Lightning ignition relative index — LIS/OTD flash climatology × per-Köppen p(ignition\|flash), normalised by the global maximum | relative index (0–1) | uint16 | 65535 |
| `ignition_density_total_0p05deg.tif` | Total ignition propensity — 1 − (1−P_anthro)·exp(−l/l₀), l₀ = 0.220418 (see `methodology.md`) | **relative** propensity, 0–1 | uint16 | 65535 |

Each file is global at 0.05° (~5 km), EPSG:4326, 7200 × 2900 pixels spanning
60° S – 84° N, internally tiled with overviews, coast-clipped to the GSHHG-f
full-resolution shoreline. Recover physical values by multiplying the stored
integer by the `PETREL_SCALE` metadata tag; `65535` is NoData (ocean,
Antarctica, and unscored cells).

**Native resolution is ~5 km — this is not a 90 m product.** The drivers
(LIS/OTD at 0.5°, GHSL at 1 km, HYDE at 5′) do not support finer output;
interpolating up would add storage, not skill. The Petrel wildfire pipeline
resamples this Layer onto its 90 m fuel grid on read.

## Reading the values (important)

- **`anthro`** is the probability of observed fire presence given the human +
  biome context of a cell — it is a susceptibility, not a count.
- **Aggregating `anthro` — it is NOT additive.** Because it is a per-cell
  *probability*, summing or averaging it over an area is not a meaningful
  quantity. To aggregate:
  1. Invert the Poisson presence relation (`P = 1 − e^(−λ)`) to expected
     occurrences: **`λ = −ln(1 − P)`**.
  2. **Mind the time base.** The label is FIRMS MODIS+VIIRS fire *presence*
     over **2015–2023**, so `λ` is expected **detected fires per cell over that
     9-year record** — divide by 9 for an annual rate. They are *detected*
     fires, not ignitions: the figure inherits the MODIS/VIIRS detection floor
     and misses small or short-lived fires.
  3. **Aggregate area-weighted, not as a mean of densities.** Sum `λ` over the
     region and divide by the region's total area. A 0.05° cell shrinks by
     cos(lat) — roughly halving between the equator and 60° — so an unweighted
     mean of per-cell densities is biased.
  Observed range in this vintage: max `P` = 0.995437, i.e. `λ` ≤ 5.39, with no
  pile-up at the encoding ceiling. `−ln(1 − P)` diverges as `P` → 1, but that
  is not realised here; clip at `P ≤ 1 − 1e−6` if you want the guard.
- **The three bands are NOT commensurable — do not compare or ratio them.**
  `anthro` is a probability, `lightning` is a unitless relative index, and
  `total` is a relative propensity. Relating them requires a fitted per-band
  efficiency, which is exactly what the Petrel Wildfire rate model estimates
  and exactly why no anthropic-vs-lightning share is published here.
- **`lightning`** is a **relative index in [0,1]**, not a rate. Through v0.2
  it shipped labelled `events km⁻² yr⁻¹`; that label was wrong by ~3 orders
  of magnitude and was corrected in v0.3. See `RELEASE_NOTES.md`.
- **`total`** is a **relative ignition propensity in [0,1]** — the spatial
  weighting Cell2Fire's ignition sampler consumes. It is **not** "ignitions
  per year"; absolute-rate calibration is a v1.0 item. Compare cells within
  this vintage, not across vintages or against external rate datasets.

## Quick start

**Via Petrel API** (recommended — returns 1-hour presigned URLs for every
file in the bundle; `$PETREL_API_KEY` is your `tlk.…` key, free tier works):
```bash
curl -s -H "X-API-Key: $PETREL_API_KEY" \
  https://api.petreldata.io/v1/layer/ignition/v0.3/bundle \
  | jq -r '.files[] | [.url, .name] | @tsv' \
  | while IFS=$'\t' read -r url name; do curl -s "$url" -o "$name"; done
```

**Point query** in Python (with rasterio — streams the COG, no full download):
```python
import os, requests, rasterio

r = requests.get(
    "https://api.petreldata.io/v1/layer/ignition/v0.3/bundle",
    headers={"X-API-Key": os.environ["PETREL_API_KEY"]},
).json()
url = {f["name"]: f["url"] for f in r["files"]}["ignition_density_total_0p05deg.tif"]

lat, lon = 34.05, -118.24                      # Los Angeles
with rasterio.open(url) as src:
    raw = next(src.sample([(lon, lat)]))[0]
    scale = float(src.tags()["PETREL_SCALE"])
    if raw == src.nodata:
        print("no data (ocean / outside coverage)")
    else:
        print(f"total ignition propensity: {raw * scale:.3f} (relative, 0-1)")
```

See [`API_USAGE.md`](API_USAGE.md) for more snippets.

## Documentation

| Document | Purpose |
|---|---|
| [`methodology.md`](methodology.md) | How the two composers + the combination work |
| [`model_card.md`](model_card.md) | Intended use, training data, limitations |
| [`data_sources.md`](data_sources.md) | All input datasets with citations + licenses |
| [`validation_report.md`](validation_report.md) | Validation status (v0.3: qualitative) + known limitations |
| [`RELEASE_NOTES.md`](RELEASE_NOTES.md) | Client-facing version history |
| [`API_USAGE.md`](API_USAGE.md) | curl / Python / R code snippets |
| [`bulk_download_instructions.md`](bulk_download_instructions.md) | Download flow + restrictions |
| [`LICENSE.md`](LICENSE.md) | CC-BY-NC-4.0 full text |
| [`CITATION.cff`](CITATION.cff) | How to cite this dataset |

## License

**Creative Commons Attribution-NonCommercial 4.0 International** (CC-BY-NC-4.0).

You may share and adapt this Layer for non-commercial purposes with attribution.
Commercial use requires a separate license — contact licensing via https://petreldata.io/demo.

See [`LICENSE.md`](LICENSE.md) for the full text.

## Citation

```
Petrel (2026). Petrel Ignition Density Layer v0.3 — Global ML.
https://petreldata.io/layers/ignition/v0.3
```

See [`CITATION.cff`](CITATION.cff) for Citation File Format metadata.

## Known limitations (read before using)

- **v0.3 is not yet formally validated.** The spatial pattern agrees
  qualitatively with GFED fire geography and passes structural sanity checks;
  quantitative skill scoring against GFED is scheduled for v1.0. See
  [`validation_report.md`](validation_report.md).
- **`total` is relative, not absolute** — see *Reading the values* above.
- **~5 km cells** aggregate over towns, road corridors, and vegetation
  mosaics. Not suitable for parcel- or property-level decisions.
- **No per-pixel uncertainty layer ships in v0.3** (single-model GBM, no
  ensemble). An uncertainty companion is a v1.0 candidate.
- **Antarctica and latitudes above 84° N are excluded by standard**; ocean is
  NoData (GSHHG-f coast clip).

## Provenance

- **Built by:** the Petrel ML pipeline (config `configs/ignition_layer.yaml`,
  promoted via the canonical Petrel postprocess chain)
- **STAC item:** [`ignition_v0.3_global_ml_stac_item.json`](ignition_v0.3_global_ml_stac_item.json)