SoilGrids tools

cycles.soilgrids

SoilGrids(path, *, maps=ALL_MAPS, crs=None, aggregated=None)

Read SoilGrids rasters and build Cycles-compatible soil profiles.

Parameters:
  • path (str | Path) –

    Directory containing downloaded SoilGrids rasters.

  • maps (list[str], default: ALL_MAPS ) –

    Optional map identifiers in property@layer format. If not provided, all available maps are loaded.

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

    Optional target CRS for reprojection.

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

    Optional aggregated resolution (1000 or 5000 m).
Attributes:
  • crs (str) –

    Coordinate reference system used for raster operations.

  • maps (dict[str, DataArray]) –

    Dictionary mapping map identifiers to loaded xarray DataArrays.

  • transformer –

    Pyproj Transformer for converting coordinates from EPSG:4326 to the target CRS.

  • matched_maps (DataFrame | None) –

    DataFrame of reprojected and matched map values, populated after calling reproject_match().

reproject_match(*, reference_xds, reference_name, boundary)

Reproject loaded maps to a reference raster grid.

Parameters:
  • reference_xds (DataArray) –

    Reference raster whose CRS, transform, and resolution are used for reprojection.

  • reference_name (str) –

    Column name used for the reference raster values in the generated matched table.

  • boundary (GeoDataFrame) –

    Boundary geometry used to clip all rasters after reprojection.
Returns:
  • None –

    None.

get_soil_profile(lat_lon)

Sample loaded maps at a coordinate and build a soil profile.

Parameters:
  • lat_lon (LatLon) –

    Latitude and longitude pair in EPSG:4326.
Returns:
  • list[SoilLayer] –

    Soil layers populated from SoilGrids values at the nearest grid cell.

generate_soil_file(fn, lat_lon, *, desc=None, hsg='', slope=None)

Generate a Cycles soil file from SoilGrids values.

Parameters:
  • fn (Path | str) –

    Output soil file path.

  • lat_lon (LatLon) –

    Latitude and longitude pair in EPSG:4326.

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

    Optional custom header text for the output file.

  • hsg (str, default: '' ) –

    Optional hydrologic soil group code used for curve-number mapping.

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

    Optional slope value written to the soil file header.
Returns:
  • None –

    None.

download_soilgrids_data(path, *, maps=ALL_MAPS, boundary=None, bbox=None, crs='epsg:4326')

Download SoilGrids raster layers via WCS.

You can provide either a boundary polygon or an explicit bounding box. Bounding boxes are expected in (west, south, east, north) order.

Parameters:
  • path (str | Path) –

    Directory where downloaded GeoTIFF files are written.

  • maps (list[str], default: ALL_MAPS ) –

    Map identifiers in property@layer format.

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

    Optional polygon used to derive a buffered bounding box.

  • bbox (tuple[float, float, float, float] | None, default: None ) –

    Optional explicit bounding box as (west, south, east, north).

  • crs (str, default: 'epsg:4326' ) –

    CRS of the provided bbox coordinates.
Returns:
  • None –

    None.
Raises:
  • ValueError –

    If neither boundary nor bbox is provided.