Literature and observation evidence for habitat eligibility departures #20

Context

link#19 proposes habitat eligibility overrides that depart from bcfishpass v0.5.0 defaults. Each departure needs evidence — literature, provincial fish observation data, or both. This issue tracks the research methodology and connects to prior work across multiple repos. Individual departures get their own issues with citations.

This work sits within the broader Watershed Data Workflow Framework (WSF proposal, SERNbc/New Graph/Hillcrest/Poisson) — building reproducible tools for watershed analysis across the province. The habitat eligibility parameters are a core modelling decision that affects every downstream analysis.

Prior work

Fish observations and density (fissr, fissr_explore, fissr-explore-21)

Analysis of FISS (Fisheries Information Summary System) data tied to the FWA stream network. Channel width and fish density modelling with Poisson Consulting:

• fissr_explore/ — FISS data exploration, channel width analysis
• fissr/ — FISS data access and analysis tools
• fissr-explore-21/ — Earlier iteration

Key references:

• @thorley_etal2021ChannelWidth — Channel width and fish density relationships
• @amies-galonski_etal2022FISSFish — FISS fish observation analysis

bcfishobs extends this — ties all provincial fish observation data to the FWA stream network. Allows quantification of observations by edge_type and feature_code.

Caveat: observation coordinates often land at the downstream end of sample sites, not where fish were captured. Points on a mainstem may represent fish caught in an adjacent tributary. Account for this uncertainty.

Stream temperature (skeena-stream-temp-25, fish-passage-22b)

Spatial stream temperature modelling as a habitat variable:

• skeena-stream-temp-25/ — Skeena region temperature analysis
• fish-passage-22b/ — Fish passage reporting with temperature work

Key references:

• @hill_etal2025Spatialstream — Spatial stream temperature modelling (2025)
• @hill_etal2024Spatialstream — Spatial stream temperature modelling (2024)

Temperature is a future variable for mapping intrinsic potential — species-specific thermal tolerances determine habitat suitability independent of gradient and channel width. See #21 (temperature as habitat variable).

Research approach

1. Literature review (Zotero + ragnar)

Relevant Zotero collections in NewGraphEnvironment group library:

• Fisheries/Fish Passage — crossing connectivity, barrier assessment
• Fisheries/species — species-specific habitat requirements
• Fisheries/temperature — thermal tolerances, temperature modelling
• Fisheries/regions — regional assessments, watershed-specific studies
• hydrology — discharge, MAD, flow regimes

Workflow:

• Search Zotero for existing references on species habitat use (lake rearing, intermittent stream use, wetland spawning/rearing)
• Web search for open-access PDFs to fill gaps
• Build ragnar DuckDB store from collected PDFs (Ollama + nomic-embed-text)
• Semantic search for specific claims (e.g., "bull trout lake rearing", "coho intermittent stream")
• Build evidence table: species, habitat type, edge/feature category, reference, key quote

2. Provincial fish observations (bcfishobs)

Quantify observations per species per edge_type and feature_code — empirical evidence for which segment types actually have fish:

• Query bcfishobs for observations by species, edge_type, feature_code
• Summarize: how many observations on intermittent streams? Lakes? Wetlands? Ditches?
• Cross-reference with the proposed eligibility table (link#19)
• This extends the channel width / fish density work from @thorley_etal2021ChannelWidth — same data source, different question (presence by segment type vs density by channel width)

3. Output

Per-species evidence summary for each departure from bcfishpass v0.5.0:

• Literature citation(s) with key quotes
• Observation count from bcfishobs (where available)
• Biological rationale in plain language
• Individual issues filed per departure with evidence attached

Sub-issues to spawn

Each departure from bcfishpass v0.5.0 defaults gets its own issue:

1. Lakes for rearing (BT, CH, CO, ST, WCT)
2. Intermittent streams for spawning and rearing (all species)
3. Wetland-flow streams for spawning (all species)
4. CO wetland rearing carve-out
5. River waterbody_type handling

Dependencies

• Zotero library access (MCP tools)
• Ollama with nomic-embed-text (running)
• bcfishobs database access
• ragnar package

Relates to #19, #18, #2

Habitat dimensions table (working source of truth)

Building on the literature review approach above, the working source of truth for which species use which habitat types lives in inst/extdata/parameters_habitat_dimensions.csv. This is the artifact the research validates. Each cell is a yes/no answer; the notes column carries nuance and the SRED-trackable departures.

Current draft (2026-04-09)

Habitat dimensions

• spawn_lake — does the species spawn on lake substrate (beach/shore/outlet shoals)?
• spawn_stream — does the species spawn in flowing streams (and rivers via the waterbody_type=R join)?
• rear_lake — do juveniles use lakes for rearing?
• rear_lake_only — does the species ONLY rear in lakes, never streams? (override that drops rear_stream/rear_wetland)
• rear_no_fw — do juveniles leave for the ocean immediately, no freshwater rearing? (PK, CM)
• rear_stream — do juveniles rear in streams (and rivers via waterbody_type=R)?
• rear_wetland — do juveniles use off-channel wetland complexes / beaver ponds?

The waterbody_type=R river polygon join is implicit — if spawn_stream or rear_stream is yes, the YAML generator writes both a stream,canal rule AND a waterbody_type=R rule (the second handles segments where modelled channel_width is unreliable on river-mapped polygons).

Each "no" or qualifier needs evidence from the literature review or bcfishobs analysis. Notes column captures known nuance:

• CH: stream-type modelled; ocean-type outmigrants not split out yet
• CO: river spawning marked yes — investigate further
• CT: resident form modelled; anadromous form for later
• DV/RB: rare lake spawning exists, classified as no until evidence
• GR: northern populations lake-rear
• CM/PK: brief side-channel use before estuary outmigration; classified as no FW rear (acceptable simplification)

CSV → YAML script

A link script transforms parameters_habitat_dimensions.csv into parameters_habitat_rules.yaml (the file fresh#113 consumes). The script lives in link, the YAML is a generated artifact.

Logic:

• spawn_stream = yes → spawn rule with edge_types: [stream, canal] AND additional rule with waterbody_type: R (data fix for unreliable channel_width on river polygons)
• spawn_lake = yes → additional spawn rule with waterbody_type: L
• rear_stream = yes → rear rule with edge_types: [stream, canal] + waterbody_type: R rule
• rear_wetland = yes → additional rear rule with edge_types_explicit: [1050, 1150]
• rear_lake = yes → additional rear rule with waterbody_type: L (with optional lake_ha_min from CSV)
• rear_lake_only = yes → REPLACE all rear rules with lake-only (drop stream/wetland rules)
• rear_no_fw = yes → REPLACE all rear rules with empty (no rearing classified)

The CSV is the authored source; the YAML is generated. Edits go in the CSV. The generated YAML gets committed to both link and fresh (manual sync from link → fresh).

See [#22] for the script implementation issue.

Relates to #19, #18, #2, NewGraphEnvironment/fresh#113