Calibrate CH/BT habitat thresholds from observations (#284, steps 1-4, 6)

[NewGraphEnvironment]

Summary

Steps 1–4 and 6 of #284: CH and BT gradient and channel-width thresholds for the default_tuned bundle, calibrated from observations, FISS site data and literature. The rule was fixed before the distributions were seen.

• One cell changes: BT rear_gradient_max 0.1049 → 0.1349 in configs/default_tuned/. The evidence is BT and DV records pooled (n 4,764 accessible observations, P95 0.135), and Isaak et al. 2015's 15 % natal envelope agrees. BT records alone give 0.1249, and both are recorded (evidence_role in candidates.csv).
• Kept: every other CH/BT gradient max and width min, spawn_gradient_min (CH spawning selects the flattest bin, ratio 2.8) and cluster_bridge_gradient (1.2 % loss). So default_tuned still inherits parameters_fresh.csv.
• Vetoed by the literature: CH spawning width 6.6 m, and the literature's 3 % for CH spawning gradient.
• Evidence: data-raw/query_habitat_thresholds_{obs,fiss}.R → data-raw/logs/habitat_thresholds_284/.
• Verdicts: research/habitat_thresholds.md, plus a new research/README.md index.

Read before trusting the numbers

• Three changes were made to the rule after numbers had been seen, all disclosed in the doc (Method, Changes 1–3):

  • use restricted to accessible segments (CH spawning 0.0549 → keep, CH rearing 0.0649 → keep);
  • an inverted keep clause removed;
  • BT and DV pooled, at the operator's call. Inland, DV are bull trout under the other name; on the coast, their biology is treated as equivalent.

  Step 5 should score the retired values too.

• The candidates are unscored. Scoring against the observation validation (Validate modelled habitat against fish observations per species and watershed group #283) is step 5, so Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 stays open.

• BT has no life stage in bcfishobs. The staged evidence is the DV records. With them at full confidence the rule would loosen BT spawning gradient (0.1949) and width (1.2 m); the literature vetoes both.

Related Issues

• Relates to Research: calibrate CH and BT gradient and channel-width thresholds from observations #284 (does not close it: step 5 waits on Validate modelled habitat against fish observations per species and watershed group #283)
• Relates to Per-bundle habitat thresholds CSV in config.yaml #282, Validate modelled habitat against fish observations per species and watershed group #283
• Relates to NewGraphEnvironment/sred#24

Test plan

• devtools::test(filter = "lnk_config"): 171/171, including a new test that pins exactly which cells default_tuned changes. That test was proven by planting an untracked cell change, which made it fail.
• Full suite: 1951 pass, 3 errors. All three are Connection refused on the bcfishpass tunnel :63333, which was down during the run; these tests aren't touched by this branch.
• lnk_config_verify(lnk_config("default_tuned")) clean; audit_configs.R §2: default_tuned rules match structurally, so it needs no own rules.yaml.
• Both scripts rerun end to end with byte-identical outputs.
• /code-check on the pooling change, 3 rounds (review-pool-round*.md). Round 3 swept 45 BT figures for which evidence set each came from.
• /code-check, 4 rounds (planning/archive/2026-09-issue-284-*/review-round*.md). R1 and R2 found defects that flipped candidates and corrected the bridge mechanism. R3 and R4 checked 88 and 97 claims; R4 was 96/97, and the one miss (a section pointer) is fixed.

Notes

• Public/private boundary: knowledge is private, so only FISS aggregates are committed here. Site rows are written only when LNK_FISS_SITES_OUT is set.
• Two issue drafts are in the archive, not filed:
  • knowledge: parse the individual-fish sheets; average_gradient_percent holds proportions.
  • fresh/link: NULL-width river polygons fail the river rule's BETWEEN 0 AND 9999.
• This branch replaces the parked 284-research-calibrate-ch-and-bt-gradient-a, whose three planning commits are cherry-picked here. That leaves out the unrelated MCGR run-log commit, which is on local main only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WJE2szSCkeV9R3qKhuSwyx