\n\n# napari-colocalization\n\n[](https://github.com/DBI-INFRA/napari-colocalization/raw/main/LICENSE)\n[](https://pypi.org/project/napari-colocalization)\n[](https://python.org)\n[](https://github.com/DBI-INFRA/napari-colocalization/actions)\n[](https://codecov.io/gh/DBI-INFRA/napari-colocalization)\n[](https://napari-hub.org/plugins/napari-colocalization)\n[](https://napari.org/stable/plugins/index.html)\n\n> ⚠️ **Under construction - pre-alpha.** APIs, UI, and outputs may change\n> without notice. Not recommended for production analysis yet; use at your\n> own risk and please report rough edges via the\n> [issue tracker](https://github.com/DBI-INFRA/napari-colocalization/issues).\n\nInteractive intensity-colocalization analysis for [napari](https://napari.org).\nPick two channels (or one multi-channel image), optionally restrict the\nanalysis to a region drawn as shapes or labels, choose your metric, and get a\nresults table plus an intensity-vs-intensity density plot.\n\n
\n \n
\n\n## Features\n\n- **Five colocalization metrics**, spanning both families: three of\n *correlation* — Pearson (PCC), Spearman rank (SRCC) and Li's Intensity\n Correlation Quotient (ICQ) — and two of *co-occurrence* — Manders'\n overlap coefficient with split coefficients (r, k1, k2) and Manders'\n thresholded coefficients tM1/tM2.\n- **Pairwise or all-to-all** mode: analyse two grayscale layers, or every\n channel pair within a single multi-channel layer.\n- **2D and 3D** support natively (no time-series for now).\n- **Region-restricted analysis** via a Shapes or Labels layer - each non-zero\n region is reported on its own row.\n- **Manders thresholds**: choose **Costes auto** (orthogonal-regression\n bisection, matched to Fiji Coloc 2), a per-channel **auto-threshold**\n (Otsu, Li, Triangle, Yen, Mean, IsoData → thresholded tM1/tM2), or **Manual**.\n- **Per-Z-slice mode**: analyse each plane of a stack separately (one row\n per slice), à la JACoP B's \"consider Z slices separately\".\n- **Interactive results**: in-widget table, density plot of the selected row,\n multi-row selection that highlights all matching shapes/labels in the viewer,\n and an optional **fixed-axes** cytofluorogram for comparable plots.\n- **Diagnostics tab**: single-pair diagnostic plots - Costes randomization\n significance test (observed PCC vs a scrambled null, with p-value/z-score),\n Van Steensel cross-correlation function (CCF), and Li intensity correlation\n analysis (ICA).\n- **Object-based tab**: compare segmented objects (from Labels layers or by\n thresholding) - centre-particle coincidence and object overlap per object,\n with centroid Points and nearest-neighbour Vectors drawn into the viewer.\n- **Outputs to the viewer**: add the colocalized-pixel mask (selected row) as\n a Labels layer, or a block-scrambled example as an Image layer.\n- **CSV export** of the current table, plus **figure export** of the\n density plot (PNG / PDF / SVG / TIFF, configurable size and DPI).\n\n## Installation\n\n```bash\npip install napari-colocalization\n```\n\nIf napari isn't already installed, install both at once:\n\n```bash\npip install \"napari-colocalization[all]\"\n```\n\nFor the latest development version:\n\n```bash\npip install git+https://github.com/DBI-INFRA/napari-colocalization.git\n```\n\n## Quick start\n\n1. Launch napari.\n2. Load sample data: **File → Open Sample → napari-colocalization →\n Colocalization sample (2D)**. A 3D synthetic sample and **CBS006RBM**\n (a two-channel benchmark image from the\n [Colocalization Benchmark Source](https://colocalization-benchmark.com))\n are also provided.\n\n
\n \n
\n\n3. Open the widget: **Plugins → Colocalization Analysis**. Two image layers\n `channel_a` and `channel_b` are auto-selected for pairwise mode.\n\n4. Click **Run**. The results table populates with a single row (the whole\n image), and the density plot below shows the intensity pairs with the\n metric values overlaid.\n\n
\n \n
\n\n5. *(Optional)* Add a Shapes layer, draw a few rectangles or polygons, set\n **Region** to *Shapes* and pick the layer. Re-run - the table now has one\n row per shape, and clicking a row highlights the matching shape in the\n viewer.\n\n
\n \n
\n\nSee [docs/usage.md](docs/usage.md) for the full walkthrough.\n\n## Diagnostics\n\nThe **Diagnostics** tab runs single-pair diagnostic plots that go beyond a\nsingle number per region: the **Costes randomization** significance test (the\nobserved PCC against a block-scrambled null, with a p-value and z-score), the\n**Van Steensel** cross-correlation function, and **Li's intensity correlation\nanalysis**.\n\n
\n \n
\n\n## Object-based analysis\n\nThe **Object-based** tab compares segmented *objects* between the two channels:\n**centre-particle coincidence** (does an object's centroid fall inside an\nobject of the other channel?) and **object overlap**, with one row per object.\nObjects come from existing Labels layers or by thresholding, and the detected\ncentroids and nearest-neighbour links are drawn back into the viewer as Points\nand Vectors.\n\n
\n \n
\n\n## Documentation\n\n- **[Usage guide](docs/usage.md)** - every control in the widget, in order.\n- **[Metrics](docs/metrics.md)** - what PCC, SRCC, ICQ, the overlap\n coefficient and Manders (tM1/tM2) mean, co-occurrence versus correlation,\n and how the Costes auto-threshold works.\n- **[Python API](docs/api.md)** - calling the pure-compute layer\n (`pearson`, `spearman`, `li_icq`, `manders`, `overlap`,\n `costes_threshold`, `costes_regression`, `analyse_pairwise`,\n `analyse_all_to_all`) from scripts or notebooks.\n\n## Related projects\n\n- [Coloc 2](https://imagej.net/plugins/coloc-2) - the reference ImageJ\n colocalization plugin; this plugin follows it in spirit, and the Costes\n auto-threshold here is matched to its implementation.\n- [JACoP](https://imagej.net/plugins/jacop) - \"Just Another Colocalization\n Plugin\" (Bolte & Cordelières, 2006); the inspiration for the diagnostics\n (Van Steensel CCF, Li ICA, Costes randomization) and the object-based\n analysis.\n- [ijp-jacop-b](https://github.com/BIOP/ijp-jacop-b) - the BIOP fork of JACoP;\n inspired the per-channel auto-thresholds, per-Z-slice mode and the\n layers written back to the viewer.\n- [scikit-image colocalization metrics](https://scikit-image.org/docs/stable/auto_examples/applications/plot_colocalization_metrics.html):\n the underlying implementations of PCC and Manders.\n\n## Contributing\n\nContributions are welcome. Run the test suite with:\n\n```bash\npip install -e . --group dev\npython -m pytest tests/ -v\n```\n\nPre-commit hooks (ruff lint + format, napari-plugin-checks) ship with the\nrepo:\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\nPlease keep test coverage at or above the current level when submitting a PR.\n\n## License\n\nDistributed under the terms of the [MIT](http://opensource.org/licenses/MIT)\nlicence; `napari-colocalization` is free and open-source software.\n\n## Issues\n\nFound a bug or have a feature request? Please\n[open an issue](https://github.com/DBI-INFRA/napari-colocalization/issues).\n","description_content_type":"text/markdown","keywords":null,"home_page":null,"download_url":null,"author":"Jesko Wagner","author_email":"35219306+jeskowagner@users.noreply.github.com","maintainer":null,"maintainer_email":null,"license":null,"classifier":["Development Status :: 2 - Pre-Alpha","Framework :: napari","Intended Audience :: Developers","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["numpy","magicgui","qtpy","scikit-image","scipy","matplotlib","napari[all]; extra == \"all\""],"requires_python":">=3.10","requires_external":null,"project_url":["Bug Tracker, https://github.com/dbi-infra/napari-colocalization/issues","Documentation, https://github.com/dbi-infra/napari-colocalization#README.md","Source Code, https://github.com/dbi-infra/napari-colocalization","User Support, https://github.com/dbi-infra/napari-colocalization/issues"],"provides_extra":["all"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}
![\"napari-colocalization](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/logo.png\"){kind=logo}
\n![\"napari-colocalization](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/widget_overview.png\")
\n![\"Open](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/quickstart_sample.png\")
\n ![\"napari-colocalization](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/widget_shapes.png\")
\n![\"Diagnostics](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/widget_diagnostics.png\")
\n![\"Object-based](\"https://raw.githubusercontent.com/DBI-INFRA/napari-colocalization/main/docs/img/widget_objects.png\")
\n