Skip to contents

Get confluences of aggregate flowpaths

Source: R/hydro_location_distance.R
get_confluences.Rd

Returns a hydro location for each confluence where one aggregate flowpath flows into another, such as a tributary mainstem joining the mainstem it drains to. An aggregate flowpath is the run of flowlines that share an aggregate_id and link end to end. Each confluence is identified by the tributary's aggregate_id and placed on the first flowline of the receiving aggregate flowpath below it.

Confluences work as reference points for distances along a river because any network that carries both mainstems has the confluence too. Pass the result to add_hydro_location_distance() to record positions as distances from these confluences, and to index_hydro_location_distance() to place those distances on the same or another network.

Usage

get_confluences(x)

# S3 method for class 'data.frame'
get_confluences(x)

# S3 method for class 'hy'
get_confluences(x)

# S3 method for class 'hy_topo'
get_confluences(x)

# S3 method for class 'hy_node'
get_confluences(x)

Arguments

x

hy_topo or hy_node, or a data.frame coercible with hy(). aggregate_id is set on the flowlines of each aggregate flowpath and NA elsewhere. A topo_sort column keeps building the aggregate flowpath axis cheap; without it a full topological sort is run.

Value

data.frame with one row per confluence: aggregate_id (the receiving aggregate flowpath), hydro_location_id (the tributary's aggregate_id), id (the receiving flowline just below the confluence) and id_measure (always 100, the upstream end of that flowline).

Details

A confluence is found where the bottom flowline of one aggregate flowpath connects downstream to a flowline with a different aggregate_id. The hydro location goes at the upstream end (id_measure 100) of that downstream flowline rather than at the end of the tributary. That keeps it on the receiving aggregate flowpath, and it still exists when the receiving flowpath is truncated just above the confluence. Only topology is used; no coordinates are read.

Each aggregate flowpath has one bottom flowline, so it yields at most one confluence. A tributary whose downstream connection is a diversion (divergence == 2) is dropped with a warning.

The output follows the hydrolocation feature type of OGC 25-045, with aggregate_id in the role of mainstem_id and hydro_location_id in the role of link.

Measures

id_measure is an interpolative measure along a single flowline: a percent of the line from its outlet, 0 at the outlet (downstream end) and 100 at the inlet (upstream, head end).

Examples

# New Hope flowlines, with ref/mainstems URIs joined on as aggregate_id
g <- sf::read_sf(system.file("extdata/new_hope.gpkg", package = "hydroloom"))
csv <- utils::read.csv(
  system.file("extdata/new_hope_mainstems.csv", package = "hydroloom"))

g$mainstemid <- csv$mainstem_uri[match(g$COMID, csv$comid)]
g$REACHCODE <- NULL

net <- add_toids(hy(g))

confluences <- get_confluences(net)

head(confluences)
#> # A tibble: 6 × 4
#>   aggregate_id                               hydro_location_id     id id_measure
#>   <chr>                                      <chr>              <int>      <dbl>
#> 1 https://geoconnex.us/ref/mainstems/2408627 https://geoconne… 8.89e6        100
#> 2 https://geoconnex.us/ref/mainstems/2408627 https://geoconne… 8.89e6        100
#> 3 https://geoconnex.us/ref/mainstems/2408056 https://geoconne… 8.89e6        100
#> 4 https://geoconnex.us/ref/mainstems/2080102 https://geoconne… 8.90e6        100
#> 5 https://geoconnex.us/ref/mainstems/2080102 https://geoconne… 8.90e6        100
#> 6 https://geoconnex.us/ref/mainstems/2080102 https://geoconne… 8.90e6        100