# Petrel Aridity Index Layer — v0.1 Global ML

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

Long-term water-balance dryness at **native ~28 km (0.25°)** global. This Layer
ships three rasters: the continuous aridity index P/PET, the UNEP 5-class
classification, and a 90% block-bootstrap confidence interval on the index. It
is a byproduct of Petrel's drought v2 pipeline (same ERA5 record) and feeds the
Petrel Drought Hazard, agriculture / ecosystem screening, and downstream
fire-weather work.

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

| File | Description | Units / range | Dtype | NoData |
|---|---|---|---|---|
| `aridity_index_0p25deg.tif` | Long-term mean P/PET | dimensionless, 0–4 | uint16 | 65535 |
| `aridity_class_0p25deg.tif` | UNEP 5-class classification | class code 1–5 | uint8 | 0 |
| `aridity_index_ci_0p25deg.tif` | 90% CI half-width on the index | dimensionless, 0–1 | uint16 | 65535 |

Each file is global at 0.25° (~28 km), EPSG:4326, 1440 × 721 pixels, 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` (index/CI) / `0` (class) is NoData (ocean, Antarctica,
unscored cells).

**Native resolution is ~28 km — this is not a 90 m product.** The ERA5
climatology that drives it is 0.25°; interpolating up would add storage, not
skill (same native-resolution decision as the Petrel ignition Layer). Consumers
that need it on a finer grid (e.g. the drought pipeline) resample on read.

## Reading the values (important)

The aridity index is **P/PET — precipitation over potential evapotranspiration**.
It runs the intuitive way for a *water balance* but the counter-intuitive way
for the word "aridity":

- **Low P/PET = dry.** Hyper-arid deserts sit near 0 (Sahara ≈ 0.006).
- **High P/PET = wet.** Humid tropics exceed 1 (Amazon ≈ 1.7, i.e. rainfall
  outstrips evaporative demand).
- The UNEP classes run **hyper-arid (1) → humid (5)** as P/PET rises.

So a *high* index value means *low* aridity. The `aridity_class` layer removes
this ambiguity by giving the named UNEP class directly.

## UNEP class encoding (Middleton & Thomas 1997)

| Code | Class | P/PET range |
|---|---|---|
| 1 | Hyper-arid   | AI < 0.05 |
| 2 | Arid         | 0.05 ≤ AI < 0.20 |
| 3 | Semi-arid    | 0.20 ≤ AI < 0.50 |
| 4 | Dry-subhumid | 0.50 ≤ AI < 0.65 |
| 5 | Humid        | AI ≥ 0.65 |
| 0 | Ocean / masked | — |

## 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/aridity/v0.1/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/aridity/v0.1/bundle",
    headers={"X-API-Key": os.environ["PETREL_API_KEY"]},
).json()
url = {f["name"]: f["url"] for f in r["files"]}["aridity_index_0p25deg.tif"]

lat, lon = 30.06, 31.24                         # Cairo
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"aridity index P/PET: {raw * scale:.3f}")
```

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

## Documentation

| Document | Purpose |
|---|---|
| [`methodology.md`](methodology.md) | How the index, class, and CI are built |
| [`model_card.md`](model_card.md) | Intended use, inputs, limitations |
| [`data_sources.md`](data_sources.md) | All input datasets with citations + licenses |
| [`validation_report.md`](validation_report.md) | Validation status (v0.1: 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 Aridity Index Layer v0.1 — Global ML.
https://petreldata.io/layers/aridity/v0.1
```

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

## Known limitations (read before using)

- **v0.1 uses Thornthwaite (temperature-only) PET.** This lets the index span
  the full ERA5 1940–2024 record but is less physical than Penman-Monteith,
  which needs post-1991 humidity + wind. A Penman-Monteith variant is the
  flagged v0.2 item. See [`methodology.md`](methodology.md).
- **~28 km cells** aggregate whole landscapes; not for parcel- or field-level
  decisions.
- **A high index means low aridity** — see *Reading the values* above.
- **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/aridity_layer.yaml`,
  promoted via the canonical Petrel postprocess chain)
- **STAC item:** [`aridity_v0.1_global_ml_stac_item.json`](aridity_v0.1_global_ml_stac_item.json)