Design a sensory screen before it runs: blocked, carry-over balanced serving plans

[kgdunn]

Summary

process_improve.sensory currently analyses panel data that already exists (validate, panel check, relate, compare_products). This PR adds the step before that: turning a long candidate list into a serving sheet a sensory lab can actually run.

New module src/process_improve/sensory/screening.py. A panel screen is not an ordinary designed experiment, and the module handles the three reasons why:

Session capacity. An assessor can only judge a handful of samples in one sitting before fatigue and carry-over dominate. Once the candidate list is longer than a session, every assessor sees only a subset, so the design is an incomplete block design with the assessor-session as the block. cyclic_block_design builds the blocks so replication is equal (or as near-equal as the numbers allow) and every pair of candidates meets inside a block about equally often - the pairwise concurrence, which decides how precisely two candidates can be compared with each other.

Carry-over and position. williams_design returns serving orders in which every treatment appears once per position and every ordered pair occurs equally often, so no candidate is systematically favoured by what was tasted before it. An even treatment count needs one square; an odd count needs a mirrored second one.

Sensitivity. detectable_difference converts a residual standard deviation and a panel size into the smallest difference the screen can resolve; required_panelists inverts it. Both Bonferroni-correct for the size of the comparison family, because testing 20 candidates against one control is 20 comparisons.

sensory_screening_plan assembles all three into one sheet, optionally anchoring a reference sample first in every block so session and assessor drift can be removed later. The sheet uses the descriptive_long column names, so filling in the scores feeds it straight into compare_products with panelist_id as the block - the design half and the analysis half now close the loop.

Design note: why two move types in the block construction

The greedy fill lands close to balance but not on it. The hill-climb that follows uses two moves and needs both:

• a substitution (one treatment in a block replaced by one not in it) changes replication, so it is what levels replication out;
• an exchange (two blocks trade one treatment each) leaves replication untouched, so it is what goes on improving concurrence after replication has settled.

With replication already level, every substitution makes it worse, so a substitution-only search stalls one step short. With the exchange added, the construction recovers an exact balanced incomplete block design when one exists - verified against the Fano plane (t=7, k=3, b=7, r=3, lambda=1).

Behaviour worth knowing

• A panel too small to cover the candidate list is reported in warnings, not silently truncated. Quietly screening 18 of your 21 candidates is the failure mode worth being loud about.
• plan_diagnostics says whether the blocks are an exact BIBD (balanced), plus replication and concurrence min/max/mean, control coverage and position balance, so the plan is contestable rather than taken on faith.
• Everything is seeded and reproducible.

Also included

• Agent tools sensory_screening_plan and sensory_detectable_difference (@tool_spec, registered in get_sensory_tool_specs).
• A new "Before the panel: designing the screen" section in docs/user_guide/sensory_panel.rst.
• Version 1.62.2 -> 1.63.0 (new module), CITATION.cff and CHANGELOG.md kept in sync.

Test plan

• uv run pytest tests/test_sensory_screening.py --no-cov - 36 tests pass
• Williams squares: ordered-pair balance verified for t = 2, 4, 6, 8 (each pair once) and t = 3, 5, 7 (each pair twice), plus the Latin-square position property
• cyclic_block_design recovers the Fano plane; near-equal replication (max - min <= 1) for a (20, 6, 10) case with no exact BIBD; deterministic for a seed
• Serving plan: capacity respected, no repeat within a block, control in every block at position 1, reproducible, shortfall warned, invalid inputs rejected
• detectable_difference monotone in n and in the comparison count, linear in sd; required_panelists verified to be the smallest n that reaches the target (n-1 does not)
• uv run ruff check and uv run mypy src/process_improve/sensory/screening.py clean

Note: uv.lock is deliberately not touched.

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.33887% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/process_improve/sensory/screening.py	98.07%	2 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!