Skip to content

r.dem.stats

Compute terrain surface metrics used as DoD predictors

r.dem.stats [-e] input=name output=name metric=string [window=integer] [log_base=string] [slope_format=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.dem.stats input=name output=name metric=slope

grass.tools.Tools.r_dem_stats(input, output, metric, window=7, log_base="e", slope_format="degrees", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_dem_stats(input="name", output="name", metric="slope")

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

grass.script.run_command("r.dem.stats", input, output, metric, window=7, log_base="e", slope_format="degrees", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.dem.stats", input="name", output="name", metric="slope")

Parameters

input=name [required]
    Input DEM (or DoD raster for metric=error_sigma_local)
output=name [required]
    Output surface-metric raster
metric=string [required]
    Surface metric to compute
    Allowed values: slope, roughness_std, diversity_geomorphon, diversity_shannon, error_sigma_local
window=integer
    Moving window size in cells (odd integer >= 3)
    Default: 7
log_base=string
    Logarithm base for Shannon diversity
    Allowed values: e, 2, 10
    Default: e
slope_format=string
    Output format for slope
    Allowed values: degrees, radians
    Default: degrees
-e
    Also compute Shannon evenness (metric=diversity_shannon)
--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

input : str | np.ndarray, required
    Input DEM (or DoD raster for metric=error_sigma_local)
    Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Output surface-metric raster
    Used as: output, raster, name
metric : str, required
    Surface metric to compute
    Allowed values: slope, roughness_std, diversity_geomorphon, diversity_shannon, error_sigma_local
window : int, optional
    Moving window size in cells (odd integer >= 3)
    Default: 7
log_base : str, optional
    Logarithm base for Shannon diversity
    Allowed values: e, 2, 10
    Default: e
slope_format : str, optional
    Output format for slope
    Allowed values: degrees, radians
    Default: degrees
flags : str, optional
    Allowed values: e
    e
        Also compute Shannon evenness (metric=diversity_shannon)
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.

input : str, required
    Input DEM (or DoD raster for metric=error_sigma_local)
    Used as: input, raster, name
output : str, required
    Output surface-metric raster
    Used as: output, raster, name
metric : str, required
    Surface metric to compute
    Allowed values: slope, roughness_std, diversity_geomorphon, diversity_shannon, error_sigma_local
window : int, optional
    Moving window size in cells (odd integer >= 3)
    Default: 7
log_base : str, optional
    Logarithm base for Shannon diversity
    Allowed values: e, 2, 10
    Default: e
slope_format : str, optional
    Output format for slope
    Allowed values: degrees, radians
    Default: degrees
flags : str, optional
    Allowed values: e
    e
        Also compute Shannon evenness (metric=diversity_shannon)
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.dem.stats computes terrain surface metrics from a DEM (or a DEM of Difference). The outputs are the predictor rasters used to model terrain-correlated DoD uncertainty and systematic bias, for example as inputs to r.dem.bias or as an uncertainty source for r.dem.errprop.

A single metric is selected per run through the metric option:

  • slope: surface slope from r.slope.aspect, in degrees or radians as selected with slope_format (default degrees).
  • roughness_std: local roughness as the Gaussian-weighted focal standard deviation of elevation (r.neighbors).
  • diversity_geomorphon: landform category richness in a moving window, computed from r.geomorphon forms.
  • diversity_shannon: local Shannon diversity H' = -sum(p * log(p)) over category proportions in a window, computed from a categorical input such as a geomorphon forms map. The logarithm base is selected with log_base (e, 2, or 10; default e). With the -e flag the matching Shannon evenness J = H' / log(S) is also written as <output>_evenness.
  • error_sigma_local: a robust local standard deviation via the median absolute deviation, sigma = 1.4826 * median(|x - median(x)|) in a moving window. Use a DoD raster as input to obtain a spatially varying DoD uncertainty surface.

NOTES

The window must be an odd integer of at least 3 cells. Focal metrics use a Gaussian weighting whose falloff is derived from the window radius, matching the focal behavior used throughout the DoD workflow.

For diversity_shannon the input is expected to be categorical (integer classes). A natural pairing is to first compute a geomorphon forms map and then run r.dem.stats with metric=diversity_shannon on that map.

Intermediate rasters are removed on exit. The tool honours the current computational region and the --overwrite flag.

EXAMPLES

The commands below use the example scene built in the r.dem toolset manual, which is derived from the North Carolina sample dataset. Build it there first.

Derive the terrain predictors used by r.dem.bias method=regression and as diagnostic surfaces:

g.region raster=elev_lid792_1m

r.dem.stats input=elev_lid792_1m output=slope metric=slope
r.dem.stats input=elev_lid792_1m output=roughness \
    metric=roughness_std window=13
r.dem.stats input=elev_lid792_1m output=landforms \
    metric=diversity_geomorphon window=13

The slope metric is r.slope.aspect under the tool's own naming, so the two agree cell for cell.

metric=diversity_shannon needs a categorical map rather than an elevation surface, so derive the geomorphon forms first and run the metric on those. The -e flag adds the matching evenness raster:

r.geomorphon elevation=elev_lid792_1m forms=landform_classes \
    search=7 flat=4

r.dem.stats -e input=landform_classes output=landform_diversity \
    metric=diversity_shannon window=13

r.dem.stats example
Figure: Slope, roughness, and geomorphon diversity on the lidar reference.

SEE ALSO

r.dem, r.dem.bias, r.dem.errprop, r.geomorphon, r.neighbors, r.slope.aspect

AUTHORS

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

SOURCE CODE

Available at: r.dem.stats source code (history)
Latest change: Thursday Aug 20 19:32:37 2026 in commit d08d385