r.soils.rosetta

Estimate van Genuchten soil hydraulic parameters from soil texture using the ROSETTA pedotransfer model.

Command linePython (grass.tools)Python (grass.script)

r.soils.rosetta [-u] sand=name silt=name clay=name [bulk_density=name] [water_content_33=name] [water_content_1500=name] [version=integer] [theta_r=name] [theta_s=name] [alpha=name] [n=name] [ksat=name] [ksat_units=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.soils.rosetta sand=name silt=name clay=name

grass.tools.Tools.r_soils_rosetta(sand, silt, clay, bulk_density=None, water_content_33=None, water_content_1500=None, version=3, theta_r=None, theta_s=None, alpha=None, n=None, ksat=None, ksat_units="mm_per_hour", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_soils_rosetta(sand="name", silt="name", clay="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.run_command("r.soils.rosetta", sand, silt, clay, bulk_density=None, water_content_33=None, water_content_1500=None, version=3, theta_r=None, theta_s=None, alpha=None, n=None, ksat=None, ksat_units="mm_per_hour", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.soils.rosetta", sand="name", silt="name", clay="name")

Parameters

Command linePython (grass.tools)Python (grass.script)

sand=name [required]
    Sand content raster map [percent, 0-100]
silt=name [required]
    Silt content raster map [percent, 0-100]
clay=name [required]
    Clay content raster map [percent, 0-100]
bulk_density=name
    Bulk density raster map [g/cm3] (enables ROSETTA model 3)
water_content_33=name
    Volumetric water content at 33 kPa raster map [cm3/cm3] (enables ROSETTA model 4)
water_content_1500=name
    Volumetric water content at 1500 kPa raster map [cm3/cm3] (enables ROSETTA model 5)
version=integer
    ROSETTA model calibration version (3 = Zhang and Schaap 2017)
    Allowed values: 1, 2, 3
    Default: 3
theta_r=name
    Output residual water content raster map [cm3/cm3]
theta_s=name
    Output saturated water content raster map [cm3/cm3]
alpha=name
    Output van Genuchten alpha raster map [1/cm]
n=name
    Output van Genuchten n raster map [dimensionless]
ksat=name
    Output saturated hydraulic conductivity raster map
ksat_units=string
    Units for the ksat output map
    Allowed values: mm_per_hour, cm_per_day
    Default: mm_per_hour
-u
    Also write per-parameter uncertainty (standard deviation) maps as <output>_stddev
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

sand : str | np.ndarray, required
    Sand content raster map [percent, 0-100]
    Used as: input, raster, name
silt : str | np.ndarray, required
    Silt content raster map [percent, 0-100]
    Used as: input, raster, name
clay : str | np.ndarray, required
    Clay content raster map [percent, 0-100]
    Used as: input, raster, name
bulk_density : str | np.ndarray, optional
    Bulk density raster map [g/cm3] (enables ROSETTA model 3)
    Used as: input, raster, name
water_content_33 : str | np.ndarray, optional
    Volumetric water content at 33 kPa raster map [cm3/cm3] (enables ROSETTA model 4)
    Used as: input, raster, name
water_content_1500 : str | np.ndarray, optional
    Volumetric water content at 1500 kPa raster map [cm3/cm3] (enables ROSETTA model 5)
    Used as: input, raster, name
version : int, optional
    ROSETTA model calibration version (3 = Zhang and Schaap 2017)
    Allowed values: 1, 2, 3
    Default: 3
theta_r : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output residual water content raster map [cm3/cm3]
    Used as: output, raster, name
theta_s : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output saturated water content raster map [cm3/cm3]
    Used as: output, raster, name
alpha : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output van Genuchten alpha raster map [1/cm]
    Used as: output, raster, name
n : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output van Genuchten n raster map [dimensionless]
    Used as: output, raster, name
ksat : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output saturated hydraulic conductivity raster map
    Used as: output, raster, name
ksat_units : str, optional
    Units for the ksat output map
    Allowed values: mm_per_hour, cm_per_day
    Default: mm_per_hour
flags : str, optional
    Allowed values: u
    u
        Also write per-parameter uncertainty (standard deviation) maps as <output>_stddev
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

Raises:

grass.tools.ToolError: When the tool ended with an error.

sand : str, required
    Sand content raster map [percent, 0-100]
    Used as: input, raster, name
silt : str, required
    Silt content raster map [percent, 0-100]
    Used as: input, raster, name
clay : str, required
    Clay content raster map [percent, 0-100]
    Used as: input, raster, name
bulk_density : str, optional
    Bulk density raster map [g/cm3] (enables ROSETTA model 3)
    Used as: input, raster, name
water_content_33 : str, optional
    Volumetric water content at 33 kPa raster map [cm3/cm3] (enables ROSETTA model 4)
    Used as: input, raster, name
water_content_1500 : str, optional
    Volumetric water content at 1500 kPa raster map [cm3/cm3] (enables ROSETTA model 5)
    Used as: input, raster, name
version : int, optional
    ROSETTA model calibration version (3 = Zhang and Schaap 2017)
    Allowed values: 1, 2, 3
    Default: 3
theta_r : str, optional
    Output residual water content raster map [cm3/cm3]
    Used as: output, raster, name
theta_s : str, optional
    Output saturated water content raster map [cm3/cm3]
    Used as: output, raster, name
alpha : str, optional
    Output van Genuchten alpha raster map [1/cm]
    Used as: output, raster, name
n : str, optional
    Output van Genuchten n raster map [dimensionless]
    Used as: output, raster, name
ksat : str, optional
    Output saturated hydraulic conductivity raster map
    Used as: output, raster, name
ksat_units : str, optional
    Units for the ksat output map
    Allowed values: mm_per_hour, cm_per_day
    Default: mm_per_hour
flags : str, optional
    Allowed values: u
    u
        Also write per-parameter uncertainty (standard deviation) maps as <output>_stddev
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

r.soils.rosetta estimates Mualem-van Genuchten soil hydraulic parameters from soil texture using the ROSETTA pedotransfer model (Schaap et al. 2001; Zhang and Schaap 2017). It is a raster transform: given per-cell soil texture maps it predicts, for each cell, the residual water content (theta_r), saturated water content (theta_s), the van Genuchten alpha and n shape parameters, and the saturated hydraulic conductivity (ksat).

The required inputs are the USDA soil texture separates sand, silt, and clay, each as a percentage (0-100). Prediction accuracy increases as optional inputs are added, in this fixed order: bulk_density (g/cm3), water_content_33 (volumetric water content at 33 kPa, cm3/cm3), and water_content_1500 (volumetric water content at 1500 kPa, cm3/cm3). The set of supplied inputs selects the ROSETTA model automatically:

Model	Inputs
2	sand, silt, clay
3	+ bulk_density
4	+ water_content_33
5	+ water_content_1500

Only the outputs you name are computed. The ksat map is written in mm/hr by default (ksat_units=mm_per_hour) so it can be used directly by hydrologic tools such as r.sim.water; set ksat_units=cm_per_day for ROSETTA's native units.

NOTES

The tool uses the offline rosetta-soil Python package (pip install rosetta-soil). When the package is not installed it falls back to the handbook60.org ROSETTA web API, which requires network access; the offline package is recommended for reproducible runs. The uncertainty maps produced by the -u flag are only available with the offline package.

ROSETTA reports alpha, n, and ksat as base-10 logarithms and ksat in cm/day; the tool back-transforms these to linear units and converts ksat to the requested units. The -u standard-deviation maps for alpha, n, and ksat remain in log10 space (the standard deviation of the log10 parameter), while theta_r and theta_s uncertainties are linear.

A cell is predicted only where every supplied input map has data; cells that are NULL in any input are NULL in all outputs. Because ROSETTA output depends only on the input tuple, the tool predicts each unique combination once, which makes it efficient on categorical inputs such as SSURGO map units.

ROSETTA is nonlinear, so applying it to depth-aggregated texture is not the same as aggregating hydraulic parameters computed per horizon. When driving the model from SSURGO map-unit texture (as in the workflow below), the texture has already been depth-weighted to a single value per map unit; interpret the result accordingly.

The tool respects the current computational region and mask and writes outputs to the current mapset.

EXAMPLES

Estimate hydraulic parameters from texture maps

g.region raster=sand -p
r.soils.rosetta sand=sand silt=silt clay=clay bulk_density=bd \
  theta_s=theta_s alpha=alpha n=n ksat=ksat version=3

Complete workflow: SSURGO to SIMWE

Import SSURGO with r.in.ssurgo, which writes depth-weighted texture and bulk-density rasters, estimate Ksat with r.soils.rosetta, then run overland flow with r.sim.water.

g.region raster=elevation -p

# Import SSURGO texture and bulk density for the top 25.4 cm.
r.in.ssurgo ssurgo_path=wss_SSA.zip soils=soils \
  sand=sand silt=silt clay=clay bulk_density=bd \
  hzdept_r=0 hzdepb_r=25.4

# Predict saturated hydraulic conductivity (mm/hr).
r.soils.rosetta sand=sand silt=silt clay=clay bulk_density=bd \
  ksat=ksat_vg version=3 ksat_units=mm_per_hour

# Partial derivatives of the surface for the flow solver.
r.slope.aspect elevation=elevation dx=dx dy=dy

Figure: ROSETTA-estimated saturated hydraulic conductivity (mm/hr) from SSURGO texture and bulk density over shaded relief (NC sample dataset, Lake Wheeler area). Low-conductivity alluvial soils trace the drainage network; gray areas are map units without soil data.

Figure: ROSETTA-estimated saturated water content theta_s (cm3/cm3) for the same area.

Ksat then enters r.sim.water in one of two ways. Both interpret Ksat as the steady-state infiltration rate; do not use both at once or infiltration is counted twice.

Variant 1: supply Ksat as the infiltration loss on flowing water (infil):

r.sim.water elevation=elevation dx=dx dy=dy \
  rain_value=50 infil=ksat_vg man_value=0.1 \
  depth=depth discharge=discharge -t

Variant 2: fold Ksat into the rainfall excess (rain) and leave infil off. Rainfall excess is rainfall intensity minus infiltration, in mm/hr:

r.mapcalc "rain_excess = max(0.0, 50.0 - ksat_vg)"
r.sim.water elevation=elevation dx=dx dy=dy \
  rain=rain_excess man_value=0.1 \
  depth=depth discharge=discharge -t

REFERENCES

Schaap, M.G., Leij, F.J., and van Genuchten, M.T. (2001). ROSETTA: a computer program for estimating soil hydraulic parameters with hierarchical pedotransfer functions. Journal of Hydrology 251(3-4): 163-176.
Zhang, Y. and Schaap, M.G. (2017). Weighted recalibration of the Rosetta pedotransfer model with improved estimates of hydraulic parameter distributions and summary statistics (Rosetta3). Journal of Hydrology 547: 39-53.

AUTHORS

Corey T. White, Center for Geospatial Analytics, NC State University

SOURCE CODE

Available at: r.soils.rosetta source code (history)
Latest change: Thursday Sep 03 04:43:28 2026 in commit 96c6e42

r.soils.rosetta

Parameters

DESCRIPTION

NOTES

EXAMPLES

Estimate hydraulic parameters from texture maps

Complete workflow: SSURGO to SIMWE

REFERENCES

SEE ALSO

AUTHORS

SOURCE CODE