# Model Card — Petrel Aridity Index Layer v0.1 Global ML

Following the Model Card framework of Mitchell et al. (2019), "Model Cards for
Model Reporting", FAccT. Note: this Layer is a **deterministic computed
climatology**, not a trained statistical model — there are no learned
parameters and no training set. The "model" is the composition Thornthwaite PET
→ long-term P/PET → UNEP thresholds. The card is retained for consistency and
because intended-use / limitation reporting is just as relevant for a derived
index.

## Model details

- **Name:** Petrel Aridity Index Layer v0.1 Global ML
- **Version:** v0.1-global-ml
- **Vintage code:** `aridity_v0.1_global_ml`
- **Release:** July 2026
- **Owner:** Petrel
- **Type:** Deterministic water-balance climatology — long-term mean P/PET from
  ERA5 (1940–2024) with Thornthwaite PET, the UNEP 5-class discretization, and a
  block-bootstrap 90% CI companion
- **Native resolution:** ~28 km (0.25°), global 60° S – 84° N — **not 90 m**
- **License:** CC-BY-NC-4.0
- **Citation:** see [`CITATION.cff`](CITATION.cff)
- **Contact:** layers@petreldata.io

## Intended use

### Primary intended uses

- A dryness / water-balance covariate for the Petrel Drought Hazard and other
  environmental screening models
- Agriculture, ecosystem, rangeland, and desertification research at regional
  to global scale
- A climate-context feature for fire-weather and vegetation work
- Teaching / cartography — the UNEP class map is a recognizable reference layer

### Out-of-scope uses

- **Parcel- or field-level assessment.** ~28 km cells aggregate whole
  landscapes.
- **Absolute PET or water-deficit accounting.** Thornthwaite PET is a
  temperature-only estimate; use a Penman-Monteith product (or Petrel aridity
  v0.2) where absolute evaporative demand matters.
- **Real-time / seasonal monitoring.** This is an 85-year climatology, not an
  updating index. For current-conditions dryness use the Petrel Drought Hazard.
- **Reading the index as "aridity magnitude" directly.** High P/PET means
  *low* aridity — use the `aridity_class` layer for the named class.

## Inputs

- **ERA5 monthly 2 m temperature 1940–2024** → Thornthwaite PET.
- **ERA5 monthly total precipitation 1940–2024** → the P numerator.
- No labels, no covariate learning. See [`data_sources.md`](data_sources.md).

## Evaluation

**v0.1 has no published quantitative skill score.** Validation to date is
qualitative: geographic agreement with the CGIAR-CSI Global Aridity Index and
UNEP desertification maps, plus structural sanity anchors (hyper-arid deserts
near 0, humid tropics > 1, plausible UNEP class distribution). A quantitative
cell-wise comparison against CGIAR-CSI is the flagged v0.2 item. See
[`validation_report.md`](validation_report.md) for exactly what was and was not
checked.

## Uncertainty

Unlike most Petrel layers, an uncertainty companion **does** ship in v0.1: the
`aridity_index_ci` layer is the 90% block-bootstrap CI half-width on the
long-term mean (resampling years). It captures sampling uncertainty in the mean
— **not** structural uncertainty from the choice of PET method, which is the
dominant error source (see limitations).

## Known biases & failure modes

| Failure mode | Surface | Status in v0.1 |
|---|---|---|
| **Thornthwaite PET bias** | Overestimates PET in humid warm climates, underestimates in arid ones; shifts absolute P/PET vs Penman-Monteith references | Documented; index is best read as a relative ranking; PM is the v0.2 fix |
| **Polar PET → 0 blow-up** | Cold high-latitude cells give divide-by-tiny P/PET (up to ~487) | Capped at 4.0 for encoding/display; already class 5 (humid) |
| **Index sign confusion** | High value = low aridity (P/PET convention) | Documented in README; `aridity_class` avoids it |
| **Coarse cells** | ~28 km aggregates deserts abutting oases, coasts, orography | Documented; not for local use |
| **CI is sampling-only** | The bootstrap CI reflects interannual variability, not PET-method or reanalysis error | Documented; structural uncertainty not quantified in v0.1 |
| **Coverage** | Ocean NoData; Antarctica excluded (GSHHG-f L1) | By standard |

## Ethical considerations

- **No PII.** All inputs are gridded reanalysis fields; the product identifies
  no properties, parcels, or people.
- **Derived-product uncertainty.** ERA5 is itself a modelled reanalysis; v0.1
  inherits its uncertainties, compounded by the Thornthwaite approximation.
- **Non-commercial license.** Commercial environmental decisions should involve
  explicit human review, not automated reliance on an unvalidated v0.1
  research-grade layer — commercial licensing (via https://petreldata.io/demo)
  exists partly to enforce that conversation.

## Caveats & recommendations

- Prefer the `aridity_class` layer for a categorical answer; use the continuous
  index for gradients, remembering high = wet.
- Consult `aridity_index_ci` before trusting a near-threshold class assignment.
- If you need absolute evaporative demand, wait for the v0.2 Penman-Monteith
  variant.
- Report systematic biases to layers@petreldata.io — user feedback feeds the
  v0.2 validation plan.

## References

Mitchell, M., Wu, S., Zaldivar, A., Barnes, P., Vasserman, L., Hutchinson, B.,
Spitzer, E., Raji, I. D., & Gebru, T. (2019). Model Cards for Model Reporting.
FAT* '19. https://doi.org/10.1145/3287560.3287596