ADR-0008: SSURGO Reclaimed Soil Restrictive Layer Fallback
Status: Accepted Date: 2026-06-22
Context
The 2025 gNATSGO raster can select reclaimed mine-land Fairpoint map units for
watershed elements that previously resolved to older Shelocta-Latham map units.
The affected Fairpoint MUKEYs 3294459, 3294460, and 3294461 have valid
SSURGO component and horizon data, but their first horizon has very low
ksat_r. The previous restrictive-layer rule marked that first horizon as the
restrictive layer, emitted zero WEPP soil layers, and caused the MUKEYs to be
treated as invalid. The gridded soil builder then substituted a different valid
soil without preserving the original raster-selected MUKEY.
The historical restrictive-layer rule is understood by the operator to have come from Erin Brooks's Lake Tahoe WEPP calibration work. That precedent used measured Tahoe Basin Soil Survey properties because default WEPP pedotransfer functions were not appropriate for steep, rocky forest soils, and it treated consolidated bedrock beneath Tahoe watersheds as a hydrologic lower boundary. That is a different physical case from a reclaimed mine-land profile whose first valid SSURGO horizon is itself a low-conductivity soil horizon.
Decision
WEPPcloud will retain the first valid horizon as a WEPP soil layer even when its
ksat_r is below the restrictive-layer threshold. Restrictive-layer truncation
may start only after at least one valid horizon has been emitted.
The gridded Soils controller will also preserve raw SSURGO dominant MUKEYs in
raw_ssurgo_domsoil_d and record replacements in ssurgo_substitution_d.
Existing domsoil_d and ssurgo_domsoil_d remain final, WEPP-usable dominant
soil maps for backward compatibility.
Decision Provenance (Required for Parameterization Changes)
Decision Venue: Codex work package execution, 2026-06-22 11:50 America/Los_Angeles Participants Present: WEPPcloud operator/user, Codex coding agent Decision Owner(s): WEPPcloud operator/user Implementer(s): Codex coding agent
Change Summary
Old behavior:
- Any valid horizon with
ksat_r < 2.0 um/scould becomeres_lyr_i. - If the first valid horizon met that condition,
num_layersbecame0. - The soil failed
WeppSoil.valid()withValidity: no horizons. - Gridded fallback replaced invalid dominant MUKEYs in
domsoil_dwithout storing the original raster-selected MUKEY.
New behavior:
res_lyr_ksat_thresholdremains2.0 um/s.- The first valid low-
ksat_rhorizon is retained as a WEPP layer. - A later low-
ksat_rhorizon can still mark the restrictive layer and truncate the profile below the retained layer. - Gridded fallback stores raw dominant MUKEYs separately and records each
substitution with
raw_mukey,replacement_mukey, and reasoninvalid_dominant_mukey.
Rationale
The Fairpoint reclaimed map units represent current SSURGO mapping for the reported watershed elements. Treating a valid first horizon as a zero-layer profile makes the data unusable even though WEPP can model the low-conductivity surface layer directly. Keeping one valid layer preserves the updated map unit identity and avoids falling back to older neighboring soils.
Separate raw/final dominant maps let operators audit fallback behavior without
breaking downstream code that expects domsoil_d and ssurgo_domsoil_d to
reference generated .sol files.
Tahoe Restrictive-Layer Interpretation
Brooks et al. (2016) evaluated WEPP in Lake Tahoe watersheds and built soil inputs from measured Tahoe Basin Soil Survey properties rather than relying on default WEPP pedotransfer functions for steep, rocky forest soils. The paper also describes steep Tahoe watersheds underlain by consolidated bedrock and uses baseflow/deep-percolation partitioning to reason about the lower boundary.
WEPPcloud interprets that precedent as support for truncating a modeled soil
mantle at restrictive material below at least one emitted soil layer, then
using the lower-boundary conductivity behavior (kslast) for the material
beneath the modeled profile. It is not interpreted as support for rejecting a
valid first mineral horizon and producing a zero-layer WEPP soil.
Local run evidence matches this distinction. The Blackwood/Lake Tahoe run
/wc1/runs/ma/mammalian-ageism has 231 hillslopes with restrictive profiles
but zero hillslopes that would have hit the prior first-horizon zero-layer
reassignment case. The reclaimed mine-land run
/wc1/runs/ha/hard-line-foothold has 73 restrictive-profile hillslopes, 71 of
which are first-valid-horizon cases that the previous rule would have rejected
and reassigned.
Alternatives Considered
- Lower or disable
res_lyr_ksat_thresholdfor reclaimed mine lands - rejected because it changes the threshold semantics globally or requires a new classification rule. - Generate a synthetic placeholder layer above the restrictive horizon - rejected because it invents a horizon not present in SSURGO.
- Change
ssurgo_domsoil_dto raw MUKEYs - rejected because existing consumers rely on it matching generated WEPP soil files.
Consequences
Fairpoint MUKEYs 3294459, 3294460, and 3294461 now produce valid WEPP
soil files with at least one layer. Profiles whose first valid horizon is below
the restrictive threshold will no longer be represented as zero-layer invalid
soils. Tahoe-style profiles with restrictive material below one or more valid
soil layers still truncate below the emitted soil mantle. The fallback
provenance fields are additive NoDb data and parquet columns; old NoDb payloads
are backfilled with None and {} defaults.
Evidence
- Work package:
docs/work-packages/20260622_ssurgo_reclaimed_soil_fallback/ - Reported production run:
https://wepp.cloud/weppcloud/runs/hard-line-foothold/disturbed9002/ - Target watershed elements: Topaz IDs
573and581 - Integrated regression MUKEYs:
3294459,3294460,3294461 - Brooks, Dobre, Elliot, Wu, and Boll (2016), "Watershed-scale evaluation of
the Water Erosion Prediction Project (WEPP) model in the Lake Tahoe basin":
https://research.fs.usda.gov/download/treesearch/50802.pdf - Tahoe comparison run:
/wc1/runs/ma/mammalian-ageismhas 231 restrictive profile hillslopes and zero prior-rule zero-layer reassignment cases. - Reclaimed comparison run:
/wc1/runs/ha/hard-line-footholdhas 73 restrictive-profile hillslopes and 71 prior-rule zero-layer reassignment cases.
Risk and Rollback Notes
Risk: shallow, very low-conductivity profiles will now run instead of falling back to a neighboring valid soil. Monitor generated soil logs for unexpectedly high counts of retained first-horizon restrictive profiles.
Rollback: restore the previous _analyze_restrictive_layer() rule and remove or
ignore the additive provenance fields. Existing generated runs are unaffected
unless soils are rebuilt.
Implementation Notes
Unit tests cover the three Fairpoint MUKEYs with deterministic SSURGO table rows
and verify that generated .sol files exist. NoDb tests cover raw dominant
MUKEY preservation, substitution records, and nullable summary fields.