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

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

@@ -4,6 +4,86 @@ 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.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.**
+  The out_of_plane (yellow) class used a per-frame amplitude/SNR percentile, so
+  when the bead population is uniformly low-quality a genuinely good bead sitting
+  near the moving percentile line was demoted ~a quarter of the time — driven
+  mainly by a `low-SNR OR` clause that could yellow a bead whose amplitude was
+  fine. Fix: (1) require the AMPLITUDE to actually be low for the dim class (SNR
+  is now only a secondary confirmation, never demotes a bright bead on its own),
+  and (2) add a high-NCC singlet guard (NCC ≥ 0.80) so a well-matched bead is
+  immune to the dim percentile. Verified on real data: the previously-flickering
+  bead (amp~164, NCC~0.94) is now singlet in 1000/1000 frames (was ~76%), while a
+  genuinely dim bead (amp~75, NCC~0.76) correctly STAYS out_of_plane — the garbage
+  rejection (NCC floor) and aggregate class are untouched. This preserves the
+  hard-won hot-pixel/ring/noise rejection while stopping the erroneous demotion of
+  real beads.
+
+### Added — MSD lag-window fit gate (hardware-defensible fit bounds)
+- `fit_anomalous_diffusion` now computes a **defensible MSD lag window** bounded
+  by the frame rate (high-frequency cutoff = frame interval) and the acquisition
+  duration (low-frequency cutoff), and by default confines the D/α fit to it.
+  Fitting outside this band (only sub-second lags, dominated by the localization
+  floor, or out toward the full duration, where a handful of pairs dominate)
+  produces a wrong D/α. Exposed under the VPT "Show advanced fit / moduli options"
+  expander:
+  - **Upper-lag rule** (user-selectable, with tooltips): *Fraction of track length*
+    (default, 0.25), *Fixed frequency window* (set the upper lag in seconds), or
+    *Minimum independent pairs* (keep a lag only while ≥ N independent tracks span
+    it).
+  - **"Confine fit to scientifically defensible bounds"** toggle (default ON) —
+    clips the fit to the window; turn off to fit the full range at your own risk.
+  - The gate **warns, never blocks**: if the acquisition can't cover the requested
+    window (too-short clip), it emits a clear warning and falls back gracefully.
+  Validated on real data across all three rules + the confine toggle + the
+  too-short-data warning path.
+
+## [1.5.331] - 2026-07-10
+### Added — Evans (2009) viscoelastic moduli + bootstrap confidence bands
+- **G′/G″ (storage/loss moduli) now use the Evans et al. (2009) direct
+  compliance→moduli conversion** (`compute_moduli_evans` in
+  condensate_physics_tools.py), replacing the Mason (2000) single-point algebraic
+  GSER in the VPT pipeline. Evans represents the creep compliance J(t) as a
+  piecewise-linear interpolant and analytically Fourier-transforms it, so
+  G*(ω)=1/(iω·J̃(ω)) with **no local-power-law assumption** — it handles
+  curvature, plateaus, and crossovers directly. Validated in-sandbox against
+  known analytic MSDs: exact on a pure viscous fluid (G′≈0, G″=ηω to machine
+  precision) and ~1–2% on a Maxwell fluid across the reliable band. The highest
+  one or two frequencies (shortest lags) are the least reliable and are dropped.
+  The Mason `compute_moduli_gser` is retained (additive/revertable).
+- **Optional bootstrap confidence intervals on G′/G″**
+  (`compute_moduli_evans_bootstrap`), exposed under a new hidden "Show advanced
+  moduli (G′/G″) options" expander in the VPT Step-5 panel (default off). Resamples
+  whole tracks with replacement, recomputes moduli per resample, and shades
+  percentile bands on the plot (`plot_moduli` draws bands when present). Validated
+  in-sandbox: ~93–97% empirical coverage of a known analytic truth for a nominal
+  95% band. This is the honest response to noisy data — it shows which parts of
+  the spectrum to trust.
+- NOTE: a compliance-interpolation upgrade (natural/Akima spline) was evaluated
+  and **rejected** — validated as a no-op on smooth MSDs and unhelpful (can worsen
+  jitter) on noisy ones; the real levers for noise are the CIs above plus upstream
+  trajectory cleanup. Documented as such in the code.
+
+### Added — dual pixel/µm coordinate readout
+- **The napari status bar now shows both the pixel index (r, c) and the world
+  (µm) position under the cursor**, plus the value under the cursor, e.g.
+  `px (r=362, c=483) | µm (y=242.5, x=323.6) | Bead Detections = 171`
+  (`pycat/ui/coordinate_readout.py`, installed at launch in run_pycat.py). PyCAT
+  scales image layers by pixel size (µm/px), so napari's default status showed
+  microns only; pixel indices are what the analysis actually runs in (blob sigma,
+  linking distances, template windows, FIJI cross-referencing), so both are now
+  surfaced. Best-effort and fail-safe — never blocks launch, and leaves napari's
+  default status untouched if the coordinate can't be resolved.
+
+### Docs
+- Added a "Near-term UX & interaction" section to the development roadmap
+  (frame-0-on-load, materialization progress, pixel-size acquisition profiles,
+  command palette, plot↔layer brushing, dual px/µm readout).
+- Added `docs/audits/DEV_NOTES.md` (private, Sphinx-excluded): instrument-scoped
+  module roadmap and known-issues detail kept out of the published docs.
+
 ## [1.5.208] - 2026-07-05
 ### Fixed (overlay stripe — the ACTUAL root cause: a scale mismatch)
 - **The Overlay Image now inherits the source image layer's scale.** Confirmed via git

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycat-napari
-Version: 1.5.330
+Version: 1.5.332
 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/docs/audits/DEV_NOTES.md

@@ -0,0 +1,157 @@
+# PyCAT — Private Development Notes
+
+> **PRIVATE / NOT PUBLISHED.** This file lives in `docs/audits/` which is *outside*
+> the Sphinx source tree (`docs/source/`) and is not in any `toctree`, so it is never
+> built into the public documentation. It intentionally contains lab-specific detail
+> (instrument inventory, hardware-gated scoping, machine/collaborator-specific bug
+> notes) that must **not** appear in anything scraped or shown externally. Keep
+> equipment names and internal scoping here, not in `roadmap.rst`.
+
+---
+
+## 1. Lab / instrument base (scoping reference — keep private)
+
+Informs which advanced analysis modules are worth building; scope modules to real
+hardware. **Do not list this equipment in published docs.**
+
+- **LUMICKS C-TRAP** — optical-tweezers + confocal, 3 lasers. Source instrument for
+  the existing FRAP / droplet-fusion / force-distance modules; Lumicks `.h5` files.
+- **ISS Q2** — laser-scanning confocal with APDs on 3 channels; does FLIM and
+  point-detector FCS/FCCS. Native instrument for single-point FCS/FCCS and FLIM.
+- **Andor Dragonfly** — spinning-disk confocal with TIRF/HILO, Micropoint, Mosaic,
+  two pinhole discs (25 & 40 µm). Two cameras: Andor iXon 888 EMCCD (1024×1024,
+  back-illuminated) and Andor Zyla sCMOS; both fast (~1000 fps with cropping). For
+  camera-FCS the **Zyla (sCMOS)** is correct (no EM gain, well-characterized per-pixel
+  noise); the iXon EMCCD is weaker for FCS (EM gain adds multiplicative excess noise
+  ~√2 on variance). Dragonfly TIRF/HILO gives a defined thin axial volume, so
+  **Dragonfly TIRF/HILO + Zyla is a viable present-day imaging/camera-FCS testbed**
+  (spinning-disk is a messier volume model). Unconfirmed: can Dragonfly TIRF route to
+  the Zyla port? sCMOS imaging-FCS also needs a per-pixel offset/gain/variance
+  calibration map (the N&B documented hook).
+- **Leica Stellaris** (campus access) with LIGHTNING deconvolution + a STED path.
+- **Zeiss Airyscan 2** — incoming access (super-resolution detector-array confocal).
+- **Photometrics Kinetix sCMOS** — currently on a Zeiss Axio Observer with LED
+  widefield (epi, no defined axial slice → not ideal for FCS). Future: Kinetix moves
+  to a custom ring-TIRF/HILO scope, with planned PolScope (polarization/birefringence
+  orientation) and FLIM on the other illumination path.
+- Confocal imaging source for the 2D/TS condensate pipelines: Zeiss/ZEN Plan-Apo
+  63×/1.40 Oil, 405 + Argon 488, 3 PMTs, 0.0264 µm/px, DAPI/EGFP/transmitted.
+
+**Implications:** single-point FCS/FCCS and FLIM are native to the ISS Q2 (PyCAT does
+phasor/lifetime *downstream* analysis + import, not raw TCSPC); PolScope/orientation
+pairs with the future Kinetix polarization path.
+
+---
+
+## 2. Advanced spectroscopy / imaging module roadmap (hardware-scoped)
+
+All are **import-and-analyze** modules: PyCAT quantifies what the specialized
+instrument produces; it does not reimplement acquisition. Ordered by data-availability.
+
+**Buildable now (data exists today):**
+
+- **FCS/FCCS analysis module** — native to the ISS Q2 (APDs, 3 channels). Import
+  point-detector correlation curves / photon streams; fit diffusion models
+  (single/multi-component, triplet, anomalous); FCCS cross-correlation amplitude ratio
+  → bound fraction. Composes with the fluctuation-spectroscopy family (MSD/VPT
+  viscosity, N&B, SpIDA). *Prereq:* confirm what the Q2 exports (correlation curves vs
+  raw photon stream vs `.fcs`). Extend `correlation_func_analysis_tools.py` (already
+  has spatial ACF/CCF + Gaussian-peak fitting, ICS-style); N&B (`nb_tools.py`) already
+  flags per-pixel sCMOS variance/offset correction.
+- **FLIM phasor + downstream module** — native to ISS Q2. Import-based (no raw TCSPC).
+  Import lifetime/decay → phasor-plot analysis (model-free lifetime separation) →
+  segmentation-linked biology (per-condensate mean lifetime, lifetime vs partition
+  coefficient, lifetime shift across a phase transition). The distinctive "PyCAT owns
+  the downstream biology" play.
+- **RICS / STICS** (raster & spatiotemporal image correlation spectroscopy) —
+  highest-leverage near-term. Works on current laser-scanning confocals (ISS Q2,
+  C-Trap) with no new hardware; extracts diffusion maps AND flow/velocity fields.
+  Reuses the existing spatial-correlation backend. Smaller lift than camera
+  imaging-FCS. *Prereq:* confirm the Q2 / C-Trap scanned-image-series export format +
+  whether pixel dwell / line time is in metadata (RICS depends on scan timing).
+
+**Future (hardware-gated):**
+
+- **Imaging / multipoint camera-FCS** — flagship but future. Tie to the Kinetix's
+  future ring-TIRF/HILO scope, NOT the current Axio Observer + LED widefield (no
+  defined axial slice → per-pixel FCS volume not well-posed). Per-pixel temporal
+  autocorrelation of a fast sCMOS stream → diffusion/concentration maps. Hard parts:
+  per-pixel sCMOS noise/variance/offset correction, frame-timing calibration,
+  bleaching, TIRF/HILO axial volume model.
+- **PolScope / orientation analysis** — future, pairs with the Kinetix polarization
+  path. Import orientation/birefringence/anisotropy maps → orientational order
+  parameters, anisotropy distributions, orientation-vs-condensate-structure.
+- **SMLM / localization-table analysis** — three super-res-capable instruments
+  (Dragonfly TIRF single-molecule, campus STED, incoming Airyscan 2) but zero
+  localization-table analysis today. Import localization tables (PALM/STORM/PAINT);
+  the Ripley/PCF cluster-analysis machinery already exists and applies directly; add
+  localization precision + drift correction. LOCAN ecosystem interop lands here.
+- **Fluorescence anisotropy / homo-FRET** (steady-state polarization) — precursor to
+  PolScope; buildable sooner if any current instrument has a parallel/perpendicular
+  channel pair. Two-channel ratiometric-style computation.
+
+*Caveat for all:* some capabilities are inferred from instrument class — confirm the
+specific unit configuration (does the Dragonfly config do true SMLM? does any current
+instrument have polarization optics installed?) before committing.
+
+---
+
+## 3. Known issues (may name specific machines/configs — keep private)
+
+### GPU / OpenGL canvas corruption on some NVIDIA configs (ACTIVE, not resolved)
+
+**Symptom:** after loading an image, clicking the canvas renders the view
+tilted/sheared (diagonal split); scroll/zoom still work (input + data fine — a
+display/framebuffer-presentation problem). Earlier empty-canvas clicks showed
+triangular tearing / swirling moiré + UI vanishing. Constant flickering appears only
+on dim/out-of-focus objects.
+
+**Confirmed NOT a PyCAT bug** — reproduces in plain napari (no PyCAT).
+
+**Environment where seen** (collaborator machine, NVIDIA T400 4GB): Win11, Python 3.12,
+napari 0.7.1, vispy 0.16.2, Qt 5.15.2/PyQt5, **NVIDIA driver 595.97**, OpenGL 4.6,
+1920×1080 @ 100% single monitor, 75Hz HDMI. Ruled out (via `gpu_diag.py`):
+wrong-GPU-selection, integrated graphics, Qt high-DPI scaling, multi-monitor.
+
+**Three OpenGL backends all fail differently:** native NVIDIA → tearing/tilt on click;
+`QT_OPENGL=angle` → crashes at startup (GLError 1282 on `glGetParameter(GL_MAX_TEXTURE_SIZE)`,
+GL context broken at creation); `LIBGL_ALWAYS_SOFTWARE=1` → opens clean but slow to
+start, then tears after repeated clicks.
+
+**Prime suspect:** NVIDIA driver 595.97 (newest; only recently-changed variable; a
+tilt/shear = framebuffer stride/row-alignment presentation bug — a classic driver-build
+regression that hits OpenGL apps while leaving the desktop compositor fine).
+
+**Next steps (awaiting):** clear env vars (`set QT_OPENGL=` / `set LIBGL_ALWAYS_SOFTWARE=`),
+roll back the NVIDIA driver to the prior Studio branch (clean-install checkbox), reboot,
+retest plain napari + load image + click/scroll. Open question: is this the only machine
+affected, or do others on the same napari/vispy fail? (only → isolate this box's
+GPU/driver, rollback is the fix; several → consider pinning napari/vispy.)
+
+**When the fix is confirmed:** write a *public-facing* known-issues note (symptom →
+confirm via plain napari → `gpu_diag.py` → resolution = driver rollback; software
+rendering as an imperfect last resort). A possible PyCAT `--safe-rendering` launch flag
+(sets `LIBGL_ALWAYS_SOFTWARE` before napari init) is opt-in first, but software
+rendering was not fully stable here (tore after repeated clicks) so it's an imperfect
+stopgap, not a clean fix. `gpu_diag.py` delivered (one-shot GPU/OpenGL/Qt/scaling report
++ opens plain napari for the reproduce test).
+
+### Multi-file OME-TIFF with a missing linked member (hardened 1.5.330)
+
+A multi-file OME-TIFF that references a missing sibling (e.g. a `...MMStack_Pos0.ome.tif`
+referencing an absent later-timepoint file) makes the loader zero/truncate the missing
+data, and a degenerate 1-D frame could reach `score_beads_template`, crashing with
+`ValueError: not enough values to unpack (expected 2, got 1)`. 1.5.330 guards this
+(squeeze + skip frame with a warning). Root fix for a *complete* analysis: ensure all
+linked `.ome.tif` files are present, or use a self-contained single-file export.
+
+---
+
+## 4. VPT calibrated-thermodynamics scoping notes (lab-specific framing)
+
+The calibrated intensity → concentration → ΔG_transfer workflow (see public roadmap for
+the capability description) is scoped against the lab's Csat / phase-diagram /
+quantitative-measurement program. This is the flagship manuscript differentiator:
+converts PyCAT from "image analysis" to "biophysical parameter extraction." PyCAT today
+has intensity-based ratios (partition coefficient, client enrichment) but zero
+`delta_g` / standard-curve-concentration code — that gap is the build.

{pycat_napari-1.5.330 → pycat_napari-1.5.332}/docs/source/development/roadmap.rst

@@ -396,6 +396,69 @@ supporting Category B, because PyCAT's point-based spatial statistics are alread
 what localization-cluster analysis needs.
 
 
+Near-term UX & interaction
+--------------------------
+
+Small, mostly self-contained quality-of-life items that improve responsiveness and
+keep the scientist engaged with their data. None are architectural; each can ship
+independently.
+
+.. rubric:: Default to the first frame on load
+
+Most image viewers open a stack on frame 0; PyCAT currently opens on the middle
+frame. Change the default so a freshly loaded stack shows frame 0 (set the viewer's
+current step on the T axis to 0 after load), matching viewer convention.
+
+.. rubric:: Materialization progress on stack-consuming methods
+
+Where a method must read/decode a whole stack before working (e.g. bead detection),
+the progress indication should read as one continuous 0→100% pass rather than
+reaching 100% twice (once for materialization, once for the work). The reusable
+``PhasedProgress`` helper already exists; the remaining work is rolling it out to the
+other stack-consuming workflows so a materialization wait is always labelled and never
+double-counts. Useful app-wide, since materialization is a common shared wait.
+
+.. rubric:: Pixel-size acquisition profiles
+
+Users repeatedly image files from the same microscope with the same missing-metadata
+flaw (no pixel size, often no magnification either), so re-entering the scale every
+load is friction. The robust design is **named acquisition profiles**: the user
+creates and names a profile (storing its pixel size), saved to a small JSON on disk,
+and selects it (or it is remembered as default) at load time. This sidesteps the
+metadata problem by having the human supply the key the file cannot. When camera +
+magnification *are* present in metadata, auto-fill the pixel size as a bonus. Scoped
+as an additive picker on the existing load-time pixel-size dialog, composing with the
+existing "persist through session" option — not a rewrite. (Metadata-only
+auto-recovery was considered and rejected as the primary mechanism, because the exact
+scopes this targets omit the metadata needed to compute the scale.)
+
+.. rubric:: Command palette / search bar
+
+A search bar (command-palette pattern, à la VS Code Ctrl+Shift+P or Spotlight) to
+find and jump to functionality by name, in three scopes of increasing difficulty:
+(1) open a method/widget by name — easy, a fuzzy filter over the existing
+analysis-method registry calling the same launch function the menu does; (2) find a
+layer by name — trivial, a thin wrapper over the viewer's layer list; (3) find a
+step/process within a widget by name — harder, requires steps to be enumerable and
+addressable (name → widget + the control that runs it + a scroll-to/highlight). Ship
+1 + 2 first as a simple palette; extend to steps once step-addressing infrastructure
+firms up (the same "steps as first-class addressable things" requirement also serves
+the pipeline-step-diagnostics dropdown and the linked-navigation object model).
+
+.. rubric:: VPT/MSD plot ↔ layer brushing (first instance of linked navigation)
+
+A concrete, near-term instance of the linked multiscale navigation idea (see the
+biological object model section): click a trajectory in the MSD plot → highlight that
+bead and its track in the canvas and surface its data row, so browsing the plot leads
+back to the data in the image. This is a small build for VPT specifically because the
+identity plumbing already exists end-to-end — every MSD line carries a track id, and
+the tracks layer holds those trajectories keyed by the same id. The missing piece is
+narrow: make the (currently static) MSD plot pickable, map the picked line → track id,
+then select/centre that track in the viewer and surface its row. Once proven here it
+generalizes to the other plots (partition-coefficient scatter → condensate;
+enrichment plot → cell).
+
+
 Calibrated Thermodynamic & Quantitative Condensate Reporting
 ------------------------------------------------------------
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycat-napari"
-version = "1.5.330"
+version = "1.5.332"
 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.330 → pycat_napari-1.5.332}/src/pycat/run_pycat.py

@@ -322,6 +322,16 @@ def run_pycat_func():
     # be skipped entirely by setting PYCAT_SKIP_WARMUP=1.
     viewer = napari.Viewer(title="PyCAT-Napari")
 
+    # Dual pixel / micron coordinate readout in the status bar. PyCAT scales
+    # layers by pixel size (µm/px), so napari's default status shows microns
+    # only; this surfaces the raw pixel index alongside it (px is what the
+    # analysis runs in). Best-effort — never blocks launch.
+    try:
+        from pycat.ui.coordinate_readout import install_coordinate_readout
+        install_coordinate_readout(viewer)
+    except Exception as _e:
+        print(f"[PyCAT] Coordinate readout not installed: {_e}")
+
     if os.environ.get('PYCAT_SKIP_WARMUP', '') not in ('1', 'true', 'True'):
         import threading
         def _warmup():

{pycat_napari-1.5.330 → pycat_napari-1.5.332}/src/pycat/toolbox/analysis_plots.py

@@ -97,7 +97,7 @@ def plot_moduli(moduli_df, title="Viscoelastic moduli (microrheology)",
                 interactive=True):
     """
     Log-log plot of storage G'(ω) and loss G''(ω) vs angular frequency, from
-    compute_moduli_gser(). The crossover (G'=G'') marks the viscoelastic
+    compute_moduli_evans() (or compute_moduli_gser()). The crossover (G'=G'') marks the viscoelastic
     relaxation frequency.
     """
     import matplotlib
@@ -114,6 +114,18 @@ def plot_moduli(moduli_df, title="Viscoelastic moduli (microrheology)",
     w = d['omega_rad_s'].values
     gp = d['g_prime_pa'].values
     gpp = d['g_double_prime_pa'].values
+
+    # Optional bootstrap confidence bands (drawn only if the columns are present,
+    # produced by compute_moduli_evans_bootstrap). Shaded region behind the lines.
+    if {'g_prime_lo', 'g_prime_hi'}.issubset(d.columns):
+        ax.fill_between(w, np.clip(d['g_prime_lo'].values, 1e-12, None),
+                        np.clip(d['g_prime_hi'].values, 1e-12, None),
+                        color='#c44e52', alpha=0.18, linewidth=0)
+    if {'g_double_prime_lo', 'g_double_prime_hi'}.issubset(d.columns):
+        ax.fill_between(w, np.clip(d['g_double_prime_lo'].values, 1e-12, None),
+                        np.clip(d['g_double_prime_hi'].values, 1e-12, None),
+                        color='#4c72b0', alpha=0.18, linewidth=0)
+
     # only positive values are meaningful on log axes
     ax.plot(w, np.clip(gp, 1e-12, None), '-o', ms=4, color='#c44e52',
             label="G′ (storage / elastic)")