Find braids and add to a dataframe/sf dataframe

Find and uniquely identify braids in a network of flowlines, given a dataframe containing comid, fromnode, tonode and divergence as columns. 'find_braids()" identifies braids as cycles in the graph representation of the river network.

Usage

find_braids(
  network,
  terminal_id = NULL,
  add = FALSE,
  nested = TRUE,
  version = 2,
  verbose = FALSE
)

Arguments

network

The network object representing the river network.

terminal_id

character, column name containing a unique identifier, delineating separate networks in the 'network' dataset. Default is NULL which will use 'find_connected_components()' and determine the connected components in the graph to try and create a 'component_id' column in 'network'

add

Logical indicating whether to add braid information to the original network data.

nested

Logical indicating whether the output dataframe should be nested, with each COMID having a list of all the braids it is a part of. If TRUE (Default), the braid_id column may contain multiple braid IDs for a given COMID. If FALSE, there may be duplicate COMIDs as a single COMID could be a part of multiple braids (braid_id)

version

integer, version number of multibraid classification and grouping algorithm, must be either 1 or 2. Default is 2.

verbose

Logical indicating whether to display verbose messages during the braid detection process.

Value

dataframe or sf dataframe with added braid_id

Examples

 if (FALSE) {
net <- nhdplusTools::navigate_network(
 start       = 101,
 mode        = "UT",
 distance_km = 100
 ) 
 
# drop most of the columns in the network dataset
net <- dplyr::select(net, comid, divergence, totdasqkm, fromnode, tonode, terminalpa)

# get a dataframe of COMIDs and braid IDs
braids <- find_braids(network = net, add = FALSE)

# add braid_id column to original dataset
braid_df = find_braids(network   = net,
                       add       = TRUE,
                       nested    = TRUE,
                       )

# returnal original data with each braid_id represented
# by its individual COMIDs (may contain duplicate COMIDs)
nested_braids = find_braids(network   = net,
                       add       = TRUE,
                       nested    = FALSE
                       )
# if a column exists that uniquely identifies different contiguous networks,
# the column name can be given to 'terminal_id' to delianiate seperate networks within 'net'
sep_braids = find_braids(network     = net,
                         terminal_id = "terminalpa",
                         add         = TRUE,
                         nested      = FALSE
                       )
}