soilgrids

soilgrids provides a set of functions that allow downloading of the global gridded soil information from SoilGrids, a system for global digital soil mapping to map the spatial distribution of soil properties across the globe.

soilgrids also includes a Basic Model Interface (BMI), which converts the SoilGrids dataset into a reusable, plug-and-play data component (pymt_soilgrids) for the PyMT modeling framework developed by Community Surface Dynamics Modeling System (CSDMS).

If you have any suggestion to improve the current function, please create a github issue here.

Install package

Stable Release

The soilgrids package and its dependencies can be installed with pip $ pip install soilgrids or with conda. $ conda install -c conda-forge soilgrids

From Source

After downloading the source code, run the following command from top-level folder to install soilgrids. $ pip install -e .

Citation

Please include the following references when citing this software package:

Gan, T., Tucker, G.E., Hutton, E.W.H., Piper, M.D., Overeem, I., Kettner, A.J., Campforts, B., Moriarty, J.M., Undzis, B., Pierce, E., McCready, L., 2024: CSDMS Data Components: data–model integration tools for Earth surface processes modeling. Geosci. Model Dev., 17, 2165–2185. https://doi.org/10.5194/gmd-17-2165-2024

Gan, T. (2023). CSDMS SoilGrids Data Component. Zenodo. https://doi.org/10.5281/zenodo.10368882

Quick Start

Below shows how to use two methods to download the SoilGrids datasets.

You can learn more details from the tutorial notebook. To run this notebook, please go to the CSDMS EKT Lab and follow the instruction in the "Lab notes" section.

Example 1: use SoilGrids class to download data (Recommended method)

```python import matplotlib.pyplot as plt from soilgrids import SoilGrids

get data from SoilGrids

soilgrids = SoilGrids() data = soilgrids.getcoveragedata( serviceid="phh2o", coverageid="phh2o0-5cmmean", west=-1784000, south=1356000, east=-1140000, north=1863000, crs="urn:ogc:def:crs:EPSG::152160", output="test.tif", )

show metadata

for key, value in soil_grids.metadata.items(): print(f"{key}: {value}")

plot data

data.plot(figsize=(9, 5), vmin=0) plt.title("Mean pH between 0 and 5 cm soil depth in Senegal") ```

Example 2: use BmiSoilGrids class to download data (Demonstration of how to use BMI)

```python import matplotlib.pyplot as plt import numpy as np

from soilgrids import BmiSoilGrids

initiate a data component

datacomp = BmiSoilGrids() datacomp.initialize("config_file.yaml")

get variable info

varname = datacomp.getoutputvarnames()[0] varunit = datacomp.getvarunits(varname) varlocation = datacomp.getvarlocation(varname) vartype = datacomp.getvartype(varname) vargrid = datacomp.getvargrid(var_name)

print(f"{varname=}") print(f"{varunit=}") print(f"{varlocation=}") print(f"{vartype=}") print(f"{var_grid=}")

get variable grid info

gridrank = datacomp.getgridrank(var_grid)

gridsize = datacomp.getgridsize(var_grid)

gridshape = np.empty(gridrank, int) datacomp.getgridshape(vargrid, grid_shape)

gridspacing = np.empty(gridrank) datacomp.getgridspacing(vargrid, grid_spacing)

gridorigin = np.empty(gridrank) datacomp.getgridorigin(vargrid, grid_origin)

print(f"{gridrank=}") print(f"{gridsize=}") print(f"{gridshape=}") print(f"{gridspacing=}") print(f"{grid_origin=}")

get variable data

data = np.empty(gridsize, vartype) datacomp.getvalue(varname, data) data2D = data.reshape(grid_shape)

get X, Y extent for plot

miny, minx = gridorigin maxy = miny + gridspacing[0] * (gridshape[0] - 1) maxx = minx + gridspacing[1] * (gridshape[1] - 1) dy = gridspacing[0] / 2 dx = gridspacing[1] / 2 extent = [minx - dx, maxx + dx, miny - dy, max_y + dy]

plot data

fig, ax = plt.subplots(1, 1, figsize=(9, 5)) im = ax.imshow(data_2D, extent=extent, vmin=0) fig.colorbar(im) plt.xlabel("X") plt.ylabel("Y") plt.title("Mean pH between 0 and 5 cm soil depth in Senegal")

finalize data component

data_comp.finalize() ```