napari-segmencolo 0.1.2

A napari plugin for AI-based image segmentation, colocalization and classification

napari-segmencolo

A napari plugin for AI-based image segmentation, with multichannel colocalization filtering, classification, and export (TIFF / Excel).

Developed during an internship in fluorescence imaging at the UCD Conway Institute (Dublin), with the help of AI.

---

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	TIFF + object counts (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 / counts

1. ④ Export 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
• pylibCZIrw — CZI reading (batch mode)

The Ilastik-style mode is implemented in-house (scikit-image + scikit-learn); it does not require an Ilastik installation. It is inspired by ilastik (Berg et al., 2019, GPL-2.0), but contains no ilastik code and does not depend on it — so ilastik's GPL license does not apply, and this plugin stays BSD-3.

Author

Lena PROUX — Internship at the Imaging Core, UCD Conway Institute (Dublin), supervised by Dr Scholz. Plugin developed during the internship, with the help of AI, for image segmentation and analysis.

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
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
• ilastik (inspiration for the Ilastik-style mode) — Berg, S., Kutra, D., Kroeger, T., et al. (2019). ilastik: interactive machine learning for (bio)image analysis. Nature Methods, 16, 1226–1232. https://doi.org/10.1038/s41592-019-0582-9

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.