SSURGO tools

cycles.ssurgo

Ssurgo(path, state, *, lat_lon=None, boundary=None)

Load SSURGO lookup tables and extract soil profiles for locations.

When a location (lat_lon) or boundary polygon is provided, the map-unit table is filtered to include only those map units that intersect the location or polygon. When a boundary polygon is provided, the map-units are also grouped by name and symbol, and the major map unit is selected for profile extraction. The slope and hydrologic soil group (HSG) for the selected map unit are averaged across all map units that share the same name, weighted by area. When a point location is provided, the map unit that contains the point is selected.

Parameters:
  • path (str | Path) –

    Directory containing SSURGO geodatabase and lookup CSV files.

  • state (str) –

    State identifier

  • lat_lon (LatLon | None, default: None ) –

    Optional latitude/longitude for point-based spatial filtering.

  • boundary (GeoDataFrame | None, default: None ) –

    Optional boundary GeoDataFrame for polygon-based filtering.
Attributes:
  • state (str) –

    State identifier used in SSURGO file naming.

  • components (DataFrame) –

    DataFrame of soil component records from SSURGO lookup tables.

  • horizons (DataFrame) –

    DataFrame of soil horizon records from SSURGO lookup tables.

  • grouped_mapunits (MapUnitGeoDataFrame | None) –

    Grouped and dissolved map-unit GeoDataFrame when boundary filtering is used.

  • mukey (int | None) –

    Currently selected map-unit key (int), or None if not yet selected.

  • slope (float | None) –

    Slope gradient (%) for the selected map unit, or None if not selected.

  • hsg (str) –

    Hydrologic soil group code for the selected map unit.
Returns:
  • –

    None.
Raises:
  • ValueError –

    If both lat_lon and boundary are provided.

mapunits property

Return loaded map-unit table.

Returns:
  • MapUnitGeoDataFrame | DataFrame –

    Map-unit table as GeoDataFrame/DataFrame, or None if not loaded.

muname property

Return map-unit name for the currently selected MUKEY.

Returns:
  • str –

    Map-unit name string.

musym property

Return map-unit symbol for the currently selected MUKEY.

Returns:
  • str –

    Map-unit symbol string.

non_soil_mask(mapunits)

Build a mask for non-soil or urban map units.

Parameters:
  • mapunits (DataFrame | GeoDataFrame) –

    Map-unit table to evaluate.
Returns:
  • Series –

    Boolean Series where True indicates non-soil or urban classes.

get_soil_profile(*, mukey=None, major_only=True)

Build a soil profile from SSURGO components and horizons.

Parameters:
  • mukey (int | None, default: None ) –

    Optional map-unit key. If omitted, the selected major MUKEY is used.

  • major_only (bool, default: True ) –

    If True, include only components marked as major.
Returns:
  • list[SoilLayer] –

    Soil profile as a list of SoilLayer records.

generate_soil_file(fn, *, mukey=None, desc=None, hsg=None, slope=None, soil_depth=None)

Generate a Cycles soil file from SSURGO profile data.

Parameters:
  • fn (Path | str) –

    Output soil file path.

  • mukey (int | None, default: None ) –

    Optional map-unit key. If omitted, dominant MUKEY is used.

  • desc (str | None, default: None ) –

    Optional custom header text for the output file.

  • hsg (str | None, default: None ) –

    Optional hydrologic soil group; inferred from map unit if omitted.

  • slope (float | None, default: None ) –

    Optional slope value; inferred from map unit if omitted.

  • soil_depth (float | None, default: None ) –

    Optional maximum depth (m) used during profile mapping.
Returns:
  • None –

    None.