WEPPcloud

← Back to help

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/s could become res_lyr_i.
  • If the first valid horizon met that condition, num_layers became 0.
  • The soil failed WeppSoil.valid() with Validity: no horizons.
  • Gridded fallback replaced invalid dominant MUKEYs in domsoil_d without storing the original raster-selected MUKEY.

New behavior:

  • res_lyr_ksat_threshold remains 2.0 um/s.
  • The first valid low-ksat_r horizon is retained as a WEPP layer.
  • A later low-ksat_r horizon 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 reason invalid_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

  1. Lower or disable res_lyr_ksat_threshold for reclaimed mine lands - rejected because it changes the threshold semantics globally or requires a new classification rule.
  2. Generate a synthetic placeholder layer above the restrictive horizon - rejected because it invents a horizon not present in SSURGO.
  3. Change ssurgo_domsoil_d to 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 573 and 581
  • 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-ageism has 231 restrictive profile hillslopes and zero prior-rule zero-layer reassignment cases.
  • Reclaimed comparison run: /wc1/runs/ha/hard-line-foothold has 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.