hy_node: hy_node: bipartite feature-and-nexus graph

In hydroloom: Utilities to Weave Hydrologic Fabrics

hy_node: bipartite feature-and-nexus graph

Description

A hy_node object is a bipartite graph over catchments or flowlines and nexuses: each catchment (or flowline) is one row, carrying a fromnode (the upstream nexus it leaves) and a tonode (the downstream nexus it enters). Connectivity is recovered by matching tonode to fromnode across rows. This is the representation that natively supports divergences without duplicating rows — a divergence is simply a nexus with more than one outgoing feature.

As with hy_topo, a hy_node represents either a catchment topology or a flowline topology. Catchments carry a known local drainage area and are 1:1 with their flowpaths; flowlines are linear features without a committed local drainage area. The two graphs are practically related but functionally distinct.

hy_node inherits from hy.

Details

Because divergences are encoded through shared node identifiers rather than row duplication, hy_node requires unique id even on non-dendritic networks. The fromnode/tonode pair carries the connectivity that an id/toid edge list cannot.

hy_node is the entry point for hydroloom's divergence-aware operations: add_divergence() flags main and diverted paths from geometry, add_return_divergence() marks where diverted paths return to the main, and subset_network() walks the bipartite graph during subsetting.

Required columns

• id — catchment or flowline identifier, unique across rows

• fromnode — upstream nexus identifier

• tonode — downstream nexus identifier

See hydroloom_name_definitions for the canonical column definitions.

Functions that operate on hy_node

• Divergence handling: add_divergence(), add_return_divergence()

• Subsetting: subset_network()

• Edge-list construction: add_toids()

Call hy_capabilities() on a specific object for the authoritative list given its current columns.

Conversions to other representations

• To hy_topo (self-referencing edge list): add_toids(). With return_dendritic = TRUE (the default) the resulting toid drops secondary paths at divergences; set the option to FALSE and route through to_flownetwork() to keep them.

See Also

hy, hy_topo, hy_leveled, hy_flownetwork, hy_capabilities(), hy_network_type(), make_node_topology(), add_toids(), add_divergence(), subset_network()

Examples

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

z <- hy(x)

hy_network_type(z)

z

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