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

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

Drainage structure of the land surface at **278 m (9 arcsec)** global. This
Layer ships two rasters: distance-to-nearest-drainage-channel (metres) and the
topographic wetness index (TWI). They are derived from attribution-only inputs
— GEDTM30 v1.2 bare-earth terrain, with HydroLAKES and Natural Earth used to
route the Volga/Kama reservoirs — making this a **free dataset for the
community** under CC-BY-NC-4.0. As a clean-room replacement for
HydroSHEDS/HydroRIVERS it reaches you with **no copyleft or flow-down
obligations** to manage, and the same layers feed Petrel's landslide,
soil-erosion, flood, and volcano-lahar work.

## Layers (2 × 278 m global GeoTIFF)

| File | Description | Units / range | Dtype | NoData |
|---|---|---|---|---|
| `flow_distance_to_drainage_278m.tif` | Euclidean distance to nearest channel | metres, 0–50 000 | uint16 | 65535 |
| `flow_twi_278m.tif` | Topographic wetness index, ln(area/tan slope) | dimensionless, ~0–35 | uint16 | 65535 |

Each file is global at 9 arcsec (~278 m), EPSG:4326, 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` is NoData (ocean, Antarctica, unscored cells).

**Contributing area is not in this bundle.** The reconciled upstream area in
km² is produced by the same build and is available on request; it is not
encoded here because its dynamic range spans seven orders of magnitude and the
uint16 encoding used for these two rasters would destroy it. The two shipped
rasters are the derivatives the downstream Petrel hazard models consume.

## Reading the values

- **`flow_distance_to_drainage`** is the straight-line distance, in metres, from
  each land cell to the nearest DEM-derived stream channel. A channel is any
  cell whose upstream contributing area exceeds **1 km²** — an area, so the
  definition does not drift with latitude. Valley floors, riverbanks and the
  surface of a through-flowing reservoir read 0; ridgelines and dry interiors
  read high. The tail is capped at **50 km** (the top of the encoding). That
  value is reached only on small islands and cays that carry no 1 km² channel
  at all — 1,683 cells worldwide, 118 km² — where it means "no modelled
  channel on this land" rather than a distance.
- **`flow_twi`** is ln(upslope contributing area / tan local slope). High TWI =
  flat, water-gathering, saturation-prone terrain (valley bottoms, floodplains);
  low TWI = steep, well-drained slopes. It is a standard wetness / saturation
  proxy used in landslide and soil-moisture modelling.

## What changed in v0.3

v0.1 derived flow per 10° tile, so any catchment crossing a tile boundary was
truncated — the Amazon captured 5.6% of its true basin area. v0.3 reconciles
the tiles, and measured against published upstream areas at nine reference
gauges it now reads **96–101% on eight of them** (the Ural reads 90%). TWI,
being a logarithm of that area, was correspondingly **1.7–3.7 units low** on
major basins in v0.1 and is corrected.

Two things worth knowing when reading the rasters:

- **Reservoirs carry the river.** On the Volga/Kama cascade the water surface
  reads as channel, because the river does flow through it.
- **Lakes elsewhere keep DEM routing.** Drainage entering a lake is conserved,
  but on a large flat lake the modelled outlet may not be the real one.

Full numbers, including four defects this validation caught, in
`validation_report.md`.

## Licensing in one line (why this Layer exists)

Every input is attribution-only: GEDTM30 v1.2 and HydroLAKES are CC BY 4.0,
Natural Earth is public domain. Because no share-alike or EULA-flow-down source
touches it,
the derived Layer is free of license entanglements — **free for the community**
under CC-BY-NC-4.0, safe to sit alongside whatever else is in your stack, and
equally clean inside Petrel's own hazard models. That is the whole point: a
purpose-built, unencumbered replacement for the copyleft-flavoured
HydroSHEDS/HydroRIVERS drainage layers. See
[`data_sources.md`](data_sources.md) and [`model_card.md`](model_card.md).

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

lat, lon = -8.108, 112.922                      # Semeru summit, Java
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"distance to drainage: {raw * scale:.0f} m")
```

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

## Documentation

| Document | Purpose |
|---|---|
| [`methodology.md`](methodology.md) | How accumulation, distance-to-drainage, and TWI are built |
| [`model_card.md`](model_card.md) | Intended use, inputs, licensing, limitations |
| [`data_sources.md`](data_sources.md) | All input datasets with citations + licenses |
| [`validation_report.md`](validation_report.md) | Gauge-based validation, the defects it caught, 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.
Attribution must also credit the underlying DEM: *"© DLR/Airbus, provided under
COPERNICUS by the European Union and ESA."* 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 Flow Accumulation Layer v0.3 — Global (DEM-derived).
https://petreldata.io/layers/flow_accumulation/v0.3
```

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

## Known limitations (read before using)

- **Two basins still under-count.** The Ural reads 90% of its published area
  at Atyrau and the Amu Darya 94% at Kerki; flat steppe and irrigated delta
  terrain lose tributary area at a few points. Every other tested basin reads
  96–101%. See [`validation_report.md`](validation_report.md).
- **Lakes outside the Volga/Kama cascade keep DEM routing.** Flat water gives
  the DEM no gradient, so the modelled outlet of a large lake may not be the
  real one. Drainage entering the lake is conserved either way.
- **TWI saturates on large rivers.** It is a logarithm of contributing area
  capped at 35, so the biggest basins sit at the cap.
- **Small islands read 50 km.** An island too small to carry a 1 km² channel
  has no channel at all, so every cell on it saturates at the distance cap.
  1,683 cells worldwide (118 km²). Read it as "no modelled channel here".
- **278 m cells** aggregate sub-pixel drainage; not for reach-scale hydraulic
  work.
- **Distance-to-drainage is capped at 50 km**; deserts / endorheic interiors
  saturate at the cap.
- **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/flow_accumulation_volga.yaml`,
  promoted via the canonical Petrel postprocess chain)
- **STAC item:** [`flow_accumulation_v0.3_global_dem_stac_item.json`](flow_accumulation_v0.3_global_dem_stac_item.json)