r.richdem.dephier

Compute the depression hierarchy of a DEM using RichDEM

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

r.richdem.dephier input=name [output_labels=name] [output_flowdirs=name] [output_hierarchy=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.richdem.dephier input=name output_labels=name

grass.tools.Tools.r_richdem_dephier(input, output_labels=None, output_flowdirs=None, output_hierarchy=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_richdem_dephier(input="name", output_labels="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.richdem.dephier", input, output_labels=None, output_flowdirs=None, output_hierarchy=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.richdem.dephier", input="name", output_labels="name")

Parameters

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

input=name [required]
    Input elevation raster
output_labels=name
    Output depression labels raster (leaf depression index per cell)
output_flowdirs=name
    Output flow directions raster
output_hierarchy=name
    Output depression hierarchy vector map
    Name for output vector map
--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 elevation raster
    Used as: input, raster, name
output_labels : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output depression labels raster (leaf depression index per cell)
    Used as: output, raster, name
output_flowdirs : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Output flow directions raster
    Used as: output, raster, name
output_hierarchy : str, optional
    Output depression hierarchy vector map
    Name for output vector map
    Used as: output, vector, name
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 elevation raster
    Used as: input, raster, name
output_labels : str, optional
    Output depression labels raster (leaf depression index per cell)
    Used as: output, raster, name
output_flowdirs : str, optional
    Output flow directions raster
    Used as: output, raster, name
output_hierarchy : str, optional
    Output depression hierarchy vector map
    Name for output vector map
    Used as: output, vector, name
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.richdem.dephier computes the depression hierarchy of a digital elevation model (DEM) and stores the results in two raster maps and one vector map. The depression hierarchy is a data structure that encodes all nested depressions in a landscape and their hydrological connectivity, without removing them by filling or breaching.

This module is the required first step of the Fill--Spill--Merge workflow (Barnes et al., 2020, 2021). Its outputs feed directly into r.richdem.fsm.

Depression hierarchy concept

Every topographic depression, from a small pit cell to a large endorheic basin, can be described as part of a hierarchy. Small leaf depressions contain no sub-depressions. When a leaf depression fills to its pour point (lowest outlet), water spills into an adjacent depression; the two merge into a meta-depression that itself can fill and spill into its neighbor. This nesting continues until water eventually reaches the ocean (or the map boundary, treated as the ultimate outlet).

The hierarchy is stored as a forest of binary trees: each node represents a depression (leaf or meta), and the two children of any meta-depression are the two depressions that merged to form it. Separately, ocean links record depressions that drain directly to the ocean rather than to another depression.

Depression hierarchy terminology. (a) Binary tree relating leaf and meta depressions. (b--d) Cross-sections illustrating nested leaf, marginal, and meta depressions. (e) Volume--elevation relationship with Parent, Leaf, and Spillover components. Figure 2 from Barnes, Callaghan & Wickert (2021), CC-BY 4.0.

A forest of binary trees representing the depression hierarchy of a landscape. Solid lines connect parent meta-depressions to their two child depressions; dashed arrows show geolinks (overflow connections between adjacent depressions) and ocean links. Each numbered node corresponds to a leaf or meta depression label stored in output_labels and output_hierarchy. Figure 1 from Barnes, Callaghan & Wickert (2020), CC-BY 4.0.

Output rasters

output_labels assigns each cell its leaf-depression label---an integer identifying which leaf depression it is part of. Cells that drain directly to the ocean receive label 0 (OCEAN).

output_flowdirs contains a D8 flow direction for each cell. Directions are encoded as integers 0--7 counting counter-clockwise from east (matching the RichDEM convention). Pit cells, which have no outflow direction, are stored with value 8.

Output vector map (two-layer)

output_hierarchy is a two-layer GRASS vector map whose attribute database holds the complete depression hierarchy:

Layer 1 --- depressions table contains one feature per depression. Leaf depressions are represented as area polygons (derived from the labels raster). Meta-depressions are represented as points located at the saddle cell (out_cell) where their two child depressions merge. Attribute columns include:

dep_label : Unique integer label for the depression

type : leaf or meta

pit_cell : Flat-index of the lowest cell (pit) in the depression

out_cell : Flat-index of the pour-point cell (lowest outlet)

parent : Label of the parent meta-depression (NULL if directly ocean-linked)

lchild, rchild : Labels of the two child depressions (NULL for leaves)

odep : Label of the depression this one overflows into via its geolink

geolink : Label of the depression on the other side of the pour point

pit_elev : Elevation of the pit cell

out_elev : Elevation of the pour-point cell

ocean_parent : 1 if this depression drains directly to the ocean, 0 otherwise

cell_count : Number of cells in the depression

dep_vol : Depression volume (integrated depth below the pour point)

water_vol : Volume of water currently in the depression (updated by r.richdem.fsm)

total_elevation : Sum of elevations of all cells in the depression

Layer 2 --- ocean_links table is a junction table with one row per direct ocean connection. Some depressions drain to the ocean through multiple independent pathways; this table records each (dep_label, linked_label) pair. Columns: cat, dep_label, linked_label.

Example output_labels outputs for a DEM of northern Madagascar. (a) Leaf-depression labels: each distinct color is a separate leaf depression. (b) Top-level (root) depression labels: only the largest containing hierarchy level is shown. (c) Filtered labels retaining only depressions above a minimum area threshold. Figure 9 from Barnes, Callaghan & Wickert (2020), CC-BY 4.0.

NOTES

The depression hierarchy algorithm runs in O(N) time, where N is the total number of cells, making it suitable for very large DEMs (Barnes et al., 2020).

The input DEM does not need to be pre-conditioned (filled or breached); the algorithm handles all depressions, including nested ones. Raw DEMs with noise may produce a large number of very small leaf depressions.

The output labels raster stores uint32 values internally but is written to GRASS as a DCELL (double-precision float) map because GRASS has no native unsigned 32-bit integer raster type. All label values up to 2³² − 2 are representable exactly as doubles.

REQUIREMENTS

This module requires the RichDEM Python package, which is not a standard GRASS GIS dependency and must be installed separately:

pip install richdem

If pip install richdem fails (the package requires a C++ compiler), build from source:

git clone https://github.com/r-barnes/richdem.git
cd richdem/wrappers/pyrichdem
pip install -e .

Ensure that RichDEM is installed into the same Python environment used by GRASS GIS.

EXAMPLES

Compute the depression hierarchy:

r.richdem.dephier input=dem \
    output_labels=dep_labels \
    output_flowdirs=dep_flowdirs \
    output_hierarchy=dep_hierarchy

Inspect the hierarchy table:

v.db.select map=dep_hierarchy layer=1 | head -20

Display leaf depression areas colored by depression volume:

# Select only leaf depressions
v.extract input=dep_hierarchy layer=1 where="type='leaf'" output=leaf_deps
v.colors map=leaf_deps use=attr column=dep_vol color=blues

Use the output to run Fill--Spill--Merge:

r.richdem.fsm input=dem \
    labels=dep_labels \
    flowdirs=dep_flowdirs \
    hierarchy=dep_hierarchy \
    water_depth=wtd \
    output=wtd_after

REFERENCES

Barnes, R., Callaghan, K.L., Wickert, A.D. (2020). Computing water flow through complex landscapes -- Part 2: Finding hierarchies in depressions and morphological segmentations. Earth Surface Dynamics Vol 8(2), pp 431--445. DOI: 10.5194/esurf-8-431-2020
Barnes, R., Callaghan, K.L., Wickert, A.D. (2021). Computing water flow through complex landscapes -- Part 3: Fill--Spill--Merge: flow routing in depression hierarchies. Earth Surface Dynamics Vol 9(1), pp 105--121. DOI: 10.5194/esurf-9-105-2021
Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem

AUTHORS

Richard Barnes, Kerry L. Callaghan, Andrew D. Wickert (Barnes et al., 2020)

GRASS GIS bindings: Andrew D. Wickert, with assistance from Claude Sonnet 4.6

SOURCE CODE

Available at: r.richdem.dephier source code (history)
Latest change: Sunday May 31 20:21:19 2026 in commit 2163cf6

r.richdem.dephier

Parameters

DESCRIPTION

Depression hierarchy concept

Output rasters

Output vector map (two-layer)

NOTES

REQUIREMENTS

EXAMPLES

REFERENCES

SEE ALSO

AUTHORS

SOURCE CODE