napari-racc

napari-racc is a napari plugin for Regression Adjusted Colocalisation Colour Mapping (RACC), a qualitative visualization method for 2D and 3D fluorescence microscopy data.

The plugin takes two image layers, computes the RACC index in 3D whenever the inputs are volumes, and adds interactive overlay, RACC, side-by-side, MIP, and scatter-plot views to the napari viewer.

Screenshots

3D side-by-side view with the thresholded channel overlay on the left and the RACC volume on the right.

3D-derived maximum-intensity projection view.

Features

• two-channel RACC calculation from napari Image layers
• live threshold, theta, percentile, and Costes threshold controls
• linked analysis/display cutoffs with optional display-only channel thresholds
• independent RACC display minimum without changing the numeric result
• synchronized translucent, maximum-intensity, and additive 3D rendering modes
• 3D-only intensity and RACC opacity controls, plus background suppression for clearer deep structures without making 2D slices or fixed MIPs faint
• transparent zero-valued RACC voxels for clean volume rendering
• thresholded RGB overlay volume with selectable probe colors
• side-by-side overlay/RACC and 3D-derived MIP views
• scatter histogram with visible axes, regression, threshold, and percentile-band overlays
• XY and Z display scale controls for metadata-light TIFF stacks
• scrollable control panel with expandable input layer selectors
• export of the numeric RACC result stack as TIFF

Installation

Install from PyPI:

pip install napari-racc

For local development:

git clone https://github.com/rensutheart/napari-racc.git
cd napari-racc
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[dev]"

Fish shell users should activate the environment with:

source .venv/bin/activate.fish

Usage

1. Open napari.
2. Open two image stacks or use File > Open Sample > RACC.
3. Start the widget from Plugins > RACC (napari-racc).
4. Select channel 1 and channel 2.
5. Adjust thresholds manually or press Costes thresholds.
6. Press Run RACC.
7. Keep Link channel cutoffs to analysis thresholds enabled for a directly comparable intensity view, or disable it to clean up the display without changing the analysis.
8. Choose Translucent, Maximum intensity (MIP), or Additive with the Rendering method control under 3D volume rendering; the selection is applied to both the intensity overlay and the RACC volume.
9. Under Display mapping, use the channel cutoffs and RACC display minimum to remove weak haze in both 2D and 3D. Under 3D volume rendering, set the intensity/RACC opacities and background suppression. Those volume controls are deliberately ignored in single-slice and fixed 2D Z-MIPs views. None of these display controls changes the calculated or exported RACC values.
10. Use Overlay, RACC, 3D side by side, and 2D Z-MIPs to switch views.
11. Press Export RACC TIFF to save the numeric RACC result stack for use in other software.

RACC is calculated over the full 3D volume when 3D inputs are used. The MIP view is derived from the 3D calculation; it is not a 2D recalculation.

Development

python -m npe2 validate src/napari_racc/napari.yaml
python -m ruff check src
python -m pytest
python -m build

Launch one example dimensionality at a time:

python scripts/launch_racc_examples.py --example 3d
python scripts/launch_racc_examples.py --example 2d

Do not launch the napari viewer with QT_QPA_PLATFORM=offscreen; napari needs a real Qt/OpenGL context for the viewer on macOS.

Citation

If you use this plugin or the RACC method in research, cite:

Theart RP, Loos B, Niesler TR. Regression adjusted colocalisation colour mapping (RACC): A novel biological visual analysis method for qualitative colocalisation analysis of 3D fluorescence micrographs. PLOS ONE 14(11): e0225141. https://doi.org/10.1371/journal.pone.0225141

License And Patent Notice

This software is licensed under the PolyForm Noncommercial License 1.0.0. It is source-available for noncommercial research, education, and evaluation use, but it is not an OSI open-source license.

Use of the RACC method may be covered by patent rights, including US patent application US20220189129A1 and related patent family members. Commercial, clinical, diagnostic, or for-profit service use requires a separate license from the rights holder. See LICENSE, NOTICE, and PATENTS.md.