# Model Card — Petrel Flow Accumulation Layer v0.1 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 → drainage derivatives. The
card is retained for consistency and because intended-use / limitation reporting
is just as relevant for a derived product.

## Model details

- **Name:** Petrel Flow Accumulation Layer v0.1 Global (DEM-derived)
- **Version:** v0.1-global-dem
- **Vintage code:** `flow_accumulation_v0.1_global_dem`
- **Release:** July 2026
- **Owner:** Petrel
- **Type:** Deterministic hydrological derivation — D8 flow accumulation from the
  Copernicus GLO-30 DEM (pysheds), shipping 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 copyleft-flavoured WWF licence (EULA flow-down, non-transferable, no
stand-alone redistribution). That is acceptable *directly inside a sold hazard
model* but 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 a single permissive input**,
the Copernicus GLO-30 DEM (attribution-only). Because no share-alike / flow-down
source is touched, the derived Layer is **unencumbered**:

- it ships to the **community as a free Layer** under CC-BY-NC-4.0 (this
  bundle, like the Petrel aridity Layer), with no license entanglements to
  carry into your stack, and
- the same clean provenance lets it feed Petrel's commercial hazard models —
  no term contaminates either side.

Single-input provenance is the load-bearing property; it is documented in
[`data_sources.md`](data_sources.md) and enforced at the config level (the only
source path in `configs/flow_accumulation_layer.yaml` is the Copernicus DEM).

## Intended use

### Primary intended uses

- A drainage-structure covariate for Petrel hazard models — landslide
  (distance-to-drainage + TWI), soil erosion (distance-to-drainage + flow
  accumulation for the LS-factor), flood, and volcano-lahar routing
- 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

- **Absolute river-discharge or catchment-area accounting from v0.1.** Halo
  tiling under-counts absolute accumulation for major trans-halo rivers; use the
  network structure (channels, distance, TWI), not the absolute upstream count,
  until v1's global two-pass accumulation ships.
- **Reach-scale hydraulic / flood-inundation modelling.** 278 m cells do not
  resolve channel geometry.
- **Bathymetry or below-DEM-resolution features.** Sub-pixel streams below the
  1 000-cell channel threshold are not represented.

## Inputs

- **Copernicus GLO-30 DEM** — the sole input; 30 m global elevation, permissive
  (attribution-only) licence. See [`data_sources.md`](data_sources.md).
- No labels, no covariate learning, no ancillary hydrography.

## Evaluation

**v0.1 has no published quantitative skill score.** Validation to date is
qualitative: a hydrological sanity check on Semeru (the accumulation maximum
lands at a valley exit, not the summit) plus structural agreement of the derived
channel network and distance-to-drainage with the HydroRIVERS geography it
replaces. A quantitative channel-overlap / distance benchmark against
HydroRIVERS is the flagged v1 item. See [`validation_report.md`](validation_report.md)
for exactly what was and was not checked.

## Uncertainty

No uncertainty companion ships in v0.1. The dominant structural error is the
**halo-tiled trans-halo accumulation under-count** (see limitations), which is
not a per-cell noise term but a systematic, geographically-localized bias at
tile interiors far from a large river's source. It is removed by the v1 global
two-pass accumulation, not by an uncertainty band.

## Known biases & failure modes

| Failure mode | Surface | Status in v0.1 |
|---|---|---|
| **Trans-halo accumulation under-count** | Absolute upstream count too low for major rivers deep in a tile, source beyond the 110 km halo | Documented; network structure unaffected; Barnes-style global 2-pass is the v1 fix |
| **Distance far-tail saturation** | Deserts / endorheic interiors exceed the 50 km cap | Capped at 50 000 m for encoding |
| **Channel-threshold sensitivity** | Network density depends on the 1 000-cell threshold | Fixed threshold; documented in methodology |
| **Coarse cells** | 278 m aggregates sub-pixel drainage | Documented; not for reach-scale work |
| **DEM artefacts** | Copernicus DEM voids / built-up / canopy bias propagate into flow paths | Inherited from input; pysheds depression-fill mitigates sinks |
| **Coverage** | Ocean NoData; Antarctica excluded (GSHHG-f L1) | By standard |

## Ethical considerations

- **No PII.** All inputs are gridded elevation; the product identifies no
  properties, parcels, or people.
- **Derived-product uncertainty.** The Copernicus DEM is itself a measured
  product with voids and canopy/built-up biases; v0.1 inherits them, compounded
  by the halo-tiling approximation.
- **Non-commercial license.** Commercial hydrological 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

- Use the **network structure** (channel positions, distance-to-drainage, TWI),
  not the absolute accumulation count, in v0.1.
- Treat distance values at the 50 km cap as "far from any channel", not as exact.
- If you need reconciled global absolute accumulation, wait for the v1 two-pass
  variant.
- Report systematic artefacts to layers@petreldata.io — user feedback feeds the
  v1 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