Get the flowlines of mainstems — get_mainstem

Returns the flowlines that realize one or more geoconnex mainstems in NHDPlusV2, NHDPlusHR, or 3DHP. The result carries the identifier, topology, and length attributes that hy recognizes, with mainstemid holding the full mainstem uri, so it can go directly to the hydroloom functions that work on aggregate flowpaths such as get_confluences and index_points_to_lines with aggregate_ids.

get_mainstem_flowlines(
  mainstems,
  network = c("nhdpv2", "nhdphr", "3dhp"),
  include_confluences = FALSE
)

Arguments

mainstems: character vector of geoconnex mainstem uris, or ref/mainstems integer ids.
network: character one of "nhdpv2", "nhdphr", or "3dhp".
include_confluences: logical. If TRUE, append the outlet flowline of each identified mainstem that flows into a requested one.

Value

sf data.frame of LINESTRING flowlines, or NULL if none were found. Mainstems with no flowlines are left out with a warning.

Details

Each network realizes a mainstem differently, so each is fetched differently.

For "nhdpv2", comids come from the ref_rivers lookup table (see add_mainstems), topology and length from the updated network attributes (see get_vaa with updated_network = TRUE), and geometry from get_nhdplus. Columns are comid, tocomid, lengthkm, hydroseq, and mainstemid. tocomid is already dendritic so no divergence is carried.

For "nhdphr", NHDPlusIDs come from the ref_rivers NHDPlusHR lookup table and the flowlines from get_nhdphr. Columns are nhdplusid (as character), fromnode, tonode, hydroseq, lengthkm, divergence, and mainstemid. Flowlines link by node rather than by toid. The NHDPlusHR lookup does not cover every mainstem.

For "3dhp", 3DHP carries mainstem uris natively and flowlines come from get_3dhp. Columns are id3dhp, toid (built from dnhydrosequence, "" where it leaves the result), hydroseq (renamed from hydrosequence), lengthkm, divergence, featuredate, and mainstemid. 3DHP identifiers are not persistent across releases; featuredate records which release the flowlines came from.

With include_confluences = TRUE, the outlet flowline of each other identified mainstem that flows into a requested mainstem is appended. Those are the rows get_confluences needs to find where tributary mainstems join. They are found by attribute queries on the flowlines' downstream connections, not by area of interest, and inflowing flowlines with no mainstem uri are left out.

The NHDPlusV2 lookup and updated network attribute tables are large downloads on first use (see add_mainstems and get_vaa), so this function has no example.


fl <- get_mainstem_flowlines("https://geoconnex.us/ref/mainstems/2408056",
                             "3dhp", include_confluences = TRUE)

hydroloom::get_confluences(fl)