[follow-up] Empirically validate TEMPORAL_NYQUIST_RATIO_MAX and DERR_EXPECTED_PERIOD_S from literature + multi-plate data

[eberrigan]

[follow-up] Empirically validate TEMPORAL_NYQUIST_RATIO_MAX and DERR_EXPECTED_PERIOD_S defaults from literature + multi-plate data

Parent epic: #197
Originating PR: #216 / add-circumnutation-tier1-derr-faithful
Type: documentation / sensitivity-sweep (no code-correctness blocker)
Priority: medium — defer until multi-plate / multi-genotype data lands

Summary

PR #6 introduces two new threshold constants that lack multi-plate empirical validation:

• TEMPORAL_NYQUIST_RATIO_MAX = 0.25 — interim default, anchored to theory.md §6.5's empirical observation that "5-min cadence is comfortable, 10-min still works, 30-min aliases the nutation" (ratios 0.09 / 0.18 / 0.54). 0.25 sits between "still works" (0.18) and "aliases" (0.54) conservatively. But the EXACT threshold value lacks multi-plate empirical confirmation.
• DERR_EXPECTED_PERIOD_S = 3333.0 — rice-specific (Nipponbare), sourced from Derr Sept-2025 pilot. Per Rivière 2022 §1.2, nutation period in Averrhoa is 5400-14400 s (1.6-4.3× range). On non-rice species the constant must be overridden via ConstantsT, but the rice value itself is N=1 plate (plate-001 Nipponbare).

This issue proposes a sensitivity sweep on a multi-plate / multi-genotype dataset once available, mirroring the #205-#208 pattern that PR #3 used for the QC tier thresholds.

Why

The two constants are "load-bearing for the trait emission's biological interpretation" (per _constants.py docstrings) but currently rest on:

• A single 5-minute cadence anchor (one plate; one species; one cadence)
• A single forensic-match target T=3333 s (one plate; the empirical median across 6 tracks is closer to T≈4013 s per the PR Added bases functions #6 GREEN-phase Reconciliation Appendix, suggesting either Derr's pipeline differs from ours or the rice population has more nutation-period variability than the N=1 reference captures)

Without multi-plate validation, we don't know whether:

• TEMPORAL_NYQUIST_RATIO_MAX = 0.25 is too lenient (a real 8-minute-cadence plate with sharp nutation might alias OR pass the gate inappropriately) or too strict (a 10-minute-cadence plate might fail the gate when it shouldn't).
• DERR_EXPECTED_PERIOD_S = 3333.0 captures the population mean for Nipponbare or just one plate's outlier value. The PR Added bases functions #6 GREEN-phase data suggests N=6 tracks median at ~T=4013s, not 3333s.

In scope (when this issue is acted on)

1. Acquire a multi-plate / multi-genotype dataset. Candidates: Suyash Patil's Nipponbare_0.8PG_GA4vsTZT experiment (4 plates: MOCK, GA₄, MOCK rep, TZT-treated). Sayuri Tomonaga's mutant collection (if applicable). Future Salk Plant Phenotyping Center datasets.
2. Run nutation.compute with default constants on each plate.
3. Per-plate report:
   • Distribution of recovered T_nutation_median (per-track median + IQR across tracks)
   • Distribution of cadence_nyquist_ratio (should all be safely below TEMPORAL_NYQUIST_RATIO_MAX for legitimate cadences)
   • is_nutating == True rate across tracks (gate quality check)
4. For DERR_EXPECTED_PERIOD_S: compute the population mean and population CV across plates. Decide whether 3333.0 is the right default OR whether a different value (or per-species table) is needed.
5. For TEMPORAL_NYQUIST_RATIO_MAX: identify plates with marginal cadence (e.g., 10-min cadence) and check whether the gate correctly distinguishes them from comfortable-cadence plates (5-min).
6. If the analysis suggests different defaults, propose them in a follow-up OpenSpec change.

Out of scope

• Replacing the constants with a species-aware lookup table (could be a separate enhancement after this sweep completes).
• Adding new constants for additional spectral-quality checks (out of scope for "validate existing defaults").

Acceptance

• A short markdown report at docs/circumnutation/temporal_nyquist_and_derr_period_validation_2026-MM-DD.md documenting the sweep results.
• If the recommended defaults differ from 0.25 / 3333.0, a follow-up OpenSpec change updates _constants.py + roadmap.md CC-7 / CC-8 / theory.md §7.2 as appropriate.
• The follow-up change bumps _CONSTANTS_VERSION per the version-sentinel contract.

Cross-references

• Originating PR: feat(circumnutation): Tier 1 Derr-faithful trait emission (#215) #216
• Pattern precedent: [follow-up] Empirically validate pairwise-agreement thresholds for circumnutation QC #205 / [follow-up] Empirically validate outlier-step thresholds for circumnutation QC #206 / [follow-up] MSD lag selection for circumnutation noise estimation #207 / [follow-up] ±inf input detection for circumnutation qc.compute #208 (α/β/γ/δ QC threshold validation; PR Add backticks to Series docstring #3 follow-up issues using the same multi-plate sweep methodology)
• design.md GREEN-phase Reconciliation Appendix (which documents the N=1 limitation explicitly)
• Theory: docs/circumnutation/theory.md §6.5 (Cadence-Nyquist), §7.2 (Derr reference period)
• Empirical anchor: docs/circumnutation/preliminary_results_2026-05-07.md §4.4 (single-plate T ≈ 3333 s anchor)

Labels

circumnutation, documentation, follow-up, medium-priority