docs(residuals): retire "hybrid" — R2 with any singleton cell is Bishop's ungrouped MA2

[cnicholas]

Summary

• What: the docs, the detector's method token, the analysis-plan text, two docstrings and two test names all described R2 for design state 3 as a per-cell hybrid (exact deviation where a cell has n ≥ 2, moving average where n = 1), and one page said it was validated by Monte Carlo. They now say what the code does.
• Why: the hybrid was removed in cb037f8 (2026-03-05). With any singleton cell, R2 is Bishop's 2-point moving average over the full canonical sequence for every observation (Eq 13.7–13.9), and the 89 ADS 3 reference assertions validate that. The docs described a calculation whose results would fail the reference, and three pages described it three different ways (one said singleton cells get zero, which was never true).
• Scope: vocabulary in sds_detector.py; docstrings in residual_calculator.py, analysis_dataset.py, datasets/synthetic.py; six docs pages; two test files; CHANGELOG.

Contract / invariants

• Defaults unchanged — no arithmetic touched. calculate_r2's body is identical; validation/e2e_bishop_report.py exits 0 and docs/reference/validation.md is unchanged.
• Residuals unaffected — numerically identical everywhere.
• Row/index alignment preserved — n/a.
• Output schema compatible — R2Method narrows to Literal['exact', 'ma2']; get_r2_method returns 'ma2' where it returned 'hybrid'; get_sds_characteristics(...)['r2_method'] and SDSAnalysisPlan.residual_calculation_method use the same two spellings in place of 'within_cell', 'moving_average', 'hybrid'. None of these names is exported from the package top level, so per CONTRIBUTING this is not a public break; it is recorded under Changed in the CHANGELOG.
• Pinned error strings unchanged — none touched.

Behaviour changes

• Method tokens as above. Log lines that print the method change text. No numeric output changes.

Methodology

• No methodology change — the docs now match the validated implementation.
• For Tom: the rewritten note on docs/user-guide/sds-detection.md ("Why DS 3 does not mix methods") asserts the reason MA2 applies to every observation: Bishop's Eq 13.7–13.9 are defined over the whole ordered sequence with no grouping by cell. The equation numbers are from cb037f8's commit message. Please read that paragraph before merge.

Tests

• TestR2MethodSelection (new, tests/test_sds_detector.py) — exact for all-replicated, ma2 for all-singleton and for mixed cells, and one spelling across the analysis plans and characteristics for states 1 to 6.

• test_calculate_r2_mixed_cells_uses_ma2_for_all and test_calculate_vas_residuals_sds3_uses_ma2_for_all — renamed; assertions unchanged in substance.

• Three assertions updated from the retired spellings.

• pytest tests/ — 2344 passed, 10 skipped

• ruff check . — clean

• mypy processbehavior — 17 pre-existing errors, identical count on main

• Golden masters untouched

Notes

• grep -rni hybrid processbehavior docs tests now returns only the two comments that explain the removal.
• The app may display r2_method or residual_calculation_method text; check it for the retired spellings when its library pin moves, not here.
• The docs site rebuilds from main on merge; the MyST CLI is not installed on this machine, so the three rewritten passages were reviewed in source only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BKphCi1LC1hjGYteWEK9JV