napari-segmencolo 0.1.0

performs image segmentation by leveraging the colocalization of multiple fluorescence channels

napari-segmencolo

A napari plugin for AI-based segmentation with multichannel colocalization filtering, classification, and export to Imaris / Excel.

Developed during an internship in fluorescence imaging, to replace an Imaris-based workflow with a reproducible open-source pipeline.

---

This napari plugin was generated with copier using the napari-plugin-template.

Features

Tab	What it does
① Segmentation	StarDist · Cellpose · Ilastik-style pixel classification — 2D & 3D
② Colocalization	KEEP/EXCLUDE filtering by fluorescence channel
③ Classification	KMeans (unsupervised) or RandomForest (semi-supervised), with nameable classes
④ Export Imaris	TIFF (all licenses) or IMS/HDF5 (native Imaris) + object counts to Excel
⑤ Batch	Process a whole folder of CZI files automatically → Excel summary

Works in 2D and on z-stacks (via MIP projection or slice-by-slice merging).

Installation

You can install napari-segmencolo via pip:

pip install napari-segmencolo

To install together with napari and a Qt backend:

pip install "napari-segmencolo[all]"

For development (from a local clone):

pip install -e ".[all]"

Quick start

1. Segmentation

1. Open your image in napari (File > Open, or drag and drop).
2. In the plugin, ① Segmentation tab:
   • Select the layer to segment (e.g. DAPI for nuclei).
   • Choose StarDist (recommended for round nuclei).
   • Pick a Z handling mode — 2D projection (MIP) is recommended for counting (every nucleus counted once).
   • Optional: draw a rectangle with the Shapes tool, then tick ROI.
   • Click ▶ Run segmentation.

2. Colocalization filtering

Example: keep only the green nuclei that do NOT colocalize with the red channel.

1. ② Colocalization tab → Add a rule.
2. Select the red channel, mode EXCLUDE, threshold = 500, overlap = 0.3.
3. Click ✔ Apply filtering.

A new Filtered_labels layer appears in napari.

3. Classification (e.g. healthy vs apoptotic nuclei)

1. ③ Classification tab: pick the labels layer and a reference channel.
2. Set the number of classes and name them (e.g. "Positive", "Negative").
3. KMeans: classes are formed automatically from intensity + morphology. RandomForest: annotate a few labels by hand (label 3 → class 1, …), then classify.

The class names are reused as column headers in the Excel export.

4. Export for Imaris / counts

1. ④ Export Imaris tab, select the labels layer to export.
2. Enter the voxel size (µm) matching your acquisition.
3. Click 💾 Export as TIFF (then in Imaris: File > Open > select the .tif).
4. Click 📊 Export counts (Excel) to save object counts (total + per class).

To convert to Surfaces in Imaris: Edit > Surfaces > Add New Surfaces > Detect from Channel.

5. Batch processing

1. ⑤ Batch tab → Browse… to pick a folder of .czi files.
2. Channel names are read from the first file → choose the nuclei and marker channels by name.
3. Set the segmentation parameters and (optionally) KMeans classification.
4. Click ▶ Run batch → Excel to produce a summary table (one row per image). Tick Show each image + segmentation in napari to verify results visually.

File architecture

src/napari_segmencolo/
├── __init__.py          # Package entry point (OpenMP workaround, exposes the widget)
├── napari.yaml          # napari manifest (declares the widget)
├── _widget.py           # Main GUI (the 5 tabs) and orchestration
├── segmentation.py      # StarDist, Cellpose, Ilastik-style + Z-plane merging
├── colocalization.py    # Multichannel colocalization filtering
├── classification.py    # Feature extraction + KMeans / RandomForest
├── stats.py             # Object counting + Excel export
├── czi_io.py            # Direct CZI reading (channel names + MIP)
└── export_imaris.py     # TIFF export

tests/
└── test_colocalization.py

Main dependencies

• napari, qtpy — viewer and GUI
• stardist, cellpose — deep-learning segmentation
• scikit-image, scikit-learn — image processing and classification
• pandas, numpy — data and arrays
• tifffile — TIFF export
• openpyxl — Excel export
• h5py — IMS / HDF5 export (optional)
• pylibCZIrw — CZI reading (batch mode)

The Ilastik-style mode is implemented in-house (scikit-image + scikit-learn); it does not require an Ilastik installation.

Author

Lena PROUX — Imaging internship. Plugin built to replace an Imaris-based workflow with a reproducible, open-source pipeline.

Credits and citations

This plugin builds on several open-source libraries. It does not redistribute their source code — they are used as standard Python dependencies, installed via pip, which every license below permits.

Software used

Library	Role in the plugin	License
napari	Image viewer & plugin framework	BSD-3-Clause
StarDist	Nucleus segmentation	BSD-3-Clause
Cellpose	Cell / nucleus segmentation	BSD-3-Clause
scikit-image	Image processing & object features	BSD-3-Clause
scikit-learn	KMeans, RandomForest	BSD-3-Clause
pandas / NumPy	Tables & arrays	BSD-3-Clause
tifffile	TIFF export	BSD-3-Clause
openpyxl	Excel export	MIT
qtpy	Qt binding abstraction	MIT
h5py	IMS / HDF5 export	BSD-3-Clause
pylibCZIrw	CZI file reading (batch)	LGPL-3.0

Note on pylibCZIrw (LGPL-3.0): it is used as an unmodified, separately installed dependency (no source code is copied into this plugin). The LGPL permits this use within a BSD-licensed project; users remain free to replace or upgrade the library independently.

Please cite (for scientific use)

If you use the segmentation models in published work, please cite the original papers — this is requested by their authors and is independent of the software license:

• StarDist — Schmidt, U., Weigert, M., Broaddus, C., & Myers, G. (2018). Cell Detection with Star-Convex Polygons. MICCAI 2018. https://doi.org/10.1007/978-3-030-00934-2_30
• Cellpose — Stringer, C., Wang, T., Michaelos, M., & Pachitariu, M. (2021). Cellpose: a generalist algorithm for cellular segmentation. Nature Methods, 18, 100–106. https://doi.org/10.1038/s41592-020-01018-x
• napari — napari contributors (2019). napari: a multi-dimensional image viewer for Python. https://doi.org/10.5281/zenodo.3555620

Pretrained models

The StarDist and Cellpose pretrained models (2D_versatile_fluo, cyto3, …) may carry their own usage terms. They are suitable for academic research; verify their conditions before any commercial use.

Contributing

Contributions are very welcome. Tests can be run with tox; please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the BSD-3 license, "napari-segmencolo" is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.