Get upstream and downstream network buffer along stream segments

Given a stream network and starting points (either segment IDs or sf points), this function extracts the segments along the network within a specified upstream and/or downstream distance (buffer). It handles points snapped to stream segments and can clip partial segments based on the start fraction.

Usage

get_buffer_along_the_network(
  lines_sf,
  target_ids = NULL,
  start_points = NULL,
  up_radius = 0,
  down_radius = 0
)

Arguments

lines_sf

An `sf` object representing the stream network. Must have columns `subc_id` (segment ID), `target` (downstream segment), `length` (segment length), and LINESTRING geometry.

target_ids

Optional integer or character vector of segment IDs to start the buffer from. Provide either `target_ids` OR `start_points`, not both.

start_points

Optional `sf` object of POINT geometries representing starting locations on the network. Provide either `target_ids` OR `start_points`.

up_radius

Numeric. Distance (in units of `lines_sf`) to trace upstream. Default is 0 (no upstream buffer).

down_radius

Numeric. Distance (in units of `lines_sf`) to trace downstream. Default is 0 (no downstream buffer).

Value

An `sf` object containing all segments within the requested upstream and downstream distances for each starting point. Additional columns: - `point_id`: identifier of starting point - `target_segment`: ID of segment used as starting point - `start_fraction`: fraction along starting segment where the point lies - `direction`: "upstream" or "downstream" - `search_distance`: the requested buffer distance

Details

- Supports both single segments (`target_ids`) or arbitrary points (`start_points`) - Clips segments proportionally if the buffer does not reach the full segment length - Handles branching upstream segments and avoids duplicate segments for the same point - Requires `sf`, `dplyr`, and helper functions `traverse_upstream()` and `traverse_downstream()`