# Petrel Flow Accumulation Layer v0.1 — 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). Both are derived entirely from the Copernicus
GLO-30 DEM — a single permissive input — 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).

**Raw flow accumulation is not shipped in v0.1.** It is an internal intermediate
with a huge dynamic range that needs a log encoding the promote reencode does
not yet support; a raw-accumulation sub-layer is a flagged v0.2 item. The two
shipped sub-layers — distance-to-drainage and TWI — are the derivatives the
downstream Petrel hazard models actually 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 accumulation exceeds 1 000 cells. Valley floors and
  riverbanks read near 0; ridgelines and dry interiors read high. The
  far-from-river tail (deserts, endorheic basins) is capped at **50 km**.
- **`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.

## ⚠ Known limitation — TWI is biased low on large river basins

Accumulation is computed per tile with a 1-degree halo, so catchments that
cross tiles are under-counted: the Amazon captures 7.8 % of its true basin
area, the Mississippi 10.4 %, the Danube 30.1 %. Since `TWI = ln(a / tan β)`,
**TWI reads about 1.2–2.6 units low on those basins**. Local and
small-catchment terrain is unaffected. A global two-pass accumulation is the
v1 fix. Full numbers in `validation_report.md`.

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

The **only** input is the Copernicus GLO-30 DEM, which is permissive
(attribution-only). 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.1/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.1/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) | Validation status (v0.1: qualitative) + 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.1 — Global (DEM-derived).
https://petreldata.io/layers/flow_accumulation/v0.1
```

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

## Known limitations (read before using)

- **v0.1 is halo-tiled, so absolute accumulation is under-counted for major
  trans-halo rivers.** Each tile is derived with a ~110 km (1°) DEM halo. The
  drainage **network structure** — channel positions, distance-to-drainage,
  TWI — is correct, but the absolute upstream count for a large river far from
  its headwaters (deep in a tile interior, source beyond the halo) is
  under-estimated. A Barnes-style global two-pass accumulation is the flagged
  v1 fix. See [`methodology.md`](methodology.md) and
  [`validation_report.md`](validation_report.md).
- **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_layer.yaml`,
  promoted via the canonical Petrel postprocess chain)
- **STAC item:** [`flow_accumulation_v0.1_global_dem_stac_item.json`](flow_accumulation_v0.1_global_dem_stac_item.json)