hy_topo: hy_topo: self-referencing edge list

In hydroloom: Utilities to Weave Hydrologic Fabrics

hy_topo: self-referencing edge list

Description

A hy_topo object is a self-referencing edge list representing either a catchment topology or a flowline topology: one row per feature, carrying an id and a toid that points at the immediately downstream feature. This is the main representation for downstream traversal, topological sorting, and most accumulation algorithms in hydroloom.

Catchment topology and flowline topology are functionally separate graphs. A catchment carries a known local drainage area and is 1:1 with its flowpath (the linear realization of the catchment). A flowline is a linear feature without a committed local drainage area — it may coincide with a catchment's flowpath, but that relationship is not guaranteed. hy_topo represents either graph; the two are practically related but should not be conflated.

hy_topo inherits from hy. The enriched subclass hy_leveled extends hy_topo with topo-sort and levelpath columns, so methods written for hy_topo apply to hy_leveled objects without modification.

Details

hy_topo requires unique id. A divergence would need two downstream connections from the same upstream feature — that is, two rows with the same id — and hy_topo does not permit that. Networks with divergences belong in hy_node (a bipartite graph through fromnode/tonode) or in hy_flownetwork (a junction table that annotates main and diverted paths). When the internal classifier called from hy() sees a duplicated id in an id/toid table, it produces an hy_flownetwork rather than an hy_topo.

For the authoritative, programmatic view of which functions are callable on a particular object, use hy_capabilities().

Required columns

• id — catchment or flowline identifier, unique across rows

• toid — id of the immediately downstream feature; network outlets carry the reserved outlet value (0 for numeric ids, "" for character)

See hydroloom_name_definitions for the canonical column definitions and accepted aliases.

Functions that operate on hy_topo

• Topology and sorting: sort_network(), add_topo_sort(), check_hy_graph()

• Path enrichment: add_levelpaths(), add_pathlength(), add_streamorder()

• Accumulation and traversal: accumulate_downstream(), navigate_hydro_network(), navigate_network_dfs(), make_index_ids()

Call hy_capabilities() on a specific object to see which functions are callable on it given its current columns.

Conversions to other representations

• To hy_node (bipartite graph): make_node_topology()

• To hy_leveled (enriched edge list): add_levelpaths(), which adds topo_sort, levelpath, and levelpath_outlet_id

• To hy_flownetwork (junction table): add_levelpaths() then to_flownetwork()

See Also

hy, hy_leveled, hy_node, hy_flownetwork, hy_capabilities(), hy_network_type(), is_dendritic(), add_toids(), sort_network(), make_node_topology()

Examples

x <- sf::read_sf(system.file("extdata/new_hope.gpkg", package = "hydroloom"))

z <- add_toids(hy(x))

hy_network_type(z)

z

hydroloom documentation built on Aug. 4, 2026, 1:07 a.m.