A Julia package providing colocalization metrics for images and their sparse representations.

This package allows you to quickly run all metrics, and report the results both in image and CSV format.

Colocalization is used often in multichannel microscopy to quantify functional interaction between fluorescently marked proteins or subcellular organelles. Note that colocalization in superresolution microscopy has to be very carefully applied, as with increasing precision no two objects can share the same location at the same time.

CircleCI codecov DOI

Table of contents

  1. Installation

  2. Usage

    2.1 Supported Metrics

    2.2 Demo

    2.3 Documentation

  3. Cite

  4. FAQ

  5. Related projects and tools

  6. Can you support metric X?


Using as a package

Start Julia (in VSCode or Command line)


In Julia

using Pkg
# Optionally, activate your environment
# Pkg.activate("path/to/your/environment")
using Colocalization

Cloning the repository

This assumes you have Git installed and configured.

git clone
cd Colocalization.jl
julia --project=.

Then, in Julia:

using Pkg
using Colocalization

That's it.

On Command line

Let's say you have 2 image files a.tif and b.tif.

julia --project=. scripts/colocalize.jl -f a.tif -s b.tif --outdir . --segment -w 3


Supported Metrics

You can get an up to date listing of the supported metrics by running the following code:

using Colocalization, Logging
@info list_metrics()

or access the actual functions:

for (name, metric) in metrics_iterator()
  @info name, metric

In silico example

Let's create 2 objects with variable levels of fluorescence labelling, that overlap by 50%.

using Images, Statistics, Distributions, Colocalization, ImageFiltering, Random
X, Y = 100, 100
xs = zeros(X, Y)
ys = zeros(X, Y)
xs[40:50, 40:50] .= rand(11, 11)
ys[45:55, 45:55] .= rand(11, 11)
sx = ImageFiltering.imfilter(xs, ImageFiltering.Kernel.gaussian((3, 3)))
sy = ImageFiltering.imfilter(ys, ImageFiltering.Kernel.gaussian((3, 3)))

We'll add some noise to make things realistic

s2x = copy(sx)
s2y = copy(sy)
s2x .+= rand(100, 100) ./ 10
s2y .+= rand(100, 100) ./ 10

View the results

using SPECHT, ImageView
imshow(mosaicview( [SPECHT.tcolors([xs, ys]), SPECHT.tcolors([sx, sy]), SPECHT.tcolors([s2x, s2y])], nrow=1))

The visualzation snippet uses SPECHT and Imageview, if you don't have them:

using Pkg

This should produce something like this image


Now, we compute all coloc metrics

results = colocalize_all(s2x, s2y)

Let's view the results, the metrics from left to right are: spearman, m2, m1, jaccard, manders, sorensen, pearson

mv = mosaicview([abs.(results[k]) for k in keys(results)], nrow=1)


Clearly, the noise is throwing a wrench in things. Metrics like Jacard, M1 and so forth expect segmented images to work on. Let's do a quick segmentation.

xt = otsu_threshold(s2x)
yt = otsu_threshold(s2y)
s2x[s2x.<xt] .= 0
s2y[s2y.<yt] .= 1
results = colocalize_all(s2x, s2y)
mv = mosaicview([abs.(results[k]) for k in keys(results)], nrow=1)

Which should produce something like the below image. demo.png


The documentation of the functions describes proper usage and meaning of parameters, to access it:

using Colocalization

The ? key invokes Julia documentation, tools/IDES such as VSCode/Atom would have built in documentation panes.


If you find this useful, consider citing:

  author       = {Ben Cardoen},
  title        = {Colocalization.jl},
  month        = jan,
  year         = 2023,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.7552357},
  url          = {}

Note For the individual metrics, please cite the introducing author!!!.


  • To display the images, you need to install ImageView
using Pkg

If you have any problems or suggestions, please create an issue


This package would not be possible without the Julia Images ecosystem

Can you support Metric X?

Sure, please create an issue describing the metric mathematically, ideally accompanied by the introducing paper.