R/select_stream_mainstem.R
select_stream_mainstem.RdEnumerates every head-to-outlet path in a directed synthetic Stream Network, compares each complete route with the retained reference hydrography, and selects the longest route among those with the best full-route reference agreement. Reference geometry identifies the Stream previously chosen by the analyst; output coordinates come only from the terrain-derived network.
select_stream_mainstem(stream_network, reference_lines)Projected `sf` LINESTRING features produced by [extract_synthetic_stream_network()]. Required fields are `stream_line_id`, `upstream_cell`, and `downstream_cell`.
CRS-defined `sf` line features representing the saved NHDPlusV2 Stream selection. Lines may be split into Reach source pieces.
A list containing the downstream-to-upstream one-feature `flowline`, upstream-to-downstream `selected_segments`, and one `candidates` feature per complete head-to-outlet route with length, discrete Hausdorff distance, rank, and selection evidence.
The function validates a one-outlet acyclic directed tree and exact segment connectivity. It does not snap, smooth, simplify, or modify input coordinates. Discrete Hausdorff distance is calculated by GEOS in the network CRS and reported in metres. A stable upstream-cell tie-break makes equivalent results independent of input row order.