Add distance from the nearest hydro location

Records each position as a signed distance along its aggregate flowpath from the nearest of a set of hydro locations, such as the confluences returned by get_confluences(). An aggregate flowpath is the run of flowlines that share an aggregate_id and link end to end, such as an identified mainstem. Each position is a flowline id and id_measure. The result adds the aggregate_id the position is on, the hydro_location_id it is measured from, and distance_km.

A distance from a confluence does not depend on the flowline ids of the network it was recorded on. index_hydro_location_distance() takes the same record and places it on any network that carries the same aggregate flowpaths, for example to move a gage location from NHDPlusV2 to 3DHP. The placed position is approximate in absolute terms, since the receiving network puts the confluence at its own spot, but it stays on the same side of the confluence.

Usage

add_hydro_location_distance(indexes, hydro_locations, x)

# S3 method for class 'data.frame'
add_hydro_location_distance(indexes, hydro_locations, x)

# S3 method for class 'hy'
add_hydro_location_distance(indexes, hydro_locations, x)

# S3 method for class 'hy_topo'
add_hydro_location_distance(indexes, hydro_locations, x)

# S3 method for class 'hy_node'
add_hydro_location_distance(indexes, hydro_locations, x)

Arguments

indexes

data.frame. Positions with id and id_measure, on x.

hydro_locations

data.frame. Hydro locations to measure from, with hydro_location_id, id and id_measure, on x (for example the output of get_confluences()).

x

hy_topo or hy_node, or a data.frame coercible with hy(). Carries aggregate_id and length_km. A topo_sort column keeps building the aggregate flowpath axis cheap; without it a full topological sort is run.

Value

indexes with aggregate_id, hydro_location_id and distance_km added. aggregate_id is NA for a position on a flowline without one. A position on an aggregate flowpath with no hydro location gets NA hydro_location_id and distance_km, with a message.

Details

Positions and hydro locations are converted to kilometers along the aggregate flowpath axis (the aggregate flowpath measured from its downstream end in x). Only hydro locations on the same aggregate_id as a position are candidates, and the one with the smallest absolute difference in kilometers is recorded. A position exactly halfway between two hydro locations takes the one with the smaller hydro_location_id, compared as strings.

distance_km is negative when the position is downstream of the hydro location (toward the outlet) and positive when it is upstream (toward the headwater). The sign is a hydroloom convention; HY_DistanceDescription in HY_Features describes the same two directions as downstream and upstream.

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

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)

# the midpoint of every identified flowline, as a distance from its
# nearest confluence
positions <- data.frame(id = net$id[!is.na(net$aggregate_id)],
  id_measure = 50)

recorded <- add_hydro_location_distance(positions, confluences, net)
#> some positions are on a mainstem with no hydro location; distance_km is NA there.

head(recorded)
#>        id id_measure                               aggregate_id
#> 1 8893864         50 https://geoconnex.us/ref/mainstems/2408627
#> 2 8894490         50 https://geoconnex.us/ref/mainstems/2408627
#> 3 8894494         50 https://geoconnex.us/ref/mainstems/2408627
#> 4 8894334         50 https://geoconnex.us/ref/mainstems/2408627
#> 5 8894492         50 https://geoconnex.us/ref/mainstems/2408627
#> 6 8893850         50 https://geoconnex.us/ref/mainstems/2408627
#>                           hydro_location_id distance_km
#> 1  https://geoconnex.us/ref/mainstems/21118     -1.6225
#> 2 https://geoconnex.us/ref/mainstems/550065      0.7400
#> 3 https://geoconnex.us/ref/mainstems/550065      0.7920
#> 4 https://geoconnex.us/ref/mainstems/550065      0.8875
#> 5 https://geoconnex.us/ref/mainstems/550065      0.8470
#> 6  https://geoconnex.us/ref/mainstems/21118      0.4770