Data files
Two JSON files carry the project: lakes_in.json, the register the team edits, and lakes.json, which the pipeline writes and the app reads.
lakes_in.json#
processing/lakes_in.json is a list with one object per lake:
{
"id": "attabad", // lower case, digits and _; also the picture folder name
"name": "Attabad Lake (landslide-dammed control)",
"lon": 74.8665, "lat": 36.333, // decimal degrees, WGS 84: a point on the lake
"role": "control", // "watch", "story" or "control"
"coord_source": "A point on the lake, ... inside OpenStreetMap way 60065056 ...",
"outline": "outlines/attabad_osm.geojson", // or null for a search circle
"downstream": null, // optional: what lies downstream
"downstream_source": null
}
Optional fields:
| Field | Meaning |
|---|---|
zone_radius_km | Radius of the search circle when there is no outline: 1 km by default, at most 2.5 km (the window is 6 km across). Karambar's terminus pond uses 0.3. |
lake_state | "lake" (default); "unconfirmed", a lake recent imagery does not confirm, which keeps its status and gets a limit; or "no_lake", a site with no lake now, whose status is No lake now with no verdict and no water layer. |
lake_state_source | What shows the state, with dates. Required unless lake_state is "lake". |
forming_share, forming_share_source | Optional, for a "no_lake" site only: the water share of the zone above which the Sentinel-2 re-check says a lake may be forming (default 4%, FORMING_WATER_SHARE), and why. Set where the empty zone holds other water, such as a river. |
limits | Optional list of the site's own sourced limits, shown with the lake (for example a past partial drainage). |
| Role | Meaning |
|---|---|
watch | A lake SARtale screens. Requests accepted from the website get this role by default. |
story | A lake that also appears in the story, such as Shisper. |
control | A known, permanent lake used to check the method. It is listed last and drawn with a dashed border. |
lakes.json#
app/public/data/lakes.json is written by lakes-build and never edited by hand. Its top level:
| Key | Contents |
|---|---|
version, built, crid | File version, build time, and every NISAR processing version (CRID) used, sorted and comma-joined (e.g. P05023, P05036) |
collections | The CMR collections the passes came from: NISAR_L2_GCOV_PROVISIONAL_V1 (provisional, up to 21 Oct 2026) and NISAR_L2_GCOV_V1 (standard, after it) |
notes | Build notes shown as method limits |
cloud_window | The dates counted in the headline |
constants | The method constants from config.py, so page text matches the build |
lakes | One object per lake (below) |
checks | Sentinel-2 comparison rows from lake_checks.json. A row with only lake and note means no comparison was possible; the app shows it as a note. |
Each lake carries its register fields plus:
| Key | Contents |
|---|---|
status | status, track, latest_date, looks, change_km2, noise_km2, a plain reason; for a level also level, level_since, level_passes (the passes that set it), cusum (up, down), z and baseline_km2 of the latest compared pass, alerts_paused (the track's first pass on a new processing version, or null) and message (level, title, what, how_sure, not, do and text: the initial message, for anyone to reuse); these are null when the status is not a level |
series | Every pass: date, track, area_km2, observable_share, excluded (null, or the reason it was left out) and crid (the pass's processing version); a compared pass also has z, baseline_km2, noise_km2 and level_contrib (the level it set), and new_version or after_open when it could not make an Alert. A left-out pass has area_km2 null and keeps what it read as diagnostic_km2 (null when it had no valid pixel), which the chart draws as a hollow marker and the status never uses |
excluded | The passes left out, as {"pass", "reason"} |
images | Paths, relative to data/, of latest_hh and water |
bounds | The window's [west, south, east, north] in degrees |
area_label, outline_source, limits, directions, cloud_window_looks | What the area measures, the outline's source, lake-specific limits, the viewing directions seen (A, D) and looks in the cloud window |
lake_state, lake_state_source | Copied from the register, except that a "no_lake" site whose latest Sentinel-2 check found water above its threshold becomes "lake_forming_check" (status Lake may be forming). The app leaves both out of the lake count and the cloud-window looks, and never features a site that is not a confirmed lake |
absence_checked | For a site with no lake now: the last Sentinel-2 check, date and s2_id of the scene, water_share and water_km2 of the zone, zone_valid_share (clear of cloud, shadow, snow and ice, and more than 100 m from cloud or cloud shadow), snow_share (under snow or ice), forming (the site's state), pending_scene (one scene on the other side of the threshold, waiting for a second), confirmed (the two scenes that set the state), threshold, checked (the run that found the scene), searched (the last run that searched), no_view_since (true when no clear, snow-free scene has come for over a week since the scene), rule, source and zone (the point with the circle radius, or the outline path and file hash; the check is carried from build to build only while the zone is the same). Null before the first check |
zone_radius_km, forming_share, forming_share_source | The circle zone's radius (null for an outline), and for a site with no lake now the threshold its re-check uses |
A sample pass from series:
{ "date": "2026-06-18", "track": "055A", "area_km2": 2.665, "observable_share": 0.675, "excluded": null, "crid": "P05023" }
Pictures#
For each lake, lakes-build writes two lossless WebP files to app/public/data/lakes/<id>/: latest_hh.webp, a grey HH picture of the latest valid pass, and water.webp, a transparent layer with the D17 water in the lake zone in blue (not written for a site with no lake now). Both cover the 6 km window on the UTM grid, north up.
Licences#
NISAR data are NASA's; OpenStreetMap outlines are © OpenStreetMap contributors under the ODbL. The full list of sources and terms is in DATA_SOURCES.md.
SARtale Guide