Straightlab Image Analysis Tools

Installation - Running - Using - Troubleshooting

A precompiled application package is provided (Intel 64 bit architecture only). Simply copy the package to your local disk and double click to begin.

If you wish to compile from source, follow the instructions for linux.

Compilation from source is handled by the Apache Ant utility (freely available at http://ant.apache.org ) with the cpptasks module (http://ant-contrib.sourceforge.net/cpptasks), which is included in the source archive, for compiling native code. Unarchive the source, navigate to the base directory, and run:

ant -Dbits=64 -lib cpptasks.jar install

If you wish to compile for a 32 bit architecture, substitute -Dbits=32.

Compilation requires java (development kit) 1.5 or later, as well as a C++ compiler, and has only been tested with Sun java and gcc. Standard search locations for these are included in the ant build.xml file. If ant or the c++ compiler complains that it cannot find headers for the java native interface (jni.h, for instance), you may need to adjust these paths. Add a tag for your path with the others in the build.xml file with the appropriate path to your headers substituted:

<sysincludepath path="/path/to/jni/headers"/>

Follow the linux instructions to compile. This has only been tested with the MinGW C++ compiler and Sun java. You will probably need to add the line:

<linkerarg value="--kill-at"/>

with the other linker argments in build.xml in order to prevent a problem with differences in compiler name mangling.

The compilation process will create a library from the C++ code in the dist subdirectory. This needs to be named "CAnalysisInterface.dll". The MinGW version I tested with names this "libCAnalysisInterface.so"; if this is the case for you, this file needs to be renamed appropriately.

You may also need to add change the path to your java native interface headers as described in the linux instructions.

java -Djava.library.path=. -Xmx500M -jar AnalysisToolsInterface.jar

(The 500MB memory size requested here is more than the amount of memory required, but the program will likely require more than the default amount allowed; set this to whatever workable amount you want.)

This will load the graphical user interface. It is also possible to run the methods from the command line; this can be done according to the instructions in the Image Analysis and Benchmarking package README at http://straightlab.stanford.edu/software.

When you start the application, there is a drop-down box of four options: "Find, quantify, and group centromeres in multiple channels", "Segment and Quantify Images", "Make Maximum Intensity Projections", and "Deschmutzerize".

All options process greyscale tiff images or metamorph stack images (extensions .tif or .stk).

Find, Quantify, and Group Centromeres

This is the centromere finding and quantification utility used in Moree, Meyer, et al. (2010). This utility processes only single-plane images (we commonly use maximum intensity projections of multi-plane images).

When you select this option, a box pops up with several option:

Type the directory of images you want to process in the "Directory to Process" box or select the choose button to open up a file chooser dialog box. (Note that if you use the file chooser pop-up you must choose the directory item itself, not something in the directory, or it won't find your files.)

The minimum area and maximum area parameters allow you to tune the size of centromeres (in pixels) for varying species/imaging conditions. For Xenopus and Human centromeres imaged using a 60x objective, we have found that 5 and 50 work well.

The four boxes labeled "Centromere Marker Channel", "Channels to Quantify", and "Other Channel to Quantify" let you specify what the different color channels you want to quantify are called. The program requires a specific naming convention: all images of the same field in different channels that you want to quantify together must be named exactly the same, except for the channel names entered in these boxes. For example, if you have an image taken using 488 nm illumination and another using 568 nm illumination and you used 488 and 568 as the channel identifiers, and named the 488 nm image "20100812_coverslip_01_488.tif", the 568 image would need to be named "20100812_coverslip_01_568.tif". This naming is case-sensitive on some machines. If the program crashes with (perhaps cryptic) explanation, double checking the naming of your files is probably the first thing to try.

The "Centromere Marker Channel" box specifies the channel that the program will use to find the centromeres. The "Channels to Quantify" are other image channels that you want measured. These boxes must be filled even if you don't have enough channels; it's ok to duplicate a channel name if you don't have enough. The "Other Channel to Quantify" box denotes an optional fourth channel; leave it blank if you don't want to use it.

The "Cluster Centromeres Into Cell Groups" option will determine whether the program treats all centromeres in an image as individuals or attempts to group them into cells. We don't always have good information from some other source about which centromeres are in the same cell, so this option will use only the position distributions of centromeres in the images to make a guess. This works well for our particular images, but it hasn't been tested extensively with other cell types, etc. The maximum clustering iterations box controls how long it will try to do the clustering. We use a value of 4. "Filter out small clusters" will remove any "cells" that have fewer than the specified number of centromeres, which can often happen if there's a piece of goo in the image that is off by itself.

The "Compensate for punctate background" option is useful if the antibody you are using for the centromere marker has a lot of spotty background that looks somewhat like dim centromeres, and the program is calling the background centromeres as well. We have found that this option is usually necessary for images taken on a confocal microscope, regardless of antibody quality. Leave this unchecked unless this becomes a problem, or else it will throw out a lot of good centromeres. Also, this option will not work correctly if you are not clustering the centromeres.

The "Summarize Data Only" option goes back and remakes a summary from the output files (in case the summary was deleted, you manually edited the output files, etc.), but does not run the actual centromere finder.

The box on the right will report what file it's working on as well as any errors encountered while running in the java portion of the program. Errors encountered in the C++ portion will almost certainly crash the program immediately; some information may be written to the terminal (or for Mac OS X to the crash report).

The output the centromere finder generates will be put into two subdirectories. The first is "output", which will contain a file for each image with all the values in each channel for each centromere, a background estimate, the number of pixels in each centromere, and the cell that centromere is in. (Note that because the extension on these files is ".out", your system may not default to seeing these as plain text files, but they can still be opened with any text editor.) This directory also contains a file, "summary.txt", which will contain averaged values for each cell in each image, or if you didn't cluster into cells, each centromere in each image. The background estimate will likely not be accurate unless you did the clustering into cells, though it will be reported regardless.

The columns are labeled in the summary.txt file but not in the individual output files. In the individual output files there is one row per centromere with the following information: Average intensity per pixel in the marker channel, then other channels in order that they appear in the input boxes, then the number of pixels in that centromere, then background estimates for each channel in the same order, then the ID of the centromere in the output image, and the ID of the cell in the output image.

The second output directory is "output_mask", which will contain two tif images for each input image. The one ending in .0.tif will contain a mask with the objects found as centromere, where the greylevel of each centromere is equal to its cell ID from the output file. The one ending in .1.tif will contain a mask where each centromere has greylevel equal to its centromere ID from the output file. Note that cell IDs and centromere IDs are numbered starting from 1, and the output files are 16 bit tif files, so they will appear completely black unless you open them in a program that automatically rescales images (we use ImageJ for viewing these).

Segment and Quantify Images

This option allows you to test and run several image segmentation methods on a single image or folder of images, including those described in Fuller and Straight (2010). The options in the dialog box that shows up, except that the other channels to quantify, and even the quantification itself can be turned on and off using the check boxes. All other channels are optional, but if checked, they must follow the same naming convention described for the centromere finder.

In the image file box, you can select either an entire directory or a single file; if the single file is selected, the mask resulting from the image segmentation will pop up in a window after the program has run in addition to being written to disk.

The implementation of the watershed method is poor, and on some images it takes an extremely long time to run; if the program appears to stop responding while on this method, this may be why.

The output files follow the same format as for the centromere finder, with the exception that there is no summary file, and only a single segmentation mask is output.

Make Maximum Intensity Projections

This option takes a folder of multi-plane tiff images or metamorph image stacks and created maximum intensity projections from them. They are output as 16-bit tiff images in a subdirectory of the original image directory called "maxintproj". Note that if you are going to run the centromere finder on the maximum intensity projections, you need to run it on the maxintproj directory, not the original directory.

Deschmutzerize

This option assists in the manual review of the segmentation produced by the centromere finder. Specifically, it takes a folder of images and allows you to view each image and its associated mask, lets you specify centromeres or cell groups to remove, and then runs the quantification again for each image on only the remaining centromeres.

In the "File or Directory to Process", you can select either a single image or an entire directory of images. Note that you should select the original image/folder that you specified to run the centromere finder, not the output directory.

When you are ready to begin, press start, and for each image that will be processed, two windows will pop up-- one showing the original image, and one showing the mask. If there are any regions in the mask that you want to remove, either click on them or click and drag a box around them. If the "Toggle Individual Centromere" option is selected, only the centromeres that you clicked or box will be highlighted; if "Toggle Entire Cell" is selected, all centromeres in the cell of and centromere that you click or box will be highlighted. If you make a mistake, click or box again to turn a centromere/cell off.

If you need to zoom in, use the + and - keys to zoom in and out (actually, = not +; no need to hold down shift), and type the number 0 to reset to the original zoom. The zooming with +/- will zoom centered at the point where your mouse is relative to the mask window, so hover your mouse over the point in the mask on which you want to zoom.

When all the regions you want to remove are selected in red, click "Remove Selected and Continue" to quantify the images again without the selected region and move on to the next image in the directory. The new quantification and new masks will be written to subdirectories of the old output directories called "deschmutzed".

Compilation from source

Most of the problems with compiling from source arise due to platform / compiler differences. The options in the build.xml file are fairly general, but may need to be tweaked for your system as described in the installation section.

The first thing to try if it's unclear what might be going wrong is to check the path to "jni.h" on your system and make sure the full path is included in the build.xml file as described in the installation section. Especially if you're compiling on windows, which uses a different folder for every minor version of java, it is unlikely to be the one that I have already put in the build.xml file.

If the build is failing due to linker errors, check to make sure whether you need to be compiling for 32 bit or 64 bit architecture and specify this accordingly. If your operating system / c++ standard library is compiled as 32 bit, you may need to compile for 32 bit even if your processor is 64 bit. If you switch which mode you are using, run:

ant -lib cpptasks.jar clean

before trying to compile again to make sure that any intermediate files compiled for the other architecture are removed.

Running

Most of the time that the program crashes for users it is due to a naming problem-- either the file naming conventions are not being followed exactly, or the directory to process is set to something in the directory instead of the directory itself. Either of these problems can cause error messages in the program window or a full crash of the program; check the names as a first pass if something goes wrong.

It's worth noting a particular tricky case here that several users have encountered. If images are named something like coverslip01_dapi01.tif, for example, and cy3 or cy5 is used for one of the channels, the images may get named something like coverslip01_cy5-01.tif; in this case, the channel name needs to be specified as cy5- (with the dash) so that the filenames are exactly the same except for the specified channel names.

Another common problem is for the java user interface to be unable to find or read the compiled C++ library. In the centromere finder, this will usually appear as an error message in the user interface message box that says there was an "UnsatisfiedLinkError". There are three common causes for this:

1. The program is being executed from the command line, but from the wrong path or without the -Djava.library.path=. command line option. Ensure that you are in the dist subdirectory of the base directory, and that you are running exactly as described in the "Running" section, specifically including the -Djava.library.path=. command line option. (Note that you need to include the dot after the equals sign.)

2. The program was compiled for the wrong architecture. Double check whether you need to compile for 32 or 64 bits, and if you need to switch, run:

ant -lib cpptasks.jar clean

from the base directory, and then recompile.

You may need to compile for 32 bit architecture even if you have a 64 bit processor if the operating system and / or system libraries are installed as 32 bit.

3. You are running Windows and need to insert the option into the build.xml file. See the installation section for instructions.

A less common problem that can nonetheless cause crashes is a corrupted image file, as might result from an interrupted network transfer of images or something similar. If the program always crashes on a particular image, make sure it can be opened without error using an image viewer.