hy_flownetwork: hy_flownetwork: non-dendritic junction table

In hydroloom: Utilities to Weave Hydrologic Fabrics

hy_flownetwork: non-dendritic junction table

Description

A hy_flownetwork object is a junction table — a non-dendritic edge list of id and toid rows where id may repeat. Each row records one connection between an upstream catchment or flowline and a downstream one, and optional upmain/downmain logical columns annotate which of the connections at a divergence is the main path. This is the only edge-list-shaped representation in hydroloom that preserves divergences directly.

Unlike the other class pages on this index, hy_flownetwork does not inherit from hy — id is not guaranteed to be a primary key, and a hy_flownetwork does not pass is.hy(). The user-facing producer to_flownetwork() drops the orig_names round-trip metadata that hy carries; a hy_flownetwork produced by hy() or classify_hy() from a non-dendritic data.frame may still have orig_names attached internally so name-aligned dispatch can restore the user's column names on return.

Details

hy_flownetwork is what hydroloom's internal classifier produces (via hy()) when an id/toid table has duplicated id values, and what to_flownetwork() produces from a hy_leveled input. The upmain/downmain annotation, when present, lets divergence-aware operations choose a main path without having to re-derive it from levelpath identity each time.

Several hydroloom operations that were originally written against hy_topo accept hy_flownetwork directly through delegate methods, because the underlying algorithm already tolerates non-dendritic input: add_streamorder(), accumulate_downstream(), get_bridge_flowlines(), add_levelpaths(), and make_node_topology() all work on hy_flownetwork without conversion.

Required columns

• id — catchment or flowline identifier; may be non-unique

• toid — downstream id

Optional:

• upmain — logical, TRUE for the main upstream connection at each junction

• downmain — logical, TRUE for the main downstream connection at each junction

See hydroloom_name_definitions for the canonical column definitions.

Functions that operate on hy_flownetwork

• Native operations: navigate_network_dfs(), make_index_ids()

• Delegated to the hy_topo algorithm: add_streamorder(), accumulate_downstream(), get_bridge_flowlines(), add_levelpaths(), make_node_topology()

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

Conversions to other representations

• To hy_node (bipartite graph): make_node_topology()

Going the other direction — from hy_node or hy_leveled into hy_flownetwork — is what to_flownetwork() is for.

See Also

hy, hy_topo, hy_leveled, hy_node, hy_capabilities(), hy_network_type(), is_dendritic(), to_flownetwork(), navigate_network_dfs(), make_index_ids()

Examples

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

z <- to_flownetwork(x)

hy_network_type(z)

z

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