# Data Dictionary: NISAR Vision Global Subsidence Atlas

> **Calibration Notice:** NISAR L2 GUNW (`CRID P05023`) data products cataloged in this atlas are provisional. Calibration and validation are carried out by the NISAR project (NASA-JPL and ISRO), not by our team.

This data dictionary defines all fields, units, types, and constraints present in `data/global/atlas.json` and associated regional metadata files.

---

## 1. Top-Level Catalog Fields

| Field | Type | Description | Example Value |
|---|---|---|---|
| `title` | string | Catalog title and operational scope | `"NISAR Vision global subsidence atlas 2026"` |
| `status` | string | Generation pipeline script and standard reference | `"Generated by PC10 pipeline/pc10/build_atlas.py (KALITE STANDARDI §1-§4)"` |
| `quality` | string | Global dataset quality tier (`provisional` or `validated`) | `"provisional"` |
| `quality_note` | string | Mandated NASA/ISRO provisional data usage disclaimer | `"NISAR data are provisional. Calibration and validation are carried out by the NISAR project..."` |
| `ranking_metric` | string | Official metric used to rank regions | `"rate_cm_per_100d"` |
| `n_regions` | integer | Total count of processed geographic regions in catalog | `10` |
| `n_reliable` | integer | Number of regions classified as reliable (`high` or `medium` confidence) | `6` |
| `n_indicative` | integer | Number of regions classified as indicative only (`low` confidence) | `4` |
| `regions` | array[object] | Complete list of all region objects sorted by `rate_cm_per_100d` | `[...]` |
| `reliable` | array[object] | Filtered list containing only reliable regions | `[...]` |
| `indicative` | array[object] | Filtered list containing only indicative-only regions | `[...]` |

---

## 2. Regional Record Schema (`regions[]`)

Each object in `regions` describes a single evaluated geographic basin:

| Field | Type | Unit | Description | Example Value |
|---|---|---|---|---|
| `id` | string | — | Unique lowercase machine identifier matching subdirectory name | `"central_valley"` |
| `name` | string | — | Human-readable region or basin title | `"Central Valley (Tulare Basin)"` |
| `country` | string | — | Sovereign country name | `"USA"` |
| `lon` | float | decimal degrees | Bounding box center longitude (WGS84, $-180$ to $+180$) | `-119.02173` |
| `lat` | float | decimal degrees | Bounding box center latitude (WGS84, $-90$ to $+90$) | `36.01119` |
| `max_cm_los` | float | cm | Peak cumulative Line-of-Sight displacement (minimum 1 km block median; negative = subsidence) | `-7.8` |
| `p2_cm` | float / null | cm | 2nd percentile of valid pixel displacements across bounding box | `-5.8` |
| `rate_cm_per_100d` | float | cm / 100 days | Normalized LOS subsidence rate: $(\text{max\_cm\_los} / \text{days}) \times 100$. Primary sorting metric | `-7.2` |
| `max_cm_vertical_est` | float | cm | Vertical subsidence estimate assuming purely vertical motion: $\text{max\_cm\_los} / \cos(37^\circ)$ | `-10.1` |
| `period` | [string, string] | ISO 8601 date | Pair of [start_date, end_date] defining the interferometric stack window | `["2026-06-28", "2026-10-14"]` |
| `days` | integer | days | Elapsed temporal baseline between first acquisition and last acquisition | `108` |
| `n_pairs` | integer | count | Number of sequential unwrapped interferometric pairs summed in stack | `7` |
| `quality` | string | — | Quality classification tier of input GUNW products (`provisional` or `mixed`) | `"provisional"` |
| `rate_cm_per_yr_estimate` | float | cm / year | Annualized LOS rate estimate: $(\text{max\_cm\_los} / \text{days}) \times 365.25$. Not used for ranking | `-26.4` |
| `valid_fraction` | float / null | fraction (0–1) | Proportion of bounding box pixels with valid unwrapped phase across all pairs | `0.629` |
| `ref_range_cm` | [float, float] / null | cm | Range [min, max] of headline displacements obtained across alternative reference points | `[-7.8, -4.7]` |
| `confidence` | string | — | Categorical confidence level (`high`, `medium`, or `low`) per Quality Standard §4 | `"medium"` |
| `indicative_only` | boolean | — | Flag indicating whether result is exploratory due to low coherence or atmospheric delay | `false` |
| `coverage` | string | — | ASF GUNW product coverage status (`"ok"`, `"partial"`, or `"none"`) | `"ok"` |
| `path` | string | relative path | Repository relative directory containing raster PNGs, points, and summary JSON | `"data/central_valley/"` |
| `note` | string | — | Contextual commentary or specific reference adjustments | `""` |
| `rank` | integer | rank | Integer position (1 to N) ordered by `rate_cm_per_100d` | `2` |

---

## 3. Associated Regional Data Assets

Under each `path` directory (e.g. `data/global/<id>/` or `data/<id>/`), companion files provide full auditability:

1. **`summary.json`**: Machine-readable single-region metrics matching the fields above, plus bounding coordinates (`[w, s, e, n]`), primary reference coordinates (`ref_lonlat`), and runtime timestamps.
2. **`validation_note.json`**: Head-to-head evaluation by PC5 comparing NISAR observations to published GNSS/InSAR literature, detailing reference sensitivity and sign-off status.
3. **`coverage.json`**: Granule inventory from ASF DAAC, including track number, granule IDs, and acquisition timestamps.
4. **`disp/*.png`**: Georeferenced displacement rasters for each cumulative step, rendered with a consistent diverging colormap (`RdBu_r`, $-15\text{ cm}$ to $+5\text{ cm}$).
5. **`uncertainty/meta.json`**: Spatial standard deviation map statistics ($\sigma_{\text{median}}$, SNR) calculated across unwrapped interferometric closure loops.