End-to-end habitat connectivity for ADMS

[NewGraphEnvironment]

End-to-end habitat connectivity for ADMS

Validate link + fresh pipeline against bcfishpass v0.5.0 reference for ADMS watershed group. All 4 species bcfishpass classifies in ADMS: BT, CH, CO, SK.

Current status

Sub-basin validated (wscode 100.190442.999098.995997.058910.432966):

• CH spawning: EXACT match (9.18 = 9.18)
• CH rearing: EXACT match (10.15 = 10.15)
• CO spawning: EXACT match (10.21 = 10.21)
• CO rearing: -0.6%, BT spawning: +1.6%, BT rearing: -0.5%
• SK rearing: 0 (lake-only rule works)

Full ADMS: access gating bug — fresh blocks ~96% of segments (should be ~67%). Two hypotheses:

1. min_length=0 DEM noise — fresh#118 set min_length to 0. Single noisy DEM vertices at >15% gradient create spurious barriers blocking everything upstream.
2. BARRIER crossings blocking natural access — 39 crossings with barrier_status = BARRIER mapped to label = "blocked". But bcfishpass natural access only uses gradient + falls — crossing barrier_status does NOT affect natural access. Sub-basin had 0 BARRIER crossings (why it worked).
3. Both compounding — more barriers + BARRIER crossings = cascading undercount.

What's needed

Access bug fix

• Test hypothesis 2: change BARRIER label from "blocked" to non-blocking (e.g., "barrier"), rerun full ADMS
• Test hypothesis 1: analyze gradient barrier distribution for DEM noise patterns
• Fix and validate full ADMS within 5%

bcfishobs integration

• Sync bcfishobs fork with smnorris upstream (done — on main branch)
• Run bcfishobs against Docker fwapg (builds bcfishobs.observations table)
• bcfishpass uses observations to upgrade access (unknown → known accessible) — fresh needs equivalent
• fresh#69: observation-based break validation design

SK spawning + lake proximity

• fresh#120: SK spawning requires connected rearing lake ≥ 200 ha within 3km
• Test on full ADMS (has lakes ≥ 200 ha, sub-basin doesn't)

Remaining comparison gaps

• link#20: literature + observation evidence for habitat eligibility
• fresh#114: MAD support for mad-model WSGs
• fresh#105: feature_codes categories
• fresh#110: gradient dedupe precision

Pipeline (current)

data-raw/compare_adms.R
├── Step 1: Connect (Docker 5432 + tunnel 63333)
├── Step 2: Load crossings, enrich with ltree, filter sub-basin
├── Step 3: Apply bcfishpass overrides (NONE→PASSABLE, PSCIS status)
├── Step 4: frs_habitat (bcfishpass-matching rules YAML + params)
│   └── frs_cluster (rearing-spawning connectivity for CH/CO/SK)
└── Step 5: Compare per-species habitat_linear_* tables

Key files

File	Purpose
data-raw/compare_adms.R	Main comparison script
data-raw/build_bcfishpass_rules_yaml.R	Generates bcfishpass v0.5.0 matching rules
data-raw/build_habitat_rules_yaml.R	Generates NGE saner defaults from dimensions CSV
inst/extdata/parameters_habitat_rules_bcfishpass.yaml	bcfishpass-strict rules
inst/extdata/parameters_habitat_rules.yaml	NGE defaults
inst/extdata/parameters_habitat_dimensions.csv	Species × habitat biology (source of truth)
inst/extdata/parameters_fresh_bcfishpass.csv	spawn_gradient_min=0 override

fresh issues resolved (from this comparison)

• Falls not used as segmentation break source — implementation drift from documented break_order #96 ✓ AOI support
• Archive PWF for link#88 (deferred from local main) #98 ✓ gate + label_block
• csv-sync: pull bcfishpass overrides 20260502 #100 ✓ edge_type filtering
• Archive PWF for link#96 (falls in break_order) #101 ✓ breaks_gradient param
• Wire CABD waterfalls + 4 edit CSVs into the falls source #102 ✓ expose params on frs_habitat
• Derive species presence cols from CSV header #107 ✓ frs_cluster (rearing connectivity)
• Persistent province-wide habitat tables (fresh.streams + fresh.streams_habitat_<sp>) #113 ✓ rules YAML format
• #116 ✓ per-rule threshold overrides
• #118 ✓ min_length filter fix

Success criteria

• All species within 5% of bcfishpass totals for full ADMS
• SK spawning requires lake proximity (fresh#120)
• bcfishobs observations loaded and available for access upgrade

Relates to #1
Relates to NewGraphEnvironment/fresh#69
Relates to NewGraphEnvironment/fresh#120
Relates to NewGraphEnvironment/sred-2025-2026#24