Skip to contents

Adds a return divergence attribute to the provided network. The method implemented matches that of the NHDPlus except in the rare case that a diversion includes more than one secondary path.

Requires and id, fromnode, tonode and divergence attribute. See add_divergence and make_node_topology.


All network connections with more than one downstream feature are considered.

navigate_network_dfs is used to find all downstream features emanating from the primary (divergence == 1) outlet of the diversion in question and secondary (divergence == 2) outlet(s) starting with the primary outlet.

navigate_network_dfs is called with reset = FALSE such that the secondary diversion paths terminate where they combine with a previously visited feature.

If the diverted paths result in only one outlet, the feature it flows to is marked as a return divergence.

If the diverted paths result in more than one outlet, the one that flows to the most upstream feature in the set of features downstream of the primary outlet of the diversion is marked as the return divergence.


add_return_divergence(x, status = TRUE)

# S3 method for data.frame
add_return_divergence(x, status = TRUE)

# S3 method for hy
add_return_divergence(x, status = TRUE)



data.frame network compatible with hydroloom_names.


boolean if status updates should be printed.


data.frame containing return_divergence attribute


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

x <- hy(x)

x <- add_return_divergence(x)

sum(x$return_divergence == x$RtnDiv)
#> [1] 745

# see description for documentation of one that does not match