Grouping: link by localization precision (SMAP's locprec mode)

[jries]

What

Grouping gets a second way to link, beside the fixed box: link by precision, SMAP's locprec mode (connectsinglesigma.c). A localization joins a blink when its distance r from the running position satisfies

r² < k² (σ_h² + σ²),   with r held between dx_min and dx_max

Defaults: k = 2.5 (SMAP's), dx_min = 10 nm, dx_max = 150 nm. Fixed distance stays the default mode.

• csrc/group.hpp, csrc/group.cpp: the precision test inside the C++ walk. It is optional (var, k2, r2min), and the box path doesn't change.
• src/smappy/group.py: GroupSettings gets link, k, dx_min and dx_max. connect(..., precision=, k=, dx_min=). The precision is read in the same unit as the positions (xy_err_nm or xy_err_pix).
• src/smappy/_group_chunked.py: the seam repair carries the running variance and applies the same test.
• src/smappy/gui/dialogs.py: the grouping dialog gets a link by choice and shows only the fields of the chosen mode.
• The docs: the Render tab page (the link settings... control and the grouping paragraph), NOTES.md under Grouping, and the module docstrings.
• Also fixed the stale claim, in _group_chunked.py and a test comment, that the chunked linker "is not wired into group()". It is, through link_chunks (8 by default).

Departures from SMAP

• Which precisions are used. SMAP uses the seed's precision for both terms, so the candidate's precision never enters the test. Here σ is the candidate's precision and σ_h is the running position's precision, propagated through the walk's mean as (σ_h² + σ²)/4.
• How the bounds apply. The bounds clamp r itself. SMAP floors each 2.5σ at the minimum separately, so its smallest radius was really √2 · dx_min.

Behaviour to know

• Links cut on purpose. With correct precisions, r²/(σ_h² + σ²) is χ² with 2 degrees of freedom, so a fraction 1 − exp(−k²/2) of links is kept: 95.6% at k = 2.5. A test checks this.
• Missing precisions. A localization with a NaN precision links up to dx_max. A table with no precision column falls back to the box and shows a warning, because every file is grouped as it opens.
• The chunked linker is a little less exact in this mode. The running variance is state that a head re-seeded past a seam does not have. On the all-seam test table it matches the sequential walk for 99.6% of localizations, against 99.9% for the box.

Tests

7 new tests in tests/test_group.py:

• the kept-link fraction against the χ² prediction
• the lower and upper bounds, and that the test is a radius rather than a box
• NaN precision
• bright neighbours separated and dim blinks kept, compared with a 50 nm box
• chunked against sequential
• pixel-unit tables
• the fallback when there is no precision column

The full suite passes with Qt offscreen: 1311 passed, 4 skipped.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UHPexokxDqWV5qNmdFKY9R

---

Generated by Claude Code