# Data Sources — Petrel Flow Accumulation Layer v0.1

All input data used to build the v0.1 vintage, with citations and licensing
notes. This Layer has an unusually simple and deliberate provenance: **a single
permissive input** (the Copernicus GLO-30 DEM) and one open-source method
library (pysheds). No share-alike, EULA-flow-down, or otherwise
commercially-encumbered source touches the derivation. That single-input
provenance is what lets Petrel own the derived Layer and license it both as a
free give-back and internally in its commercial hazard models — see
[`model_card.md`](model_card.md).

v0.1 is a **deterministic derivation**, not a trained model: there is no labelled
training set, only the DEM and the published method below.

## Elevation input (the sole data source)

### 1. Copernicus GLO-30 Digital Elevation Model

Global 30 m (1 arcsec) digital surface model, the sole input to the derivation.

- **Citation:** European Space Agency & Airbus (2022). *Copernicus DEM — Global
  and European Digital Elevation Model (COP-DEM), GLO-30.* Produced from the
  WorldDEM. https://doi.org/10.5270/ESA-c5d3d65
- **Attribution (required, must be reproduced downstream):** *"© DLR/Airbus,
  provided under COPERNICUS by the European Union and ESA."*
- **License:** Copernicus permissive licence — free reuse **including
  commercial**, with attribution; no share-alike and no EULA flow-down. This
  permissive, attribution-only status is the reason the Layer can exist: it lets
  Petrel own the derived product outright.
- **Used as:** the elevation grid fed to pysheds (fill → flow direction →
  accumulation) and to the slope term of TWI. Read at 9 arcsec (~278 m) for the
  global Layer.

**Why not HydroSHEDS / HydroRIVERS?** The classical drainage layers
(distance-to-drainage, flow accumulation, river network) come from HydroSHEDS /
HydroRIVERS. Verified 2026-09-07 against the WWF technical documentation, the
reason is NOT the one previously given here — this passage said "copyleft-
flavoured" and the conclusion was right for the wrong reason:

- **HydroSHEDS v1 / HydroRIVERS: unusable, but not because of NonCommercial.**
  §7.1 explicitly permits commercial use. The blocker is §3, which assigns WWF
  ownership of "all Intellectual Property Rights in the Licensed Materials and
  any modifications, extensions, or improvements ... however developed" — that
  reaches a Petrel-derived raster directly. Plus an End-User EULA flow-down onto
  our customers and a ban on stand-alone redistribution (§2.1.2). This is the
  same trap as FABDEM: "our derivative is a new work" is exactly what §3
  forecloses.
- **HydroSHEDS v2 (RIV_STREAMS) is CC BY 4.0 and IS clean.** §4.1: "All products
  of version 2 of HydroSHEDS are distributed under a Creative Commons
  Attribution 4.0 International License." It carries full reach connectivity at
  1 arcsec on a 1 km2 threshold — but it is **Americas-only** as of TechDoc
  v2.0.0 (July 2026), so it cannot be a global spine. Usable as a validation
  and calibration reference where it covers.
- **MERIT Hydro remains excluded** (CC-BY-NC 4.0 or ODbL — NC fails, share-alike
  fails).

This Layer re-derives the same quantities clean-room from the permissive
Copernicus DEM, which remains the only route that is simultaneously global,
licence-clean and Petrel-owned.

## Method reference (no data, published algorithm)

### 2. pysheds

- **Citation:** Bartos, M. (2020). *pysheds: simple and fast watershed
  delineation in Python.* https://github.com/mdbartos/pysheds.
  https://doi.org/10.5281/zenodo.3822494
- **License:** GNU GPL-3.0 — used as a **processing tool** (imported at build
  time to compute the derivation); it processes our data and is not
  redistributed or linked into the shipped raster, so its terms do not attach to
  the output data product.
- **Used as:** the depression-handling + D8 flow-direction + accumulation engine
  (`fill_pits → fill_depressions → resolve_flats → flowdir → accumulation`). See
  [`methodology.md`](methodology.md).

The Euclidean distance transform (distance-to-drainage) and the slope/gradient
term of TWI use SciPy / NumPy (BSD-licensed numerical libraries) — again tools,
not data sources.

## Geographic mask (post-processing)

### 3. GSHHG v2.3.7 full-resolution shoreline (`gshhg_f`)

Petrel's canonical land mask — the Wessel & Smith Global Self-consistent,
Hierarchical, High-resolution Geography database at full resolution
(~100 m native).

- **Citation:** Wessel, P., & Smith, W. H. F. (1996). A global,
  self-consistent, hierarchical, high-resolution shoreline database.
  *Journal of Geophysical Research*, 101(B4), 8741–8743.
- **License:** LGPL (internal masking use only; not redistributed as data).
- **Used as:** the coast clip applied to both rasters (`all_touched` — any cell
  touching real land keeps its value). GSHHG L1 only, so Antarctica is excluded
  by standard.

## Reproducibility

The exact source paths, method knobs (resolution, halo width, channel threshold,
caps), and promote configuration for v0.1 are versioned in
`configs/flow_accumulation_layer.yaml` in the Petrel ML repository. That config
is the source of truth — if anything here disagrees with it, the config wins.