WEPPcloud

← Back to help

SSURGO for M3 Soil Thickness

Updated 2026-09-09 after bounded acquisition and offline paired evaluation. Owner direction now approves SSURGO primary and original STATSGO THICK fallback. Production integration and detailed fallback policy remain pending.

Execution follow-up: M3 soil work package. Its fresh-agent plan includes explicit soil acquisition/inventory because the committed terrain fixtures contain no soil tables and current availability of the named live runs does not establish populated SSURGO caches.

Measured follow-up

The three live projects had no soils/ directories. Study acquisition froze 111 original map units, 390 components and 1,506 horizons, with survey lineage, queries and hashes, plus bounded original STATSGO THICK windows. All 12 sampled catchments had incomplete component support; strict soil treatment was unavailable at two Topanga outlets. Keeping all recorded layers materially changed results. Source substitution is not justified by mapping detail alone.

The canonical offline contract and ADR-0053 now define executable interval, weighting, coverage and units. The source decision records historical measured effects and uncertainty. The subsequent owner decision supersedes its retain-STATSGO recommendation: SSURGO is primary and STATSGO is fallback. No runtime fallback is implemented.

Initial feasibility finding

SSURGO is a feasible source for an M3 cumulative soil-profile thickness estimate. Current Soils builds already cache the relevant raw fields in the project. Reuse those records and spatial map units rather than WEPP's processed profile depth. Source substitution from STATSGO to SSURGO still needs validation and an ADR before implementation.

Original Predictor and Units

The USGS source metadata defines THICK as cumulative thickness of all soil layers, in inches. Processing documentation describes summing layer bottom-minus-top depths. This is not automatically depth to the first restrictive layer, bedrock depth, or root-zone depth.

USGS also distributes the original predictor as a STATSGO THICK COG, explicitly in inches, nominally rasterized at 30 m. Its fine raster spacing does not increase the original soil-map detail. It provides a useful comparison baseline and the approved fallback source; runtime fallback rules are pending. Its metadata identifies NaN and nonphysical -0.1 water values that must not enter a thickness mean.

For a valid SSURGO thickness d_cm, the M3 scaling is d_cm / 254. Example: 100 cm = 39.3700787 inches, giving S = 0.393700787, not 1.0.

Existing Project Data

Existing source Evidence and reuse
Soils.ssurgo_cache_db_path Points to soils/ssurgo_tabular_cache.sqlite; separate STATSGO cache also exists
component Cached mukey, cokey, comppct_r support map-unit/component joins and weights
chorizon Cached chkey, hzdept_r, hzdepb_r, hzthk_r, desgnmaster, and hzname support raw interval analysis
Soils.ssurgo_fn Project soil map-unit raster for spatial lookup; audit coverage and substitutions before use
raw_ssurgo_domsoil_d, ssurgo_substitution_d Existing provenance helps identify substituted soil assignments

Code evidence: wepppy/nodb/core/soils.py defines the cache paths and builds collections for map-unit keys; wepppy/soils/ssurgo/ssurgo.py fetches component and horizon records and defines the cache schema. The collection fetches horizons for all cached components of requested map units, before selecting WEPP-compatible profiles. Reading raw cache records avoids WEPP layer filtering.

The NRCS Fundamental Query guide defines horizon top and bottom depths in centimeters and notes that multiple records can share the same depth interval. Deduplication/overlap treatment is therefore a real data concern, not just a hypothetical edge case.

Existing Outputs That Cannot Be Reused Directly

  • WEPP .sol depth: generated in mm, with possible minimum-depth changes, clipping, rounding, invalid-horizon filtering, and conductivity-based restrictive-layer handling. These serve simulation requirements and do not define the source STATSGO thickness predictor.
  • SurgoSpatializer SolThk: currently sums hzdepb_r across horizons. These are cumulative bottom depths. For intervals 0-10 and 10-30 cm, it returns 10 + 30 = 40 cm rather than the actual 30 cm thickness. This is a confirmed unsuitable derivation for M3, left unchanged in this docs-only work.
  • Restriction-depth lookup: current corestrictions cache holds cokey and reskind, not resdept_r. It cannot supply numeric restriction depth without extending acquisition/schema, and that would be a different predictor.
  • Dominant WEPP profile alone: is not the same as a component-weighted map-unit estimate; substitutions must not be mistaken for original SSURGO.

Proposed Derivation and Remaining Decisions

  1. Require completed Soils data and inspect source provenance/cache coverage. Legacy, custom, or fallback-built soil inventories may not provide SSURGO horizons even when WEPP can run successfully.
  2. Read raw horizons by component and validate finite top/bottom depths and positive intervals. Resolve duplicate/overlapping intervals, profile gaps, and which bedrock designations to exclude before defining thickness.
  3. Compute cumulative soil-layer thickness from valid intervals. For a complete contiguous profile starting at zero this equals the deepest soil-horizon bottom; that shortcut is not valid for arbitrary incomplete records.
  4. Propose weighting components using comppct_r, then map-unit contributions by their area in each assessment catchment. Resolve missing component percentages and partial coverage explicitly; no silent renormalization.
  5. Convert cm to inches and divide by 100 for M3, preserving full precision. Write source and aggregation provenance in the eventual output artifact.
  6. Compare against original STATSGO THICK for representative Western US projects, measuring both thickness differences and resulting M3 probability/threshold differences. More detailed soil mapping does not itself prove improved performance of the empirical model.

No fixed 150/200 cm depth, zero-fill, POLARIS layer-depth substitution, WEPP clipped-depth substitution, or automatic network fallback is established. Missing/invalid thickness needs an explicit unavailable result or submission error according to the eventual catchment-coverage contract. Unknown depth must not be described as confirmed zero soil thickness.

Acceptance Before Runtime Work

Specify the depth and aggregation policy in an ADR and canonical contract, audit representative project caches, and cover duplicate/gapped/bedrock horizons, missing components, custom/legacy sources, and unit equivalence. Any additive thickness artifact/schema needs a compatibility plan and tests showing propagation to the actual assessment outputs. Keep existing Soils and RUSLE artifacts unchanged unless separately authorized by the implementation contract. Follow the owned geospatial stack for raster aggregation.