Design observation-based break validation without baking in assumptions

[NewGraphEnvironment]

Problem

bcfishpass v0.5.0 uses fish observations to override gradient/falls barriers per species. fresh 0.12.3 has no equivalent. This contributes to the -13 to -23% gap in the ADMS comparison (link 0.0.0.9000).

bcfishobs.observations is loaded on local Docker (372,420 obs, 592 in ADMS).

How bcfishpass v0.5.0 does it

From model_access_bt.sql, model_access_ch_cm_co_pk_sk.sql, model_access_st.sql:

Per-species thresholds

Species group	Threshold	Which observations count
BT	>= 1	BT + salmon + steelhead (anadromous fish prove passage BT can use)
CH/CM/CO/PK/SK	>= 5	Species-specific only
ST	>= 5	Species-specific only

Filters

• Date: observation_date > '1990-01-01' — only observations since 1990
• Distance buffer: observations within 20m of the barrier are discarded (fish at the barrier doesn't prove passage — must be upstream)
• User control table: user_barriers_definite_control — some barriers are confirmed impassable (e.g., dam with stocked fish above). Observations do NOT override these.

Logic

For each gradient/falls barrier, count species-appropriate observations upstream (beyond 20m buffer, since 1990). If count >= threshold, the barrier is removed from that species' barrier list. Segments upstream become accessible for that species.

The barrier still blocks other species that don't meet their threshold.

Proposed Solution

New columns in params_fresh CSV

species_code, observation_threshold, observation_date_min, observation_buffer_m, observation_species
BT,           1,                     1990-01-01,           20,                   "BT;CH;CO;SK;PK;CM;ST"
CH,           5,                     1990-01-01,           20,                   "CH"
CM,           5,                     1990-01-01,           20,                   "CM"
CO,           5,                     1990-01-01,           20,                   "CO"
PK,           5,                     1990-01-01,           20,                   "PK"
SK,           5,                     1990-01-01,           20,                   "SK"
ST,           5,                     1990-01-01,           20,                   "ST"

• observation_threshold: minimum observations to override a barrier (0 or NA = no override)
• observation_date_min: discard observations before this date
• observation_buffer_m: discard observations within this distance of the barrier
• observation_species: semicolon-separated species codes that count (BT counts anadromous fish too)

New parameter on frs_habitat()

frs_habitat(conn, wsg = "ADMS",
  observations = "bcfishobs.observations",  # table with species_code, blue_line_key, downstream_route_measure
  ...
)

When observations is provided, after the initial access gating:

1. For each species, identify barriers that block access
2. Count qualifying observations upstream of each barrier (beyond buffer, since date_min, matching observation_species list)
3. If count >= threshold, remove that barrier from species' access model
4. Reclassify access on affected segments

User barrier control

Add optional barriers_definite parameter — a table of barriers that observations cannot override. Matches bcfishpass user_barriers_definite_control pattern.

Test

Run ADMS comparison (link 0.0.0.9000) with observations wired in. The -13 to -23% spawning gap should narrow as observations confirm access to segments behind gradient barriers.

# In compare_adms.R
result <- fresh::frs_habitat(conn,
  wsg = "ADMS",
  observations = "bcfishobs.observations",
  # ... existing params
)

Versions

• fresh: 0.12.3
• bcfishpass: v0.5.0
• bcfishobs: v0.3.2 (372,420 observations on Docker)
• link: 0.0.0.9000
• fwapg: Docker local (FWA 20240830)

Relates to NewGraphEnvironment/link#16
Relates to NewGraphEnvironment/bcfishobs#1
Relates to #90
Relates to #124