Data Inventory

How to read this inventory¶

Hazard legend (the Serves column): ⛰️ landslides (shallow / deep-seated) · 🔥 post-fire debris flows · 🏚️ liquefaction & ground failure · 🌊 floods.

Data are grouped by provenance tier, because that determines how they should be trusted, stored, and calibrated:

1. Raw / observed inputs — imported from an external archive and treated as a fixed input, not a GAIA model output. Calibration holds these fixed. Note that “raw to us” ≠ “a direct observation”: some ingested products (SOLUS, POLARIS, proxy $V_{s30}$) are themselves statistically / ML-derived externally (marked 📈 in §1) and carry prediction uncertainty that must be propagated, not silently dropped.

2. Derived variables — computed from raw inputs, either deterministically (a documented equation or rule) or statistically (a fitted / ML relationship that carries its own uncertainty). Not observed, but reproducible given the input stack, rules, and config.

3. Modelled variables & outputs — produced by the model components during a run. These carry model assumptions and uncertainty.

Every value the inventory serves is therefore one of three things, and each entry says which: a direct observation, a deterministic derivation (rule/equation recorded), or a statistical / ML estimate (method + uncertainty recorded). Orthogonally, a handful of numeric parameters are 🎛️ calibration levers — free knobs tuned to targets (§6), neither observed nor fixed by a physical rule. Being a calibration number is legitimate; it just has to be visible and never mistaken for data. These are marked 🎛️ wherever they appear below.

Origin classifies the archive by source class — Federal agency, State, Academic, Private sector, Intl, or GAIA-Modeled — the axis that matters for trust and archival policy (not merely public-vs-private). Native support records the true footprint a value represents, while Posting resolution records the grid it is delivered on; keeping the two apart is what stops a downscaled 9 km pixel from being mistaken for a native 10 m one (the footprint-leakage problem). Temporal resolution is how often the value updates. Limitations captures the caveat a downstream modeler needs before using the layer — including access keys, licenses, and withheld locations (summarized in §7).

The primary targets the pipelines exist to produce are landslide__probability_of_failure ($P_f$ ⛰️ 🔥) and the probability / extent of liquefaction $P(\text{liq})$ with its manifestation severity (LPI / LSN 🏚️).

1. Raw / observed inputs (external products)¶

Fetched from external archives and prepared onto the working grid — the fixed foundation of the models and of calibration.

2. Derived variables (deterministic & statistical transformations)¶

Computed from the raw stack — not observed, but reproducible given the inputs, rules, and config. Each derivation is one of two kinds: deterministic (a documented equation or rule; §2.1–2.2) or statistical / ML (a fitted relationship that carries its own uncertainty; §2.3). Free constants tuned to targets rather than measured or physically fixed are flagged 🎛️ (the calibration levers of §6). All rows in §2.1–2.2 are deterministic unless a 🎛️ marks a calibration constant embedded in the rule.

2.1 Hydrology & terrain ⛰️ 🔥 🌊¶

2.2 Liquefaction 🏚️¶

2.3 Statistical / ML-derived layers 📈¶

These are not deterministic rules — they are fitted / machine-learned relationships, so they carry prediction uncertainty that must travel with the value. Several are ingested as §1 “inputs” even though they are model estimates, not observations (§2.4 traces one back to raw).

The geospatial liquefaction surrogate (§3, §5) and the modeled water table (Zhu GLM, §1) are likewise statistical; their uncertainty is documented on the model pages.

2.4 Worked example — tracing SOLUS back to raw¶

SOLUS is the template for every ingested statistical product: state what it was fitted from, what its native support really is, and what uncertainty it carries, so a downstream modeler can trace any value back to observations.

• What it is. SOLUS100 (USDA-NRCS): ML-predicted maps of ~20 soil properties at 100 m (1 ha) over CONUS, at the GlobalSoilMap depths (0, 5, 15, 30, 60, 100, 150 cm), with low/high 95% prediction intervals Nauman et al., 2024.

• Raw it descends from (the observations). Laboratory pedon measurements (NCSS/KSSL), plus gNATSGO/SSURGO map-unit weighted averages and component-level “disaggregation” training points — a hybrid training set. These point/polygon observations are related to the landscape through gridded environmental covariates: DEM terrain derivatives (slope, curvature, MRVBF, SAGA wetness index, topographic-position index) and PRISM 30-year climate normals (precipitation, temperature, vapor-pressure deficit) plus bioclimatic indices (full stack in the paper’s supplement).

• The transform (why it is statistical, not deterministic). A random-forest model maps those covariates → soil property. There is no closed-form rule; the 100 m value is a prediction, and the low/high 95% prediction-interval (l/h) bands are its uncertainty. Propagate them — do not treat the median as truth.

• Native support vs posting. Posted at 100 m, but the effective support is coarser and spatially variable — set by training-point density and covariate scale (SSURGO map-unit scale), not by the 100 m grid. This is the §1 “Native support ≠ Posting resolution” distinction made concrete.

• Calibration flag. Where a SOLUS property is later tuned to a target (e.g. ksat_factor on the derived $K_{sat}$), that tuned value is a 🎛️ calibration lever, not a SOLUS output — keep the two separate.

Apply the same five-line trace to POLARIS, proxy $V_{s30}$, and surficial geology before mixing them into a model.

3. Modelled variables & outputs¶

The digital twins exist to produce a fixed, named set of outputs — the canonical output vocabulary below. Everything else in this section is an intermediate or diagnostic that feeds one of them. The canonical name is the Landlab field__name (first column); the PascalCase label is a display alias. Two outputs still carry an input/output dual-role caveat (the earlier name collision is resolved by the convention note below).

Naming convention (decided). The field__name vocabulary is canonical — every output ships under a Landlab-style subject__quantity name in code, STAC, and Zarr; PascalCase names are display aliases only (docs, dashboards, product copy), never keys. This resolves the earlier collision: the model component keeps the class name LandslideProbability, while the output field it writes is landslide__probability_of_failure — a component and its field are never the same token. Names marked † are proposed (not yet emitted in code) and should be ratified before first use; the unmarked fields already exist. Uncertainty for each output is documented on its model page (Monte-Carlo $P_f$, GLM surrogate intervals, etc.).

Detailed producing-model breakdown (intermediates and diagnostics included):

4. Data-prep pipelines¶

4.1 Landslide (Landlab) ⛰️ 🔥¶

A. domain     AOI → watershed / HUC polygon; target CRS + resolution; hydrologically coherent domain; watershed outlet preferred
B. acquire    DEM · SOLUS100|POLARIS soil · NLCD landcover (+ MTBS burn severity — post-fire only)
C. harmonize  reproject + resample to ONE grid contract; nodata; manifest
D. derive     slope, specific contributing area (FlowAccumulator on the CLOSED watershed);
              import or harmonize φ and cohesion rasters; Ksat → transmissivity; landcover → PFT → LAI; Ksat → transmissivity; landcover → PFT → LAI
E. PRISM (hindcast/current workflow) | Earth2Studio tp/APCP (future forecast path) → mm/day → snow → balance → recharge
F. soil state deep-seated: import water-table h(x,t) + S_w from Pillar 1; init S0 from SMAP
G. validate   input contract: shape · CRS · transform · nodata · units · required fields
H. publish    COG / Zarr on s3://cresst + STAC items with source·measurement·res·uncertainty

Close the hydrology first (clip to a watershed with a single outlet — see Landslide Model §5); do not prepare on arbitrary tiles. Inputs are still read from hardcoded local paths in the active notebook; de-personalizing and sourcing from STAC (solus-stac, prism-stac, gaia-cli stage) is the migration in the Integration Guide §3.

4.2 Liquefaction (GLM) 🏚️¶

A. domain     AOI / region; target CRS + resolution (high-res even for static layers)
B. acquire    Vs30/Vs profiles · water table (Pillar 1) · geology · ShakeMap | NSHM ground motion
C. harmonize  reproject + resample to one grid contract; manifest + provenance
D. derive     effective stress σ'v (from water table) · Vs1 · CSR · saturation proxies
E. condition  conditional GLM P(liq|IM)  →  (unconditional: integrate over NSHM;
                                             event: apply ShakeMap IM field)
F. dynamic    couple groundwater (sea-level / seasonal) + time-varying Vs/κ0 (§7 open question)
G. validate   input contract: shape · CRS · units · required fields
H. publish    COG / Zarr on s3://cresst + STAC items

The high-resolution requirement (even for static $V_{s30}$, geology, water table) is central: liquefaction is controlled by meter-scale contrasts, so coarse inputs systematically smear hazard.

5. Models behind the products¶

Each derived/modelled product is generated by a model component. Full physics and solved-vs-assumed breakdowns are on the model pages (Landslide Model, Liquefaction Model).

• Landlab LandslideProbability ⛰️ 🔥 — infinite-slope $FS$ + Monte Carlo $P_f=\Pr(FS\le1)$ Strauch et al., 2018; assumes planar failure, steady-state topographic wetness Beven & Kirkby, 1979Montgomery & Dietrich, 1994. Shallow vs deep-seated = a swapped hydrology closure, not a different model.

• Ecohydrology SoilMoisture + PET / snow / FlowAccumulator ⛰️ 🔥 🌊 — root-zone water balance, snow partition, and flow routing that produce recharge and the hydrologic state.

• Geospatial liquefaction surrogate 🏚️ — mechanics-informed ML emulating the simplified-procedure FS at national scale Sanger et al., 2025Zhu et al., 2017, with manifestation fragility Geyin & Maurer, 2020Maurer et al., 2015; consumes $V_s$, water table, ground motion.

• Forecast weather leg — NVIDIA Earth2Studio ⛰️ 🔥 🌊 🏚️ — a weather-provider branch (GraphCast / AIFS / StormCast) supplying forecast precipitation (and groundwater forcing for liquefaction); not a hazard model itself.

6. Calibration targets¶

number_of_iterations (landslide Monte Carlo) is a convergence knob, not a calibration parameter.

7. Known gaps, risks & sensitivities¶

• CRS leakage. Local .asc stacks lack an embedded CRS; GeoTIFF/Zarr outputs must carry CRS explicitly.

• Soil-vocabulary mismatch. POLARIS and SOLUS differ in variables, depths, statistics, and units — a conversion table is required before mixing them.

• Static vs dynamic water table. Most GLMs use a static modeled water table; GAIA’s contribution is the dynamic $d_{wt}$ (seasonal, sea-level rise) from Pillar 1 — distinguish the two.

• Time-varying site term. $\kappa_0(t)$ / $V_s(t)$ are not yet wired into the NSHM-based unconditional liquefaction product (the open question in Liquefaction Model §5).

• $V_{s30}$ proxy uncertainty. Slope/geology $V_{s30}$ carries large scatter; parametric profiles Sanger & Maurer, 2025 reduce but do not remove it.

• Precip accumulation. AI-weather precip may be cumulative or stepwise; daily-recharge conversion must be tested per model.

• Cost & tiling. High-resolution everywhere in the PNW daily is expensive; use watersheds for routing, tiles only for storage; surrogates for acceleration.

• Access sensitivities. OpenTopography (key), PRISM 800 m (license), SMAP (Earthdata), ERA5 (CDS), Synoptic (token), and some hazard-inventory locations (withheld) — recorded per-layer in the Limitations column of §1 (there is no separate access column).

Related¶

• Landslides · Post-fire debris flows · Liquefaction & Ground Failure — the hazard pages.

• Landslide Model · Liquefaction Model — the model pages whose outputs and inputs this inventory catalogs.

• DataHub · DataHub Integration Guide — platform, provenance standard, and repo migration path.

• Pillar 1 — Soil Reanalysis Product — the dynamic soil-state source.

• Repos: landlab-debrisflow · landslide-digital-twin · da-seis-groundfailure · gaia-nhsm-deagg · gaia-cli · solus-stac · prism-stac.