Skip to contents

Composes fresh::frs_network_features() calls across species (and optionally observations) to produce a streams_access wide table that mirrors bcfishpass.streams_access's shape — one row per segment, with per-species has_barriers_<sp>_dnstr booleans and per- species integer access_<sp> codes derived via CASE on (wsg-presence × dnstr-empty × observed-upstream).

Usage

lnk_pipeline_access(
  conn,
  segments,
  aoi,
  to = NULL,
  barriers_per_sp = list(),
  observations = NULL,
  observations_gate = NULL,
  wsg_presence = list(),
  presence = NULL,
  barrier_sources = list(),
  crossings_table = NULL,
  segment_id_col = "id_segment"
)

Arguments

conn

A DBI::DBIConnection object pointing at fwapg.

segments

Character. Schema-qualified segments table.

aoi

Character. Watershed group code (e.g. "ADMS"). Filter applied to segments via watershed_group_code = aoi.

to

Character or NULL. Optional schema-qualified output table. When supplied, the wide streams_access shape is written via dbWriteTable(overwrite = TRUE); in either case the tibble is returned invisibly. Default NULL returns-only.

barriers_per_sp

Named list. Each name is a species code (e.g. "bt"); each value is a schema-qualified barriers table for that species (e.g. "working_adms.barriers_bt"). Each barriers table must have a <sp>_id column (e.g. barriers_bt_id) plus the standard (blue_line_key, downstream_route_measure, wscode_ltree, localcode_ltree) keys, and watershed_group_code, which the key that lets identical tables share one walk reads (as lnk_barriers_views() provides).

observations

Character or NULL. Optional schema-qualified observations table with (observation_key, species_code, ...) + the standard FWA keys. When provided, drives the access code distinction between 1 (modelled) and 2 (observed). The walk scopes segments to aoi, never these records, so a record in any group upstream counts; lnk_pipeline_run() passes every group's (<schema>.observations_province, link#401). Default NULL collapses observation-distinguishing logic — every accessible segment gets access_<sp> = 1. Walked once for the distinct species upstream of each segment (fresh's result = "distinct"), so a main stem below many groups' records costs one element per species rather than one per record (link#401).

observations_gate

Character or NULL. Optional schema-qualified table of the same shape. When given, a segment reads 2 only where a record from this table, of any species, is also upstream: bcfishpass's reading, whose species array is kept only where a record of the segment's own group is upstream (spp INNER JOIN ids in load_streams_upstr_observations.sql). lnk_pipeline_run() passes the group's own records here under pipeline: observation_upstream: group_gated, and nothing under province.

wsg_presence

Named logical. One per species (matching barriers_per_sp keys), TRUE when the species is present in aoi. Sets access_<sp> = -9 for species marked FALSE. Default empty list assumes all species present (no -9 codes emitted).

barrier_sources

Named list. Each name is an arbitrary source tag (e.g. "anthropogenic", "pscis", "dams", "remediations"); each value is a schema-qualified barriers table for that source. Output gains one has_barriers_<source>_dnstr boolean column per source. Unlike barriers_per_sp, sources here don't drive the species access integer code – they're the bcfp-shape dnstr indicators consumed by lnk_pipeline_mapping_code(). Optional; default empty.

When both "anthropogenic" and "dams" are present, the output gains a dam_dnstr_ind boolean column: TRUE iff the next- downstream anthropogenic barrier is also a dam (sequence-aware, mirrors bcfp's array[barriers_anthropogenic_dnstr[1]] && barriers_dams_dnstr SQL). Required for resident-flavor mapping_code_bt / mapping_code_wct parity with bcfp.

When "remediations" is present AND crossings_table is set, the output gains a remediated_dnstr_ind boolean column.

crossings_table

Character or NULL. Schema-qualified crossings table with aggregated_crossings_id and pscis_status columns (e.g. "bcfishpass.crossings"). Used only to compute remediated_dnstr_ind (TRUE iff the next-downstream remediation is a crossing whose pscis_status IN ('REMEDIATED', 'PASSABLE')).

bcfp's own streams_access.remediated_dnstr_ind is currently buggy (see smnorris/bcfishpass#690): the JOIN clause pscis_status = 'REMEDIATED' AND pscis_status = 'PASSABLE' is contradictory and always FALSE – verified against 4.2M rows. link computes the bcfp-intended IN semantics, so link's mapping_code may emit REMEDIATED tokens on segments where bcfp's current output emits DAM / MODELLED / ASSESSED. PR filed against the NewGraphEnvironment/bcfishpass fork; once it lands + propagates upstream the outputs converge. Default NULL skips the remediated_dnstr_ind column.

segment_id_col

Character. Default "id_segment".

Value

A tibble, one row per segment in aoi: segment_id_col, the has_barriers_*_dnstr flags, access_<sp> codes, dam_dnstr_ind / remediated_dnstr_ind when computed, and, with observations, the obsrvtn_species_codes_upstr list-column. Written to to (scalar columns only) when given.

Details

A walk whose result is read only for membership (every barriers_per_sp table, and each barrier_sources table no ordered indicator reads) asks fresh whether any barrier lies downstream (result = "exists") rather than for the array of them. Arrays are built only for the "anthropogenic" and "dams" sources when both are given (dam_dnstr_ind reads the first element), for "remediations" when crossings_table is set (remediated_dnstr_ind), and for the upstream observation walk (species codes). A table given in several roles is walked once, as an array if any role reads its elements.

This phase runs after lnk_pipeline_classify() returns and before lnk_pipeline_persist() cleanup_working drops the working schema — it needs the per-species barriers_<sp> tables that prepare/break built. Output goes to <schema>.streams_access (working schema, picked up by persist on the next commit).

Access integer codes per species (mirroring bcfp): -9 = species not present in WSG (per wsg_presence) 0 = barriers downstream (blocked) 1 = no barriers downstream + species not observed upstream (modelled accessible) 2 = no barriers downstream + species recorded upstream, as fwapg's fwa_upstream() reads it: at least 1 m above the segment's start on its own line, or on a line its watershed codes put upstream. By the same-line measure test, a record less than 1 m above the segment's start is not upstream of it, as in bcfishpass, so the segment starting at a species' top record on a line normally reads 1 (RUNBOOK.md §2c has the other records the walk counts and when a top does not cut).