Given a focal set of FWA watershed groups, return the drainage closure — the focal groups plus every watershed group their water flows through — ordered downstream-first. Pure FWA topology; no species or bundle knowledge.
Usage
frs_wsg_drainage(conn, watershed_group_code, outlets = frs_wsg_outlets())Arguments
- conn
A DBI::DBIConnection (e.g. from
frs_db_conn()). Used only to evaluatefwa_downstream(); the outlet table itself is read fromoutlets.- watershed_group_code
Character vector of focal WSG codes (e.g.
c("BULK", "MORR")). Must be non-empty and free ofNA. Codes are upper-cased internally. Focal codes absent from the outlet table trigger a warning and are dropped; if none match, the function errors.- outlets
Data frame of watershed group outlets with columns
watershed_group_code,blue_line_key,downstream_route_measure,wscode_ltree,localcode_ltree. Defaults to the table bundled atsystem.file("extdata", "wsg_outlet.csv", package = "fresh"), regenerated bydata-raw/wsg_outlet.R.
Value
Character vector of WSG codes — focal plus every WSG they flow through — ordered downstream-first.
Details
Each group is represented by its outlet point — a
blue_line_key + downstream_route_measure pair with the accompanying
wscode_ltree and localcode_ltree — and pairs are tested with
whse_basemapping.fwa_downstream(), the same primitive family as the
fwa_upstream() used elsewhere in fresh.
A point is required rather than a single code because a lone ltree cannot
order two groups that share a stem: every Fraser group carries wscode
100 and five Skeena groups carry 400. Upper Fraser and Lower Fraser
are separable only by measure — both sit on blue_line_key 356364114, at
1,189,576 m and 0 m respectively.
Order: number of groups downstream ascending, ties alphabetical, so the most downstream groups come first. Running per-WSG work in this order persists downstream barriers before upstream groups read them, which makes cross-WSG accessibility flags settle correctly within a single pass. The ordering is derived from topology, not from an ltree depth that ties across a whole stem.
See also
Other wsg:
frs_wsg_outlets()
Examples
if (FALSE) { # \dontrun{
conn <- frs_db_conn()
# Skeena + Peace focal — the drainage closure, downstream-first
frs_wsg_drainage(conn, c("PARS", "BULK"))
# The Morice drains through the Bulkley, not the reverse. FWA carried the
# "Bulkley" name down through the confluence, so the Morice — the larger
# flow — is filed as the tributary.
frs_wsg_drainage(conn, "MORR")
DBI::dbDisconnect(conn)
} # }