Sovereign 8s.is mirror of standardgalactic/napari-cell-gater
  • Jupyter Notebook 67.5%
  • YAML 27.3%
  • Python 5.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jose Nimo 2cf473a5d6
Some checks failed
Test and Deploy / macos-latest py3.10 (push) Has been cancelled
Test and Deploy / macos-latest py3.11 (push) Has been cancelled
Test and Deploy / macos-latest py3.12 (push) Has been cancelled
Test and Deploy / ubuntu-latest py3.10 (push) Has been cancelled
Test and Deploy / ubuntu-latest py3.11 (push) Has been cancelled
Test and Deploy / ubuntu-latest py3.12 (push) Has been cancelled
Test and Deploy / windows-latest py3.10 (push) Has been cancelled
Test and Deploy / windows-latest py3.11 (push) Has been cancelled
Test and Deploy / windows-latest py3.12 (push) Has been cancelled
Test and Deploy / deploy (push) Has been cancelled
Merge pull request #39 from josenimo/docs/paper-ready
point docs at CosciaLab, rewrite README
2026-09-15 09:34:48 +02:00
.github/workflows run pytest in CI instead of missing tox 2026-09-15 08:45:04 +02:00
.napari-hub point docs at CosciaLab, rewrite README 2026-09-15 08:43:16 +02:00
docs point docs at CosciaLab, rewrite README 2026-09-15 08:43:16 +02:00
old_files restructure to pixi pyproject.toml 2025-07-11 12:03:50 +02:00
src/cell_gater add PyPI metadata, bump 0.5.2 2026-09-15 08:41:06 +02:00
tests adapted tests, and passing 2025-07-14 11:29:03 +02:00
tracebacks fixed channel indexing 2024-07-19 17:49:34 +02:00
.gitattributes restructure to pixi pyproject.toml 2025-07-11 12:03:50 +02:00
.gitignore restructure to pixi pyproject.toml 2025-07-11 12:03:50 +02:00
gates_example.csv ignore csv files that start with "." 2024-04-16 11:50:47 +02:00
LICENSE initial commit 2024-03-11 10:13:53 +01:00
MANIFEST.in initial commit 2024-03-11 10:13:53 +01:00
pixi.lock bump to 0.5.1 2025-07-14 12:58:34 +02:00
pyproject.toml add PyPI metadata, bump 0.5.2 2026-09-15 08:41:06 +02:00
README.md point docs at CosciaLab, rewrite README 2026-09-15 08:43:16 +02:00

napari-cell-gater

License BSD-3 PyPI Python Version tests codecov

A napari plugin to perform cell marker gating for multiplexed immunofluorescent imaging.

napari-cell-gater is part of the openDVP ecosystem (documentation). Use it to pick, per sample and per marker, the intensity threshold that separates positive from negative cells — while looking at the image, the segmentation mask and the intensity distribution side by side.

Visual workflow of napari-cell-gater


Installation

napari-cell-gater needs Python 3.10–3.12 and a working napari installation (see the napari installation guide).

We recommend a fresh environment:

conda create -n cell-gater python=3.11
conda activate cell-gater
pip install "napari[all]"
pip install napari-cell-gater

or, with uv:

uv venv --python 3.11 && source .venv/bin/activate
uv pip install "napari[all]" napari-cell-gater

To get the latest unreleased changes instead:

pip install git+https://github.com/CosciaLab/napari-cell-gater.git@main

Then launch napari and open the plugin from Plugins → napari-cell-gater.

Inputs

You need three directories — images, segmentation masks and quantifications — with one file per sample:

Directory File per sample Notes
images 1.ome.tif or 1.tif channel order must match the marker columns of the quantification csv
masks 1.tif label image; large masks can be slow to load
quantifications 1.csv one row per cell, one column per marker, plus morphology columns

Assumptions:

  • Files are named after the sample (1, 2, … or any shared stem), and the same stem is used in all three directories.
  • Every sample must be present in all three directories.
  • Any extra file in those directories can make the plugin fail — keep them clean.

A ready-to-run example dataset ships with the repository under tests/test_data/ — 5 samples as imgs/{1..5}.ome.tif, segs/{1..5}.tif and quants/{1..5}.csv. Point the plugin at those three folders to try it out without preparing your own data.

Output

Gates are written to a csv with one row per sample/marker pair — see gates_example.csv:

sample_id,marker_id,gate_value
68,Rabbit IgG,3478.531304347826
68,Goat IgG,0.0

Gate values are always saved in linear space, even when plotting in log10. The same file can be read back with Load existing gates.

How to use

  1. Load your three directories with Load quantifications dir, Load image dir and Load mask dir. Optionally use Opt: Load channel map to supply an explicit channel-to-marker mapping.
  2. Set Select lowerbound marker column and Select upperbound marker column to the first and last quantification columns you want to gate. Pick the same bounds every session if you plan to save and reload gates.
  3. Optionally adjust Remove markers with prefix (default DNA, DAPI) to drop nuclear channels from the marker list.
  4. Click Validate input. On success the gating controls appear; on failure fix the inputs and validate again.
  5. Choose a sample and a marker from the dropdowns. Three layers load: the reference channel (Select reference channel), the segmentation mask, and the channel being gated. A plot of marker intensity (x) against Choose Y-axis (default Area) appears, with a slider underneath whose position is drawn as a vertical line.
  6. Tune the view: switch Plot type to Hexbin for dense clusters, and Logarithmic scale to Yes to plot in log10 (often easier to read). Adjust image contrast from the napari layer controls at the top left.
  7. Drag the slider to the threshold you think is correct, or type a value into Manual gate input and click Set gate manually.
  8. Click Plot Points to overlay the cells the current gate calls positive.
  9. Repeat steps 6–8 until you are satisfied, then click Save Gate. The first save asks where to write the gates csv; later saves reuse that path. Go back to step 5 for the next marker or sample.

Contributing

Contributions are very welcome. To set up a development install:

git clone https://github.com/CosciaLab/napari-cell-gater.git
cd napari-cell-gater
pip install -e ".[dev]"
pytest

Please ensure test coverage at least stays the same before you submit a pull request.

Citation

napari-cell-gater is developed as part of the openDVP ecosystem. Until the paper is out, please cite this repository and the openDVP documentation at https://coscialab.github.io/openDVP/.

License

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

Issues

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