Coloc 2

Revision as of 04:13, 28 July 2015 by White (talk | contribs) (To Do List: add buig about y intercept too high warning when actually is too low (negative))
Coloc 2 - Standardized, modular, Pixel Intensity Correlation over Space Based Colocalization analysis. (ImageJ - Fiji - ImgLib)
Author Daniel J. White, Tom Kazimiers, Johannes Schindelin
Maintainer Daniel J. White
File Colocalisation_Analysis.jar
Source on GitHub
Latest version 2014
Development status Beta. Under development, but stable enough for real work. Refinements to GUI and output under development.
Website Fiji

What is Coloc 2

Coloc 2 is Fiji's plugin for colocalization analysis. It implements and performs the pixel intensity correlation over space methods of Pearson, Manders, Costes, Li and more, for scatterplots, analysis, automatic thresholding and statistical significance testing.

There are many nuances and pitfalls to colocalization analysis. As such, we strongly recommend you read the Colocalization Analysis section of Fiji's Cookbook before attempting to use Coloc 2!

How to use Coloc 2

  • Open images to analyze.
    • You need a 2 color channel image. If the image has more than 2 channels, identify the two you want to analyze with each other, then split the channels into separate images (Image- Color - Split Channels)
  • If you want to analyze only some region of interest (ROI), there are 2 ways to do that:
    • Select a region of interest with one of the ImageJ selection tools, in one of the images.
      • If the image is a z stack, then the ROI applies in all "slices" of the stack.
    • You can have a third "binary mask" image, with the same x,y,z dimensions as the 2 images to be analyzed:
      • where the mask image is white (255 pixel value for an 8 bit greyscale image) colocalization will be analyzed for those pixels only. Where it is black (zero pixel value), the pixels will be ignored: not included in the analysis.
      • you can use a z stack as a 3D mask... it's up to you how you make that mask image, manually or by some automated method.
  • Launch the Coloc 2 plugin from the menu item: Analyze - Colocalization Analysis - Coloc 2
    • or use the command finder: press L then start typing Coloc, then choose the plugin with the arrow keys and hit enter, or double mouse click it to launch the plugin.
  • In the plugin's graphical user interface (GUI) choose the 2 images you want to analyze in the first 2 drop down lists.
    • Select the images according to which you want to be channel 1 and which to be channel 2.
    • In the third drop down list selection, select the image/channel you want to use that has the correct ROI
      • or you can choose a mask image - it must have the same xyz dimensions (number of pixels and slices) as the other 2 images.
  • Choose which "Algorithms" are run and which statistics you wish to calculate, and if you want to save the "standardized" PDF result file, when the OK button is pressed.
    • Numerical results and image names are dumped into the ImageJ Log window as comma separated values, so you can copy paste, or save the log window contents, to then import them into whatever statistical package or spreadsheet you will need to analyse the results in.
    • Turn the options on and off by clicking the selection button at the left of the Algorithm description
    • Also choose the approximate size of the point spread function (PSF) in your images, and the number of iterations to run the Costes statistical significance test (We suggest a large number... the larger the number the longer the analysis will take. Do, at the very very least, 10 iterations (100 would be better).
      • You should know approximately how big the PSF is (in pixels) in your images.
        • If you dont, go back and read about what it is and why it's important in colocalization analysis (for instance read the Costes paper )
        • This size determines what size of image chunks are shuffled in the randomization process. PSF sized image pieces make physical sense, as that's the size of the smallest objects in the image.
  • Click OK to run the analysis.
    • You will be asked if you want to save the results as a PDF file (if the Show "save PDF" dialog button was checked. So tell it where to save the PDF. This is standard output format, so you can compare with your friend, same vs. same.
      • Feel free to tell us what things you think should be included in this standardized PDF output file.

Pitfalls of the Manders and Costes methods

The auto threshold calculation method can fail if fed inappropriate information

That means it does not like images with high offset / high flat background, which adds a constant number to the "real proportional" intensity relationship to the "concentration" of the dye. If pixels that contain no real signal have large intensity values, the algorithm has no way of knowing that, and can reach a result for the thresholds where one or both of them is below the value of the lowest intensity value present in that channels of the image. This means that ALL of that channel's pixels are considered to be colocalised, then the Manders Coefficients that you get will reflect that aberrant situation. In these cases, the background / offset should be carefully removed/subtracted before running the Colocalization Threshold plugin. The images below are an example of this situation, using the badly behaved data set: 150707_WTstack.lsm. Note that the vaules for M1 and tM1 are the same! This should not be the case. You can see the green channel threshold is wrongly set below the intensity where the image data actually starts.


Effect of noise on Manders coefficients

In the case of perfect colocalisation, where the intensities of the 2 channels are always the same: Low red with low green, and high green with high red, the scatterplot would have all the data point falling on a straight diagonal line, since the green intensity would always bee the same as that of the red! however, that is the ideal case and real biological data is noisy! Noise (be it from the dyes not staining every single molecule, or from statistical photon shot noise from recording the signal from too few photons, or from other noise sources) will cause the pixel intensities to deviate from the perfect case, to be lower or higher than they really are on average. This causes scatter in the distribution of the data point in the scatterplot perpendicular to the line of regression fit. So you can see the noise by looking at how spread or tight the scatterplot points are. Also, since Manders coefficients are measuring correlation, and noise lowers the similarity of two identical signals, noise lowers the Manders coefficients to less than they should be for an image with very low noise. So for the same object under the microscope, a nosier images will appear to give less colocalisation than a clean low noise image. That means you cant compare different images with different signal:noise levels, unless you have some way of estimating the noise and correcting for it.

Fluorescence emission bleed through looks like perfect colocalization

As is often true for DAPI nuclear stain and GFP dye pairs, when images are captured at the same time, with both dyes being excited and detected simultaneously, fluorescence emission bleed through gives misleading results, as the signal from the DAPI also appears also in the GFP detection channel! Where there is more DAPI, there is also more signal in the GFP channel. This looks like really good colocalisation, but of course it is totally false! It is a problem with the imaging systems not being set up correctly or not used correctly. This can also happen with many other dye combinations, if they have overlapping emission spectra. Always check your spectra. You can do that here: Invitrogen Fluorescent Dye Spectra Viewer]. To be safe, check your emission filter sets don't allow in the wrong signal, and do "sequential imaging", so you only excite and image one dye at a time.


Regions of interest (ROIs)

Whether or not to consider zero - zero pixels as part of the interesting data for the algorithms to deal with. If you think about it, in a fluorescence image there is typically quite a large area which is black in both channels. For instance where there is space between cells, or just no signal in either channel since that area is not part of an interesting area of the sample. A philosophical point but a significant one: Why bother taking images of black areas? Why bother analyzing black areas for colocalisation? Surely you are not interested in those regions, as they contain no information of use to you? If you perform these pixel intensity correlation methods and include zero zero pixels, then of course these pixels have a very high correlation! They have the same value. But they are totally uninteresting! Sure, the auto threshold method excludes them from the tM1 and tM2 figures, but why include them in the first place? Probably better not to include them unless there is a good reason to do that. Why not just image the area, or just analyze the area where your biology is happening? If you analyse an image with large areas of close to zero and zero intensities, then the autothreshold method will tend to lower the thresholds to include more of that non interesting background. If you image the same sample, but only image a patch of the interesting part, say cytoplasm, then the autothreshold will probably give higher thresholds, and exclude more non interesting background, so the thresholded Manders coefficients will better reflect the biologically interesting parts of the image data - right? You can analyze only a region of interest by making an ROI then selecting the use ROI option in the plugin. You can use a regular shape (rectangle or ellipse) or even a freehand ROI to manually select the interesting part of the image and ignore the part you know is background. Yes, this is a subjective decision, so be careful! You can see in the following example screenshot that for the same misbehaving data set, using an ROI which roughly gets just the cell, the thresholds were calculated properly and the tM1 and tM2 are sensible and lower then 1.00:


Other pitfalls

Please see the Colocalization Analysis page for further discussion of precautions.

To Do List

0. Old to do list and design notes are found here: Coloc_2_designNotes

1. Add Tests and implementation for %Colocalization by intensity and pixels(or voxels) wrt each channel, as per the depreciated Colocalization Threshold plugin - force use of a ROI or mask, as only then do these measures make sense. Add docs for this.

2. numerical results and image stats are currently spewed into the IJ.log window. This is done separately from the way results are put into the simple results display window or the PDF output. So there three differently formatted results outputs with different stuff in them. Different ResultsHandler implementations like PDF or Simple can and do show a different selection of results. This is over complicated, so it should be made into one thing, that outputs the same numerical results and stats values, in the same order in all ResultsHander implementations ( GUI display and PDF output, and also the IJ.log. Can reuse the ValueResults class for all three by doing the same thing in each ".

3. Missing Feature: On the 2D histogram in the PDF, the regression line is absent

4. Missing Feature: auto threshold results lines are missing from the 2D histogram in the simple display results GUI and the PDF.

5. implement flags in GUI to turn on and off desired output values??? Or does this break the idea of having a standardized output? Perhaps instead just make sure the IJ.log output is easily parse-able by humans and machines.

6. Bug: Large images don't fit in results display gui, and there are no scroll bars.

7. Enable use multi-channel images as well as the current 2 images (one channel each) plus 1 mask image selection. Need to choose which images in the multi-channel images if there are more than 2.... or even which 2 channels and which mask images, if the multi-channel image contains 3 or more channels. This avoids the user having to run split channels. Ease of use.

8. Change channel naming convention in output using imagename1 and imagename2 to use imagename1(Ch1) and imagename2(Ch2), so its clear which is ch2 and ch2

9. Running as imageJ macro command fails because of the parameter: show_"save_pdf"_dialog. Probably the "" are messing up the run(Coloc_2, "params"); text string parameters. So need to escape out or get ris of the "" around save_pdf... what are they there?

10. Running as macro need a method / GUI parameter to make the PDF file output saved without user interaction.

11. Running as macro command in a loop, need to use macro commands to save the IJ.log window results, then clear the log window before the next set of results are sent there. Add words to documentation to explain that.

12. trivial bug: if 2D histogram regression finds a y intercept that is below zero it gives the too high warning "Warning! y-intercept high - The absolute y-intercept of the auto threshold regression line is high. Maybe you should use a ROI, maybe do a background subtraction in both channels" So should change warning text to too high or too low depending on if its positive or negative.


1. implement test and implement code to make sure autothreshold results are the same regardless of image channel order - in Coloc_2 plugin version 2.0.2?