Colocalization

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.

Table of contents

1. Installation

2. Usage

   2.0 Point Clouds

   2.0 Voxel based data

   2.1 [Supported Metrics](#metrics)
   
   2.2 [Demo](#demo)
   
   2.3 [Documentation](#docs)
   

3. Cite

4. FAQ

5. Related projects and tools

6. Can you support metric X?

Installation

• Download Julia
• Julia + VSCode
• Open a new VSCode window
• In the terminal, type git clone https://github.com/bencardoen/Colocalization.jl.git
• change directory to Colocalization.jl which will now be a subdirectory ### Using as a package Start Julia (in VSCode or Command line) bash julia In Julia julia using Pkg # Optionally, activate your environment # Pkg.activate("path/to/your/environment") Pkg.add(url="https://github.com/bencardoen/Colocalization.jl") using Colocalization

Cloning the repository

This assumes you have Git installed and configured. bash git clone https://github.com/bencardoen/Colocalization.jl.git cd Colocalization.jl julia --project=. Then, in Julia: julia using Pkg Pkg.instantiate() 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

Usage

Point cloud

julia julia --project=. scripts/colocalize_pointcloud.jl --first 1st.mat --second 2nd.mat --outdir "X" This reads in SuperResNet files (MAT format) of two channels, 3D localizations. The output will be a CSV file where each row describes the colocalization of 1 cluster in channel x to 5 clusters to channel y. The columns are: - channel: e.g. 1, 2 - channel name: the corresponding filename - clusterid : this is the integer identifier used for this cluster in SRN - centroid{x,y,z} : the centroid location of this cluster - distance{1-5} : The distances to the nearest 5 objects in the other channel - nearest{1-5} : The cluster ids to the nearest 5 objects in the other channel - channelcentroid{x,y,z} : The centroid of this channel - distancetocentroid: the distance of this object's centroid to the channel's centroid (~ density/topology) - radius: This is the radius of the circumscribed sphere of this cluster. If, for two clusters, you have R1 and R2 as radii, and their centroid to centroid distance is D12, then you can detect overlap = D12 < R1 + R2. This is an approximate measure, as the cluster can have weird shapes that skew the size of the circumscribed circle. - interactionfactor: let a, b be the nearest objects in channel 1, 2, then this is distance(a,b) / sum(radiusa, radiusb) - x{1..30}: The features computed by SRN for each blob

In addition, VTU files, which you can open with Paraview, are saved. - channel{1,2}clusterx.vtu : The x'th cluster (check the CSV file) - channel{12}interactingclusterx.vtu: The x'th cluster interacting with the other channel (see interaction factor) - channel{1,2}interacting : all interacting localiztion points. - channel{1,2}all : all the raw localiztion points.

Processing folders of paired files

bash julia --project=. scripts/colocalize_pointcloud.jl --patternmatch <inputdir> --outdir <somedir> If you have files that need to be paired, e.g. a single directory with paired mat files, you can use pattern matching to process all files. Currently this supports the following pattern: CavPTRF_1_1_[A-Z, a-z]+_[0-9]+_merged_threshold_[0-9]+_alpha_[0-9]+.mat

• [A-Z, a-z]+ matches alphabetic sequences (e.g. PTRF)
• [0-9]+ matches one or more numbers, e.g. 1, 23, 09 etc.

For example, to only match files with threshold 10 you'd do julia --project=. scripts/colocalize_pointcloud.jl --patternmatch <indir> --outdir <outdir> --pattern "CavPTRF_1_1_[A-Z, a-z]+_[0-9]+_merged_threshold_10_alpha_[0-9]+.mat"

Output will be saved by the values after threshold and alpha, e.g. outdir/9_10/... for threshold 9 alpha 10

SRN Specific data

You can extract specific fields from the SRN MAT file. Start julia bash julia --project=. Then, for example to read the 3D points of the clusters, you can do

julia using Colocalization data = load_SRN("file.mat") points = data[4] CSV.write("3D-points.csv", DataFrame(points, ["X", "Y", "Z"]))

You can also read the MAT file directly: ```julia s="example.mat" ss=matread(s)

Print the variables

for k in keys(ss) @info k end

Print the dimensions

@info size(ss["nodeDeg"]) data = ss["nodeDeg"] using DataFrames using CSV

Create a dataframe

df=DataFrame(data, :auto)

Write to CSV

CSV.write("example.csv", df) ```

Voxel

Supported Metrics

You can get an up to date listing of the supported metrics by running the following code: julia using Colocalization, Logging @info list_metrics() or access the actual functions: julia for (name, metric) in metrics_iterator() @info name, metric end

In silico example

Let's create 2 objects with variable levels of fluorescence labelling, that overlap by 50%. julia 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 julia s2x = copy(sx) s2y = copy(sy) s2x .+= rand(100, 100) ./ 10 s2y .+= rand(100, 100) ./ 10 View the results julia 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: julia using Pkg Pkg.add("ImageView") Pkg.add(url="https//github.com/bencardoen/SPECHT.jl")

This should produce something like this image

Now, we compute all coloc metrics julia 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) imshow(mv)

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. julia 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) imshow(mv) Which should produce something like the below image.

Documentation

The documentation of the functions describes proper usage and meaning of parameters, to access it: julia using Colocalization ?colocalize_all The ? key invokes Julia documentation, tools/IDES such as VSCode/Atom would have built in documentation panes.

Cite

If you find this useful, consider citing: bibtext @software{ben_cardoen_2023_7552357, author = {Ben Cardoen}, title = {Colocalization.jl}, month = jan, year = 2023, publisher = {Zenodo}, doi = {10.5281/zenodo.7552357}, url = {https://doi.org/10.5281/zenodo.7552357} }

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

FAQ

• To display the images, you need to install ImageView julia using Pkg Pkg.add("ImageView") If you have any problems or suggestions, please create an issue

Related software

FiJi: - https://imagej.net/plugins/coloc-2 - https://github.com/fiji/Colocalisation_Analysis

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.