Metadata-Version: 2.4
Name: napari-segmencolo
Version: 0.1.1
Summary: performs image segmentation by leveraging the colocalization of multiple fluorescence channels
Author-email: Lena PROUX <lena.proux@gmail.com>
License-Expression: BSD-3-Clause
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: magicgui
Requires-Dist: qtpy
Requires-Dist: scikit-image
Requires-Dist: napari
Requires-Dist: stardist
Requires-Dist: cellpose
Requires-Dist: scikit-learn
Requires-Dist: pandas
Requires-Dist: tifffile
Requires-Dist: openpyxl
Requires-Dist: pylibCZIrw
Provides-Extra: all
Requires-Dist: napari[all]; extra == "all"
Dynamic: license-file

# napari-segmencolo

[![License BSD-3](https://img.shields.io/pypi/l/napari-segmencolo.svg?color=green)](https://github.com/lenaproux-cyber/napari-segmencolo/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/napari-segmencolo.svg?color=green)](https://pypi.org/project/napari-segmencolo)
[![Python Version](https://img.shields.io/pypi/pyversions/napari-segmencolo.svg?color=green)](https://python.org)
[![tests](https://github.com/lenaproux-cyber/napari-segmencolo/workflows/tests/badge.svg)](https://github.com/lenaproux-cyber/napari-segmencolo/actions)
[![codecov](https://codecov.io/gh/lenaproux-cyber/napari-segmencolo/branch/main/graph/badge.svg)](https://codecov.io/gh/lenaproux-cyber/napari-segmencolo)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-segmencolo)](https://napari-hub.org/plugins/napari-segmencolo)
[![npe2](https://img.shields.io/badge/plugin-npe2-blue?link=https://napari.org/stable/plugins/index.html)](https://napari.org/stable/plugins/index.html)
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-purple.json)](https://github.com/copier-org/copier)

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

> Developed during an internship in fluorescence imaging, with the help of AI, for image segmentation and analysis.

----------------------------------

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]:

```bash
pip install napari-segmencolo
```

To install together with napari and a Qt backend:

```bash
pip install "napari-segmencolo[all]"
```

For development (from a local clone):

```bash
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](https://www.ilastik.org) (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** — Imaging internship.
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](https://napari.org) | Image viewer & plugin framework | BSD-3-Clause |
| [StarDist](https://github.com/stardist/stardist) | Nucleus segmentation | BSD-3-Clause |
| [Cellpose](https://cellpose.readthedocs.io) | Cell / nucleus segmentation | BSD-3-Clause |
| [scikit-image](https://scikit-image.org) | Image processing & object features | BSD-3-Clause |
| [scikit-learn](https://scikit-learn.org) | KMeans, RandomForest | BSD-3-Clause |
| [pandas](https://pandas.pydata.org) / [NumPy](https://numpy.org) | Tables & arrays | BSD-3-Clause |
| [tifffile](https://github.com/cgohlke/tifffile) | TIFF export | BSD-3-Clause |
| [openpyxl](https://openpyxl.readthedocs.io) | Excel export | MIT |
| [qtpy](https://github.com/spyder-ide/qtpy) | Qt binding abstraction | MIT |
| [pylibCZIrw](https://github.com/ZEISS/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.

[napari]: https://github.com/napari/napari
[copier]: https://copier.readthedocs.io/en/stable/
[MIT]: http://opensource.org/licenses/MIT
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
[napari-plugin-template]: https://github.com/napari/napari-plugin-template
[file an issue]: https://github.com/lenaproux-cyber/napari-segmencolo/issues
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
