pycat-napari 1.5.332__tar.gz → 1.5.334__tar.gz

{pycat_napari-1.5.332 → pycat_napari-1.5.334}/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to PyCAT-Napari will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.334] - 2026-07-10
+### Fixed — VPT linker shattered stable beads into short tracks (the core linking problem)
+- **Root cause 1 — gap-frame off-by-one.** The greedy linker's viability AND
+  expiry checks used `t - last_frame <= max_gap_frames`, which at `gap=0` rejects
+  even the immediately-previous frame — collapsing every detection into its own
+  length-1 "track" (and hanging/crashing the GUI when it then tried to build a
+  Tracks layer from tens of thousands of singletons). Fixed to
+  `<= max_gap_frames + 1` so `gap=0` links consecutive frames, `gap=1` bridges one
+  missing frame, etc. The Bayesian linker had the same off-by-one in its expiry
+  check only (inconsistent with its own viability filter, which was already
+  correct) — also fixed. Verified on real data: a confirmed stable bead present in
+  1000/1000 frames now links into ONE 1000-frame track instead of shattering.
+- **Root cause 2 — max linking distance too tight, now auto-derived from bead
+  motion.** The dominant problem: the default linking distance (~0.4 µm) was below
+  the beads' own frame-to-frame jitter tail (they move up to ~340 nm/frame), so it
+  clipped real motion and broke stable beads into short fragments that cannot
+  support the MSD measurement window. **New `estimate_linking_distance_um()`
+  derives a physically-grounded distance WITHOUT linking any tracks**, via a
+  short-window MAX-projection of the stack: the projected bead width broadened
+  beyond the single-frame PSF width gives the per-frame displacement scale
+  (`motion_σ = √(σ²_proj − σ²_psf)`), and the distance is `k × motion_σ` (k margin,
+  default 2.5), capped at the bead footprint so it can't grab neighbours. It is
+  viscosity-adaptive (slow beads → tight, fast beads → loose) and needs no
+  provisional linking pass. Auto-filled into the Step-4 linker field after Detect
+  Beads (shown and editable; anti-black-box), with the margin `k` exposed under a
+  new "Show advanced linking options" expander. Validated on real data: derives
+  0.58 µm (per-frame motion ~232 nm × 2.5), and linking there yields full
+  1000-frame tracks — 10% of tracks now span ≥80% of the movie (was ~0%),
+  i.e. measurement-grade trajectories.
+- **GUI crash guard.** If a link still comes out degenerate (>2000 tracks and
+  >90% single-frame), PyCAT warns and skips building the Tracks layer instead of
+  freezing.
+
+### Changed — track-length histogram pops out
+- The linker track-length histogram now opens as a dockable "Track lengths" panel
+  (reused across relinks) instead of sitting inline in the Step-4 form.
+
+## [1.5.333] - 2026-07-10
+### Added — VPT detection-variant staging + track-length histogram
+- **Detection-variant staging framework.** `detect_beads_stack` gained a
+  `detection_variant` argument (default `'baseline'` = the 1.5.329-validated
+  path, byte-identical). New detection/classification approaches are opt-in
+  variants routed through their own branches, so the validated ~8.325-through-
+  TrackMate path stays selectable and any regression is a clean one-arg revert. A
+  `compare_detection_variants()` harness runs two variants on the same stack and
+  reports the classification diff, and the chosen variant is recorded on the
+  output DataFrame's attrs. This is the safety net for the detection rework —
+  every proposed change is A/B-measured against baseline before it is trusted.
+- **`ring_merge` variant** (`dedup_detections_ring_merge`) — sigma-scaled merge
+  radius that folds DIM Airy-ring fragments into their BRIGHT centre while keeping
+  two genuinely-bright nearby beads as two. Built and kept in the codebase but
+  **not surfaced in the widget and flagged as needing validation data with
+  resolved Airy rings**: A/B on the current bead data showed it is a near no-op
+  there (beads well-separated, blob_log already ~one detection per bead). Reach it
+  via `detection_variant='ring_merge'`.
+- **`hot_pixel_reject` variant** (`build_hot_pixel_mask` + harsher on-pixel NCC
+  gate) — identifies FIXED sensor hot/dead pixels from the stack's *temporal*
+  statistics (scene-independent: hot pixels are flat in time, tstd~3-4; beads are
+  variable, tstd~40-50), then applies a STRICTER acceptance test to detections
+  landing on them rather than a flat veto — so a real bead drifting over a hot/
+  dead pixel still survives on its template evidence. Validated correct and safe
+  (every confirmed bead survived, including one adjacent to a hot pixel). Nearly a
+  no-op on the current clean fluorescence data (~18 hot pixels found, blob_log
+  barely fires on them); earns its place on data/modes that turn hot pixels into
+  recurring false detections. Reach it via `detection_variant='hot_pixel_reject'`.
+- **Track-length histogram in the linker widget.** Step 4 (Link Trajectories) now
+  shows an embedded histogram of trajectory lengths (frames per track) after each
+  link. A healthy link piles mass toward long tracks; a fragmentation-prone linker
+  shows a spike of very short tracks. The title reports the track count and the
+  fraction spanning ≥½ the movie, and a dashed line marks the median — an
+  at-a-glance linker-quality check. Fails safe if matplotlib-Qt embedding is
+  unavailable.
+
 ## [1.5.332] - 2026-07-10
 ### Fixed — VPT classifier green↔yellow flicker on bright, well-matched beads
 - **A bright, high-NCC bead no longer flips singlet↔out_of_plane frame-to-frame.**

{pycat_napari-1.5.332 → pycat_napari-1.5.334}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycat-napari
-Version: 1.5.332
+Version: 1.5.334
 Summary: Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis
 Project-URL: Homepage, https://github.com/BanerjeeLab-repertoire/pycat-napari
 Project-URL: Repository, https://github.com/BanerjeeLab-repertoire/pycat-napari

{pycat_napari-1.5.332 → pycat_napari-1.5.334}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycat-napari"
-version = "1.5.332"
+version = "1.5.334"
 description = "Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{pycat_napari-1.5.332 → pycat_napari-1.5.334}/src/pycat/toolbox/dynamic_spatial_tools.py

@@ -332,9 +332,12 @@ def link_trajectories_bayesian(
                 assigned_dets.add(c)
             # else: death (r < n_viable, c >= n_curr) — track ends naturally
 
-        # Expire tracks not seen for too long
+        # Expire tracks not seen for too long. Must match the viability filter
+        # above (t - last_frame <= max_gap_frames + 1); using the bare
+        # max_gap_frames here expired tracks one frame too early, so a track was
+        # admitted as viable next frame but could already have been dropped.
         active = {tid: info for tid, info in active.items()
-                  if t - info['last_frame'] <= max_gap_frames}
+                  if t - info['last_frame'] <= max_gap_frames + 1}
 
     # ── Gap closing: second pass ──────────────────────────────────────────
     if max_gap_frames > 0:
@@ -470,9 +473,17 @@ def link_trajectories(
         curr = df[df['frame'] == t].copy()
         curr_pts = curr[['y_um', 'x_um']].values
 
-        # Find which active tracks are still linkable (within gap window)
+        # Find which active tracks are still linkable (within gap window).
+        # max_gap_frames = number of MISSING frames tolerated, so a track last
+        # seen at frame f is linkable at frame t when (t - f) - 1 <= max_gap,
+        # i.e. t - f <= max_gap + 1. gap=0 therefore links CONSECUTIVE frames
+        # (t - f == 1), gap=1 bridges one missing frame (t - f == 2), etc.
+        # (Previously this used `t - f <= max_gap`, an off-by-one that made
+        # gap=0 reject even the immediately-previous frame — collapsing every
+        # track to length 1. Beads present in consecutive frames must link at
+        # gap=0.)
         viable = {tid: info for tid, info in active_tracks.items()
-                  if t - info[2] <= max_gap_frames}
+                  if t - info[2] <= max_gap_frames + 1}
 
         if not viable or len(curr_pts) == 0:
             # Start new tracks for all detections this frame
@@ -516,9 +527,10 @@ def link_trajectories(
                     df.at[df_idx, 'y_um'], df.at[df_idx, 'x_um'], t)
                 next_track += 1
 
-        # Remove expired tracks
+        # Remove expired tracks (same gap semantics as the viability filter:
+        # keep a track while it could still be linked at the next frame).
         active_tracks = {tid: info for tid, info in active_tracks.items()
-                         if t - info[2] <= max_gap_frames}
+                         if t - info[2] <= max_gap_frames + 1}
 
     return df