# Petrel Aridity Index Layer v0.1 — Methodology

## Data pipeline

```
    ERA5 monthly temperature 1940-2024   (Copernicus / ECMWF)
    ERA5 monthly precipitation 1940-2024 (Copernicus / ECMWF)
                              │
                              ▼
            Thornthwaite 1948 monthly PET
                              │
                              ▼
      long-term mean P / PET  per 0.25° cell         ── aridity_index
                              │
                              ▼
      UNEP 5-class thresholds (Middleton-Thomas 1997) ── aridity_class
                              │
                              ▼
     block-bootstrap by year, n=500, 90% CI           ── aridity_index_ci
                              │
                              ▼
      emit native 0.25° global GeoTIFF (−180..180, north-up)
                              │
                              ▼
      coast_clip via petrelml.utils.coast_clip (gshhg_f, all_touched)
                              │
                              ▼
      compact uint16 / uint8 reencode with PETREL_SCALE tag
                              │
                              ▼
      GeoTIFF COG w/ overviews [2, 4, 8, 16, 32, 64]
```

**Native resolution — no downscale.** v0.1 ships at the ERA5 grid (0.25°,
~28 km). The index is a smooth water-balance climatology; a 90 m rendering
would be pure interpolation and would misrepresent the product's true
information content. The promote pipeline consumes the native raster directly
via its `source_global_raster` fast-path (no coastal-dilation / bilinear
downscale stage — those exist to protect narrow coastal pixels when
downscaling, and are moot at native resolution). Ocean is removed by the
canonical `coast_clip` step, not by resampling.

## PET method — Thornthwaite (T-only)

We use Thornthwaite 1948 monthly PET because it needs only 2 m temperature —
matching the full 1940–2024 backfill of ERA5's temperature record.
Penman-Monteith would be higher-fidelity but ERA5 humidity + wind reach back
only to 1991; using P-M would truncate the record to ~34 years and defeat the
85-year foundation. Thornthwaite is known to overestimate PET in humid warm
climates and underestimate it in arid ones; the resulting index is best read
as a **relative** dryness ranking, corroborated by the UNEP class thresholds
that the global community already calibrates against Thornthwaite-family PET.

A v0.2 with Penman-Monteith PET (on a 1991–2024 record, or once the humidity +
wind backfill lands) is on the roadmap.

## Aridity index — long-term ratio-of-sums

Per cell:

```
    AI = sum_over_time(P) / sum_over_time(PET)
```

Both sums are over the full 85-year record (1020 monthly values). This is the
UNEP convention (long-term mean water balance), not an event-based dryness
metric. AI runs from ~0 in hyper-arid deserts (PET ≫ P) to >1 in the humid
tropics (P > PET). A handful of cold, high-latitude cells where Thornthwaite
PET → 0 produce very large AI (the field's p99 ≈ 27, max ≈ 487); these are
capped for display and encoding by `cap_physical = 4.0` — everything ≥ 4 stores
as "very humid" and is already class 5 (humid) in the classification.

## UNEP class thresholds

From Middleton & Thomas (1997), *World Atlas of Desertification*:

| Class | P/PET range |
|---|---|
| Hyper-arid   | AI < 0.05 |
| Arid         | 0.05 ≤ AI < 0.20 |
| Semi-arid    | 0.20 ≤ AI < 0.50 |
| Dry-subhumid | 0.50 ≤ AI < 0.65 |
| Humid        | AI ≥ 0.65 |

The classification is computed on the native grid from the continuous index
(no resampling), so class boundaries are exact — no nearest-neighbour blur.

## Bootstrap CI

Uncertainty in the long-term mean is quantified by a block-bootstrap:

1. Draw `n_boot=500` samples with replacement from the 85 available years
   (block size = 1 year, preserving the annual seasonal cycle).
2. Recompute AI for each draw → ensemble of 500 AI grids.
3. Per cell, take the (q95 − q5) / 2 half-width as the 90% CI.

Interpretation: a cell with AI = 0.15 ± 0.03 (half-width) is confidently arid;
a cell with AI = 0.19 ± 0.05 straddles the arid / semi-arid boundary. The
global median CI half-width is small (< 0.05) — the 85-year record constrains
the long-term mean tightly almost everywhere; larger CIs flag regions with
strong interannual precipitation variability or trends.

## Coastline masking

The canonical `coast_clip` step (GSHHG-f full-resolution shoreline,
`all_touched=True`) removes ocean cells after the native raster is written.
Any 0.25° cell touching real land keeps its value; open ocean and — by Petrel
standard — Antarctica (GSHHG L1 only) return NoData. Because the product ships
at its native grid, there is no coarse-to-fine coastal-hole regression class
here (the Carolina-Beach failure mode is a downscaling artifact); the audit
still verifies coastal cells resolve to data and ocean/Antarctica resolve to
NoData.

## Sanity checks the COG must pass (promote audit)

1. **PETREL_COAST_CLIP + PETREL_SCALE tags present** — enforces the canonical
   mask + encoding steps ran.
2. **Orientation / sign** — hyper-arid belts read low (Sahara, Rub al Khali,
   Atacama < 0.20) and humid tropics read high (Singapore, Amazon > 0.65).
3. **Mask correctness** — Antarctica and open ocean are NoData; coastal cells
   (e.g. Carolina Beach NC) resolve to data.
4. **UNEP class histogram** — broadly consistent with CGIAR-CSI global tallies
   (roughly: a few % hyper-arid, ~10–20% arid/semi-arid, majority humid on
   land; Thornthwaite PET shifts these vs Penman-Monteith references).

## Versioning

- `v0.1` — Thornthwaite PET on ERA5 1940–2024, native 0.25°. First shipped.
- `v0.2` — Penman-Monteith PET (1991–2024, or once humidity + wind backfill
  lands); adds Δ vs v0.1 over the overlap period. Candidate: a per-pixel
  Thornthwaite-vs-PM disagreement layer.
- `v0.3` — Non-stationary AI (rolling 30-yr windows) for climate-drift
  diagnostics.