SARtale Guide

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:

FieldMeaning
zone_radius_kmRadius 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_sourceWhat shows the state, with dates. Required unless lake_state is "lake".
forming_share, forming_share_sourceOptional, 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.
limitsOptional list of the site's own sourced limits, shown with the lake (for example a past partial drainage).
RoleMeaning
watchA lake SARtale screens. Requests accepted from the website get this role by default.
storyA lake that also appears in the story, such as Shisper.
controlA 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:

KeyContents
version, built, cridFile version, build time, and every NISAR processing version (CRID) used, sorted and comma-joined (e.g. P05023, P05036)
collectionsThe 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)
notesBuild notes shown as method limits
cloud_windowThe dates counted in the headline
constantsThe method constants from config.py, so page text matches the build
lakesOne object per lake (below)
checksSentinel-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:

KeyContents
statusstatus, 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
seriesEvery 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
excludedThe passes left out, as {"pass", "reason"}
imagesPaths, relative to data/, of latest_hh and water
boundsThe window's [west, south, east, north] in degrees
area_label, outline_source, limits, directions, cloud_window_looksWhat 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_sourceCopied 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_checkedFor 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_sourceThe 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.