GRASS logo

NAME

r.richdem.dephier - Compute the depression hierarchy of a DEM using RichDEM

KEYWORDS

raster, vector, hydrology, depression hierarchy, flow direction

SYNOPSIS

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

Flags:

--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

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

Table of contents

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.

Conceptual diagram of depression hierarchy terminology: binary tree, cross-sections of nested depressions, and volume diagram
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.

Forest of binary trees schematic showing depression hierarchy with numbered nodes, parent-child links, geolinks, and ocean links
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.

Three-panel figure showing depression labels on a Madagascar DEM: (a) leaf-level labels, (b) top-level labels, (c) filtered labels above area threshold
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 232 − 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

SEE ALSO

r.richdem.fsm, r.richdem.filldepressions, r.richdem.flowaccumulation, r.watershed, r.stream.extract

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: 2163cf63360e0ce5bfae95f4815c63ffbb9dda5c

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual