Add explicitly assigned Reaches to a saved Study Area

Creates new local Reach identities under existing Stream identities. Existing Study Area, Streams, Reaches, events and links are preserved. This is additive, not an identity reconciliation, rename, replacement or automatic segmentation. No areas, terrain or acquired Survey Events are required for names-only drafts.

add_study_reaches(
  dsn,
  output_file,
  reaches,
  name_column = "reach_name",
  parent_column = "stream_id",
  parent_key = "stream_id",
  add_note,
  report_file = NULL,
  report_purpose = "definition"
)

Arguments

dsn: Existing saved Study Area context GeoPackage.
output_file: New .gpkg beside dsn; never overwrite an existing context.
reaches: Nonempty data frame or polygon sf, one row per new Reach. Only chosen name, parent reference and optional geometry are imported. Other attributes, including source Reach IDs, are explicitly ignored.
name_column: Exact text column containing Reach names. Names are trimmed, nonempty and unique ignoring case within each parent Stream, including existing Reaches. The same name may occur under different Streams.
parent_column: Exact text column containing existing Stream references.
parent_key: Either stream_id (default) or stream_name. Every reference must match exactly one saved Stream; no fuzzy or spatial matching occurs.
add_note: Required source and segmentation/assignment rationale, appended to existing notes. Not an approval signature or structured provenance ledger.
report_file: Optional new .html destination in an existing directory.
report_purpose: Report view: definition (default), terrain or staging.

Value

List of context and report paths. New Reach IDs are local UUIDs. Areas, if supplied, must be valid finite nonempty CRS-defined XY polygons. Appending to an existing Reach table requires the same geometry presence, polygon type and semantic CRS; no repair/reprojection or missing-AOI invention. Native geometry is retained. No containment/coverage approval is implied. Saving and reporting are not one transaction: a rendering failure may leave the context. Continue that output and retry read-only reporting.