Places points that are indexed to one network (NHDPlusV2, NHDPlusHR, or 3DHP) on the flowlines of another, keeping each point on the mainstem it is on in the source network. The mainstem comes from the point's source identifier, not from its geometry, so a point near a confluence stays on its own river.
sf POINT data.frame with the source identifier column for
from (comid, nhdplusid or id3dhp) or a
mainstem_uri column.
character network x is indexed to, one of "nhdpv2",
"nhdphr", or "3dhp".
character network to place x on, one of "nhdpv2",
"nhdphr", or "3dhp".
character "geometry" or "hydro_location". See details.
units distance passed to index_points_to_lines, in a linear unit since indexing is in EPSG:5070. Only flowlines of the point's own mainstem are searched, so the radius can be wide enough to span differences between networks, such as a reservoir that one network routes differently from another.
numeric meters, passed to
index_points_to_lines. Lines near each point are
segmentized to this spacing so the match is to the nearest point on a
line, not the nearest vertex; NA matches vertices only.
x with mainstem_uri, id (target flowline),
id_measure, offset, past_end_km, status,
method, and measured_on added, and for
"hydro_location" also hydro_location_id and
distance_km.
The mainstem of each point comes from, in order: a
mainstem_uri column on x; for "3dhp", a
mainstemid column; otherwise the identifier column for from
(comid, nhdplusid or id3dhp), looked up in the
ref_rivers tables (see add_mainstems) or the 3DHP flowlines. A
superseded mainstem (see check_mainstems) is reported and not
placed; update_mainstems resolves it.
The target flowlines of each mainstem come from get_mainstem_flowlines. There are two ways to place a point on them.
method = "geometry" indexes the point to the target flowlines of
its mainstem with index_points_to_lines and
aggregate_ids. offset is the distance from the point to the
target flowline.
method = "hydro_location" indexes the point on the source flowlines,
records it as a distance from the nearest confluence that both networks
have on that mainstem (get_confluences and
add_hydro_location_distance), and lays the distance out
on the target (index_hydro_location_distance). The
placement is approximate in absolute terms but stays on the same side of
the confluence, which is what matters for upstream drainage. offset
is the distance from the point to the source flowline.
status is one of: placed; not_placed (no flowline
within search_radius); no_mainstem; mainstem_superseded;
mainstem_not_in_target (no target flowlines for the mainstem); and,
for "hydro_location", no_shared_hydro_location (no
confluence on the mainstem is in both networks, so the point is known only
to be on mainstem_uri), past_end and
hydro_location_not_in_x as described in
index_hydro_location_distance. measured_on names the
target network and the ref_rivers release, or for 3DHP the range of
featuredate. 3DHP identifiers are not persistent, so a 3DHP
placement holds for that release.
Points and flowlines are indexed in EPSG:5070 (CONUS Albers), so
offset is in meters.
The ref_rivers lookup tables are large downloads on first use (see add_mainstems), so this function has no example.
# a point on New Hope River just above the Northeast Creek mouth
pt <- sf::st_sf(comid = 8894344,
geometry = sf::st_sfc(sf::st_point(c(-78.9763, 35.8355)),
crs = 4326))
translate_hydrolocations(pt, "nhdpv2", "3dhp", method = "hydro_location")