Region-scoped observation pooling as bundle data: lnk_species_pooling() (#290)

[NewGraphEnvironment]

Summary

• Observation pooling is data now. Which observation species count as evidence for which model species moves out of code into a bundle tracker, configs/default/species_pooling.csv: one dated, sourced row per decision, scoped to a region, sub-region or WSG. Either side can be a group from species_groups.csv.
• The resolver is species-agnostic. New exported lnk_species_pooling() knows no species: DV into BT, or all salmon together, is a row.
  • The most specific scope wins, then the row naming fewer groups. Unresolved ties error, and anything unlisted is not pooled.
  • Regions come from the new package-level inst/extdata/wsg_regions.csv, which uses each group's outlet wscode and is built by data-raw/wsg_regions.R. It is also hashed into config_hash for any bundle that declares a tracker.
• The consumers read the tracker. lnk_habitat_validate() accepts the per-WSG table as species_obs; the list form and its default are unchanged. data-raw/habitat_validate.R resolves pooling once and applies it to both bundles. The Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 obs producer joins the table in place of its hard-coded DV CASE. Both drivers stop if the pooling bundle's presence table disagrees, WSG by WSG, with the scored bundle's.
• Tracker: DV → BT in the Fraser, Mackenzie, Columbia/Kootenay, and the Skeena only above Hazelton. The region seed is the operator's call of 2026-09-26; the Skeena split is their call of 2026-09-27.
  • The split is a new sub-region, Skeena above Hazelton, defined by an explicit group list. MSKE and USKE have their outlets on the Skeena mainstem, like LSKE, so no code prefix can separate them.
  • An optional obs_year_max column pools only records dated in or before a year. The validator and the Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 script apply it per record. It is empty in the seed.
• Evidence: DV/BT naming through time and the pooling sensitivity are measured by data-raw/species_pooling_evidence.R, with maps and figures. The write-up is research/species_pooling.md, and the walkthrough page is When a Dolly Is a Bull Trout (private).

Related Issues

• Fixes Region-scoped DV→BT observation pooling, tracked in bundle CSVs #290
• Unparks Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 step 5. Research: DV as BT access evidence — regional scope + multi-rule observation overrides #236's access override should read the same table.
• Relates to NewGraphEnvironment/sred#24

Test plan

• devtools::test() (at 4e9893d): 2151 pass, 3 fail. The 3 are all the :63333 bcfishpass tunnel being down (test-lnk_db_conn.R:10, test-lnk_wsg_resolve.R:143, :154), in files this branch does not touch.
• New tests:
  • 43 expectations in test-lnk_species_pooling.R, on synthetic codes (AAA/BBB/GRP), so nothing passes on BT/DV by accident;
  • the data-frame species_obs form, end to end against the list form;
  • a mocked test that a regions edit moves config_hash;
  • a check that every new dictionary consumed_by ref lands on a line naming its column.
• Guards proven by mutation in scratch copies: scope precedence, the taxon tie-break, pool = no, the presence gate, the df branch, the hash block, and wrong dictionary refs each turn their tests red.
• Under the region rule alone, the Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 obs producer re-ran byte-identical in every CSV and PNG except the province-wide ledger step 3 (DV 8,888 → 6,138). That number was predicted before the run, and independently by review.
• Under the Hazelton split, the committed Research: calibrate CH and BT gradient and channel-width thresholds from observations #284, Validate modelled habitat against fish observations per species and watershed group #283 and scenario evidence were regenerated from the committed code (911bed3).
  • 852 DV records below Hazelton drop out.
  • BT rearing gradient P95 goes 0.1348 → 0.1309 (n 4,764 → 3,988). The rule still gives 0.1349, now by 0.0009.
  • No Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 verdict moves, and CH is byte-identical.
• The Validate modelled habitat against fish observations per species and watershed group #283 validation baseline (default vs bcfishpass, 55 + 59 WSGs, knowledge @ 508bf44) re-ran byte-identical under the region rule. Under the split, its shared BT set falls from 4,600 to 3,771 locations, CH is unchanged, and the committed CSVs are updated.
• Negative check with Skeena pool = no: exactly 1,929 DV rows drop, in the 9 Skeena WSGs; nothing else moves.
• devtools::document() and pkgdown::check_pkgdown() clean.
• lintr: not clean.
  • New code adds hanging-indent style lints, the same pattern as the repo backlog (67 in test-lnk_log.R on main).
  • Plus 3 object_usage_linter false positives for helpers that are absent from the stale installed package.

Notes

• config_hash changes for default and default_tuned, because they declare two new files and now hash the region lookup. No model output changed, so a hash mismatch against pre-Region-scoped DV→BT observation pooling, tracked in bundle CSVs #290 log rows is expected, not drift.
• Where the new rule bites: 33 BT-present WSGs no longer pool DV: 29 in the Nass, Stikine, Taku, Yukon and the coast, plus the 4 Skeena groups below Hazelton.
• Review: 1 plan review and 6 /code-check rounds. That is 7 agents, past the usual bound; each round found real defects.
  • The last round covered the Hazelton split and the year column. It found that the scenario script's reimplementation could not stand in for a year-limited scenario. The fix takes every scenario's numbers from its own producer run, and corrects the S3 figures published earlier.
  • Phase 2 ran three rounds and Phase 3 two, each ended by enumerating one mechanism: two separately kept lists agree on a key, and disagreement narrows silently. Phase 3's two rounds are one below the skill's floor.
  • Findings are in planning/archive/2026-09-issue-290-species-pooling/review-*.md.
• Follow-ups filed:
  • lnk_presence(): move the hard-coded presence groups into the bundle #292: lnk_presence()'s hard-coded groups.
  • query_habitat_thresholds_obs.R: availability km differ run to run in the last bits (float sum order) #293: a pre-existing 1-ulp run-to-run difference in the Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 producer's candidates.csv, from a double-precision sum().

🤖 Generated with Claude Code

https://claude.ai/code/session_01WJE2szSCkeV9R3qKhuSwyx