Skip to content

r.dem.errprop

Propagate DEM uncertainty into a DoD and derive significance

r.dem.errprop dod=name sigma=name [,name,...] [sigma_const=float [,float,...]] output_sigma=name [output_lod=name] [output_zscore=name] [output_pvalue=name] [output_class=name] [confidence=float] [pmethod=string] [df=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.dem.errprop dod=name sigma=name output_sigma=name

grass.tools.Tools.r_dem_errprop(dod, sigma, sigma_const=None, output_sigma, output_lod=None, output_zscore=None, output_pvalue=None, output_class=None, confidence=0.95, pmethod="normal", df=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_dem_errprop(dod="name", sigma="name", output_sigma="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.dem.errprop", dod, sigma, sigma_const=None, output_sigma, output_lod=None, output_zscore=None, output_pvalue=None, output_class=None, confidence=0.95, pmethod="normal", df=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.dem.errprop", dod="name", sigma="name", output_sigma="name")

Parameters

dod=name [required]
    DEM of Difference raster (dem - reference)
sigma=name [,name,...] [required]
    One or more vertical uncertainty rasters, combined in quadrature
sigma_const=float [,float,...]
    Constant 1-sigma terms (meters) added in quadrature with the sigma rasters
output_sigma=name [required]
    Output propagated DoD uncertainty raster (sqrt of summed squares)
output_lod=name
    Output Level of Detection raster at the given confidence
output_zscore=name
    Output z-score raster (|DoD| / sigma)
output_pvalue=name
    Output two-tailed p-value raster
output_class=name
    Output categorical significance raster (erosion/deposition classes)
confidence=float
    Confidence level for the Level of Detection
    Allowed values: 0.0-1.0
    Default: 0.95
pmethod=string
    Distribution used for the p-value raster
    Allowed values: normal, student
    Default: normal
df=integer
    Degrees of freedom for the Student-t p-value (pmethod=student)
--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

dod : str | np.ndarray, required
    DEM of Difference raster (dem - reference)
    Used as: input, raster, name
sigma : str | list[str], required
    One or more vertical uncertainty rasters, combined in quadrature
    Used as: input, raster, name
sigma_const : float | list[float] | str, optional
    Constant 1-sigma terms (meters) added in quadrature with the sigma rasters
output_sigma : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Output propagated DoD uncertainty raster (sqrt of summed squares)
    Used as: output, raster, name
output_lod : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output Level of Detection raster at the given confidence
    Used as: output, raster, name
output_zscore : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output z-score raster (|DoD| / sigma)
    Used as: output, raster, name
output_pvalue : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output two-tailed p-value raster
    Used as: output, raster, name
output_class : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output categorical significance raster (erosion/deposition classes)
    Used as: output, raster, name
confidence : float, optional
    Confidence level for the Level of Detection
    Allowed values: 0.0-1.0
    Default: 0.95
pmethod : str, optional
    Distribution used for the p-value raster
    Allowed values: normal, student
    Default: normal
df : int, optional
    Degrees of freedom for the Student-t p-value (pmethod=student)
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.

dod : str, required
    DEM of Difference raster (dem - reference)
    Used as: input, raster, name
sigma : str | list[str], required
    One or more vertical uncertainty rasters, combined in quadrature
    Used as: input, raster, name
sigma_const : float | list[float] | str, optional
    Constant 1-sigma terms (meters) added in quadrature with the sigma rasters
output_sigma : str, required
    Output propagated DoD uncertainty raster (sqrt of summed squares)
    Used as: output, raster, name
output_lod : str, optional
    Output Level of Detection raster at the given confidence
    Used as: output, raster, name
output_zscore : str, optional
    Output z-score raster (|DoD| / sigma)
    Used as: output, raster, name
output_pvalue : str, optional
    Output two-tailed p-value raster
    Used as: output, raster, name
output_class : str, optional
    Output categorical significance raster (erosion/deposition classes)
    Used as: output, raster, name
confidence : float, optional
    Confidence level for the Level of Detection
    Allowed values: 0.0-1.0
    Default: 0.95
pmethod : str, optional
    Distribution used for the p-value raster
    Allowed values: normal, student
    Default: normal
df : int, optional
    Degrees of freedom for the Student-t p-value (pmethod=student)
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.errprop propagates per-source vertical uncertainty into a DEM of Difference (DoD) and derives change-significance products from the combined uncertainty. It is the analytical core of a DoD workflow: it answers how much of the measured elevation change is real rather than measurement noise.

Given a DoD raster and one or more uncertainty (1 sigma) rasters, the tool combines the uncertainty sources in quadrature:

sigma_DoD = sqrt(sigma_1^2 + sigma_2^2 + ... + sigma_n^2)

Cells where any source is NULL are left NULL, so the propagated uncertainty is only defined where every contributing source is defined. Typical sources are a vertical-accuracy raster for each input DEM (for example derived from land-cover class), plus optional co-registration or interpolation error terms.

The sigma_const option adds constant 1-sigma terms (meters) to the same quadrature as the sigma rasters. All sigma sources must be independent of the DoD being tested: deriving the uncertainty from the DoD itself (for example a windowed dispersion of the same map) inflates sigma exactly where change is real and suppresses its significance. Use the combined sigma from r.dem.lod (output_sigma) or independent error budgets.

From the propagated output_sigma the tool can additionally produce:

  • output_lod: a Level of Detection raster, LoD = z(confidence) * sigma_DoD, where z is the two-tailed normal critical value. Cells of the DoD whose magnitude exceeds the LoD are considered significant change.
  • output_zscore: the absolute z-score |DoD| / sigma_DoD (sigma is treated as known, so the statistic is z-based rather than Student-t; the magnitude discards the sign of change).
  • output_pvalue: a two-tailed p-value raster, using either a normal approximation (Abramowitz and Stegun 26.2.17, evaluated in r.mapcalc) or a Student-t distribution with df degrees of freedom.
  • output_class: a categorical erosion/deposition significance map. Each cell is labeled by the highest confidence level (68/90/95/99%) at which the change exceeds the corresponding LoD, signed by the direction of change.

NOTES

The categorical output uses signed integer classes:

Class Meaning Class Meaning
-4 Erosion >=99% 1 Deposition >=68%
-3 Erosion >=95% 2 Deposition >=90%
-2 Erosion >=90% 3 Deposition >=95%
-1 Erosion >=68% 4 Deposition >=99%
0 Not significant

Category labels and a diverging color table are written automatically.

The propagated uncertainty raster pairs naturally with r.dem.change, which applies an LoD threshold and reports volumetric change. The output_sigma raster can be supplied to r.dem.lod as a precomputed uncertainty surface.

confidence must be strictly between 0 and 1; the normal critical value is infinite at 1 and zero at 0.5.

The tool requires the Python scipy package.

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.

Turn the combined 1-sigma surface from r.dem.lod into significance products:

g.region raster=elev_lid792_1m

r.dem.errprop dod=dod_debiased sigma=sigma_combined \
    output_sigma=sigma_dod output_lod=lod_95 \
    output_zscore=zscore output_class=significance confidence=0.95

The z-score raster is exactly |DoD| / sigma, and the class raster spans -4 to 4 across the four confidence levels in both directions.

The local sigma from r.dem.lod is undefined wherever no stable cell falls inside the window, and on this scene that includes the interior of the change features. Those cells stay NULL through the propagation, which is deliberate: a cell whose uncertainty is unknown is untestable. Where the whole map has to be classified, fall back to the flight-wide sigma:

r.mapcalc "sigma_filled = if(isnull(sigma_combined), 0.0890, sigma_combined)"

r.dem.errprop dod=dod_debiased sigma=sigma_filled \
    output_sigma=sigma_dod output_class=significance

Combine several independent uncertainty sources, including constant terms, and use a Student-t distribution for the p-value:

r.dem.errprop dod=dod_debiased sigma=sigma_combined,bias_se \
    sigma_const=0.05 output_sigma=sigma_total \
    output_pvalue=pvalue pmethod=student df=120

r.dem.errprop example
Figure: z-score and the categorical significance classes at the 68, 90, 95, and 99 percent levels.

SEE ALSO

r.dem, r.dem.change, r.dem.lod, r.dem.stats, r.mapcalc, r.univar

AUTHORS

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

SOURCE CODE

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