Package scope: crossing connectivity interpretation #1

link — Crossing Connectivity Interpretation

Scoring, overrides, and prioritization for fish passage crossings. The domain interpretation layer between raw crossing data and fresh's generic network engine.

Architecture

raw crossing data → link (interpret, score, override) → fresh (segment, classify, aggregate)
  modelled crossings     severity scoring                  network segmentation
  PSCIS assessments      crossing matching                 habitat classification
  override CSVs          custom barrier metrics            upstream habitat rollup
  MOTI chris_culvert_id  life-stage context                break_sources interface

fresh stays domain-agnostic — it breaks networks at points and classifies segments by attributes. link is the domain expert that understands crossing assessment data and produces the scored tables that fresh consumes.

What link does

1. Override management

Load and apply correction CSVs that refine modelled crossing data:

• Modelled crossing fixes (OBS/NONE from imagery and field review)
• PSCIS barrier status overrides (expert corrections)
• PSCIS-to-modelled crossing xref (GPS/mapping error corrections)
• User-identified barriers and natural barrier corrections

These corrections represent tens of thousands of hand-reviewed crossings accumulated across field seasons and projects.

2. Crossing source integration

Match and link crossing records across data systems:

• PSCIS stream_crossing_id ↔ modelled_crossing_id
• MOTI chris_culvert_id ↔ PSCIS and modelled crossings (not currently linked — significant gap in provincial data integration)
• CABD dam records
• User-identified barriers

3. Severity scoring

Provincial PSCIS scoring uses criteria developed for juvenile salmon and small resident rainbow trout. The barrier_result treats crossings with very different passage characteristics identically.

link introduces severity classification based on actual crossing measurements:

High severity — outlet_drop >= 0.6m, steep long pipes
Moderate severity — flow-dependent, potentially passable at migration
Low severity — likely passable for target species at relevant flows

The thresholds are configurable per project — not hardcoded.

4. Life-stage and species context

Priority hierarchy:

1. Adult spawner access to spawning habitat — highest priority
2. Juvenile upstream movement for rearing access — secondary
3. General connectivity — baseline consideration

5. Output for fresh

Produce break_source-compatible tables:

crossings <- lnk_overrides_apply(conn, crossings)
crossings <- lnk_score_severity(conn, crossings)

frs_habitat(conn, "BULK",
  break_sources = list(
    list(table = crossings,
         label_col = "severity",
         label_map = c("high" = "blocked",
                       "moderate" = "potential"))))

Proposed function surface

All exported functions prefixed lnk_:

• lnk_overrides_load() — load override CSVs
• lnk_overrides_apply() — apply corrections to crossings table
• lnk_match_pscis() — match PSCIS to modelled crossings
• lnk_match_moti() — link MOTI chris_culvert_id to PSCIS/modelled
• lnk_score_severity() — classify by biological impact
• lnk_score_custom() — user-defined scoring rules
• lnk_break_source() — produce fresh-compatible break source table
• lnk_upstream_habitat() — per-crossing habitat rollup from fresh output

Dependencies

• Runtime: DBI, RPostgres, fresh
• Data: Override CSVs, PSCIS assessment data, modelled crossings, MOTI culvert inventory
• Database: PostgreSQL with fwapg (via fresh connection)

MOTI chris_culvert_id integration

MOTI maintains a culvert inventory with chris_culvert_id that is not currently linked to PSCIS or modelled crossings in the provincial data systems. This is a significant gap — MOTI has condition and dimension data on thousands of crossings that could inform severity scoring. link should establish this linkage.

Relates to

• Apply bcfishpass override CSVs to crossings extract fresh#90 — override CSVs
• Unified network segmentation: frs_network_segment + frs_habitat_classify fresh#83 — unified pipeline
• Replace falls param with break_sources list (label_col + label_map) fresh#70 — break_sources architecture