# Model Card — Petrel Flow Accumulation Layer v0.3 Global (DEM-derived)

Following the Model Card framework of Mitchell et al. (2019), "Model Cards for
Model Reporting", FAccT. Note: this Layer is a **deterministic DEM-derived
computation**, not a trained statistical model — there are no learned
parameters and no training set. The "model" is the composition pysheds
depression-fill → D8 flow direction → accumulation → cross-tile reconciliation
→ drainage derivatives. The card is retained because intended-use and
limitation reporting is just as relevant for a derived product.

## Model details

- **Name:** Petrel Flow Accumulation Layer v0.3 Global (DEM-derived)
- **Version:** v0.3-global-dem
- **Vintage code:** `flow_accumulation_v0.3_global_dem`
- **Release:** September 2026
- **Owner:** Petrel
- **Type:** Deterministic hydrological derivation — D8 flow accumulation from
  the GEDTM30 v1.2 bare-earth DEM (pysheds), reconciled across tiles, shipping
  contributing area (km²), distance-to-drainage (m) and the topographic wetness
  index (TWI)
- **Native resolution:** 278 m (9 arcsec), global 60° S – 84° N
- **License:** CC-BY-NC-4.0
- **Citation:** see [`CITATION.cff`](CITATION.cff)
- **Contact:** layers@petreldata.io

## Why this Layer exists — the licensing story

The drainage derivatives Petrel's hazard models need (distance-to-drainage,
TWI, flow accumulation) are classically taken from HydroSHEDS / HydroRIVERS.
Those carry a WWF licence that assigns ownership of derivatives to WWF, with an
EULA flow-down and no stand-alone redistribution. That can **never** feed a
free Layer, because a free Layer is also consumed internally by the sold
models — its terms would contaminate them.

So this Layer is a **clean-room re-derivation from attribution-only inputs**:
GEDTM30 v1.2 (CC BY 4.0) for terrain, HydroLAKES v1.0 (CC BY 4.0) for reservoir
polygons and outlets, Natural Earth (public domain) for the mapped river course
through those reservoirs, GSHHG for the coastline. No NonCommercial term, no
share-alike, no flow-down, so the derived Layer is **unencumbered**:

- it ships to the **community as a free Layer** under CC-BY-NC-4.0, with no
  licence entanglements to carry into your stack, and
- the same clean provenance lets it feed Petrel's commercial hazard models.

Provenance is the load-bearing property; it is documented in
[`data_sources.md`](data_sources.md) and enforced at the config level.

## Intended use

### Primary intended uses

- A drainage-structure covariate for Petrel hazard models — landslide
  (distance-to-drainage + TWI), soil erosion (the LS factor), flood, and
  volcano-lahar routing
- Partitioning catchments by contributing area, for example separating
  river-driven from rain-driven flood domains
- Hydrological / geomorphological research at regional to global scale
- A commercially-clean drop-in where a project cannot take a
  HydroSHEDS-licensed drainage layer
- Teaching / cartography — the channel network and TWI are recognizable
  reference layers

### Out-of-scope uses

- **River discharge.** This is contributing area, not flow. Nothing here models
  rainfall, runoff, abstraction or regulation.
- **Reach-scale hydraulic / flood-inundation modelling.** 278 m cells do not
  resolve channel geometry.
- **Catchment accounting downstream of a large lake outside the Volga/Kama
  cascade.** Every other lake keeps DEM routing, and where a river leaves a
  flat lake may differ from reality.
- **Bathymetry or sub-pixel streams** below the 1 km² channel threshold.

## Inputs

- **GEDTM30 v1.2** — bare-earth elevation, CC BY 4.0, the terrain input.
- **HydroLAKES v1.0** — polygons, expert pour points and independent watershed
  areas for the eight Volga/Kama reservoirs, CC BY 4.0.
- **Natural Earth 1:10m rivers and lake centerlines** — the mapped river course
  through those reservoirs, public domain.
- **GSHHG-f** — land/ocean mask.
- No labels, no covariate learning.

## Evaluation

v0.3 is validated **quantitatively at nine reference gauges** against published
upstream drainage areas, including three closed basins: eight of nine read
96–101% and the Ural reads 90%. v0.1 read 2.5–19.3% at the same gauges. The
measurement, the four defects it caught, and what it does not establish are in
[`validation_report.md`](validation_report.md).

## Uncertainty

No per-cell uncertainty band ships. The dominant residual errors are structural
and geographically localised rather than noise: two under-counting basins (Ural,
Amu Darya), lakes outside the Volga/Kama cascade where the outlet position is
DEM-determined, and a few tiles on drainage divides that never fully settle.
Each is named in the validation report rather than folded into a band.

## Known biases & failure modes

| Failure mode | Surface | Status in v0.3 |
|---|---|---|
| **Flat-water routing** | Inside a large lake the DEM has no gradient, so the outlet position is arbitrary | Fixed for the eight Volga/Kama reservoirs (explicit nodes); all other lakes keep DEM routing |
| **Under-counted basins** | Ural 90%, Amu Darya 94% at their gauges | Measured and documented; flat steppe and delta terrain |
| **Unsettled tiles** | A drainage divide along a tile boundary lets two tiles feed each other | A few tiles creep < 0.1% per round; boundary-cell DAG is the structural fix |
| **TWI saturation** | TWI is a log of area capped at 35, so large rivers sit at the cap | By design; use contributing area where magnitude matters |
| **Distance far-tail saturation** | Small islands and cays carry no 1 km² channel, so every cell on them saturates at the 50 km cap — 1,683 cells, 118 km², 0.00007% of land. Deserts are unaffected | Measured and documented; NoData for channel-less islands is a candidate for the next vintage |
| **Channel-threshold sensitivity** | Network density depends on the 1 km² threshold | Fixed threshold in area units, documented in methodology |
| **Coarse cells** | 278 m aggregates sub-pixel drainage | Documented; not for reach-scale work |
| **DEM artefacts** | GEDTM30 voids, residual urban bias and water-body flattening propagate into flow paths | Inherited from input; depression-fill mitigates sinks |
| **Coverage** | Ocean NoData; Antarctica excluded (GSHHG L1) | By standard |

## Ethical considerations

- **No PII.** All inputs are gridded elevation and water geometry; the product
  identifies no properties, parcels or people.
- **Derived-product uncertainty.** GEDTM30 is itself a modelled product with
  voids and a residual urban bias; v0.3 inherits them.
- **Non-commercial license.** Commercial hydrological decisions should involve
  explicit human review rather than automated reliance on a research-grade
  layer — commercial licensing (via https://petreldata.io/demo) exists partly
  to enforce that conversation.

## Caveats & recommendations

- Contributing area is now meaningful in absolute terms at the gauges tested;
  treat it as drainage area, never as discharge.
- Treat distance values at the 50 km cap as "far from any channel", not exact.
- Where your area of interest contains a large lake or reservoir outside the
  Volga/Kama cascade, check where the river leaves it before relying on
  downstream drainage.
- Report systematic artefacts to layers@petreldata.io — user feedback feeds the
  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