celltool

Celltool is a collection of tools for analysis of shapes from images, and in particular, for analyzing cell shapes from micrographs. Celltool provides methods for extracting shapes from images, aligning and measuring those shapes, plotting shapes, and statistically comparing distributions (usually of shape measurements). Celltool is open-source (GPL).

To refer to Celltool in a publication, please cite:

Pincus Z & Theriot JA. Comparison of quantitative methods for cell-shape analysis. J Microscopy (2007).

Functionality

Celltool comprises the following functionality:

1. Extraction of polygonal contours from images. These contours are the fundamental data produced and consumed by the tools that make up celltool. Contours are extracted as intensity iso-lines from a given image (i.e. by thresholding). If the images are unsuitable for thresholding, otherwise-derived (e.g. manually-defined or generated by an advanced segmentation algorithm) binary masks that already define the individual shapes can be provided. There is no limit to the number of discrete shapes that can be extracted per image.

2. Scaling, alignment, and re-sampling of polygonal contours. The contours, originally defined in pixel units, can be scaled into their natural length units (e.g. microns) for further analysis. Contours can also be aligned along their long axes, and can be re-sampled (via spline interpolation) such that each contour in a population is a polygon defined by the same number of vertices.

3. Mutual alignment of contours. Celltool can align a population of contours in space so that corresponding parts of the each contour's shape are aligned as best as possible. (This works best with shapes that have stereotyped asymmetries, like front/back or left/right.) Simultaneously, the ordering of the vertices of the polygons are aligned as well, so that corresponding parts of each contour's shape have corresponding vertex numbers. That is, once alignment is finished, "point 100" will represent roughly the same position on each contour.

4. Principal components analysis of population shape variability. Once a population of contours are aligned, a process which removes variability due to the pose and position of the contours relative to one another, the remaining variation in their shape represents the "intrinsic" spread of shapes: the space of possible shapes taken up by that population. To compactly summarize this space, Celltool can perform the principal components analysis to decompose this space into a basis set of orthogonal "shape modes", ranked by their order of importance (such a set of modes is referred to by the software as a "shape model"). These shape modes are easy to plot and understand intuitively. Moreover, such modes can be used as a quantitative measure of shape: a given contour's position along several shape modes is a numerical descriptor that can be of great statistical use.

5. Shape measurement. Celltool can measure a given shape's position along the modes of a provided shape model, as well as other simple measures of shape like area, aspect ratio, perimeter, and "smoothness". In addition, CellTool can perform image-based measurements like calculating the average image intensity within a certain region of an image as defined by the position of the contour. (Example: suppose one has a fluorescence micrograph of the distribution of a certain protein and wishes to measure the average amount of protein only at the front of a set of polarized cells. By converting the cells to contours and aligning them, the user can then direct celltool to provide the "average image intensity for each contour only in the polygon region corresponding to the front of the cell, from the cell border to a depth of one micron" or similar.)

6. High-quality plotting. Celltool can produce SVG files (easily editable in Adobe Illustrator and the free Inkscape software, amongst others) showing contour shapes, the shape modes from a shape model, and plotting actual shapes against their measured position along those shape modes (or along any arbitrary numerical measure).

7. Shape-based image manipulation. CellTool can also extract, align, and mask out regions of other images based on the shape of the polygonal contours. Note: this functionality (some variants of the extract_images command, as well as add_image_landmarks) never made the transition from Python 2 to Python 3, due to the need for a simple polygon rasterizer. It's an easy enough fix to use the one from skimage but I haven't added that back yet.

Last, note that celltool is a command-line program, with no "graphic user interface". This is, as they say, a feature, not a bug: because these analysis steps are often performed repetitively different data-sets, celltool is written for a text-mode interface, which makes it easy to script and automate. In addition, lists of text commands can be saved to provide a specific record of the analysis performed.

Installation

The simplest thing is to install the Anaconda Python distribution. This is a collection of many useful scientific python tools, and it provides a reproducible baseline environment that's totally isolated from the computer's python (if it came with one). So if something goes wrong you can just delete the anaconda folder and start again. Obtain the latest Python 3 version, using the graphical or command-line installer depending on your comfort level with the terminal.

An Anaconda install guide is available, but at simplest really all you need to do is download the graphical installer and double-click.

Then open a terminal window. You should see (base) at the beginning of the prompt, which is an indication that you're in the Anaconda base environment. This means you will be using the Anaconda python tools when you type "python" or "pip" or whatnot. (To go back to the system python, type conda deactivate.)

Advanced use: if you want to have a separate conda environment for celltool, then run the following to install the basic dependencies:

conda create -n celltool python numpy scipy scikit-image
conda activate celltool

From there (either in the base or celltool environment if you prefer the latter), just run:

pip install git+https://github.com/zpincus/freeimage-py git+https://github.com/zpincus/celltool

(all one line), which will install Celltool and its dependency, Freeimage.

Freeimage requires compilers, so you may be prompted to install them by your operating system, or may need to do so manually. If install works without error (it'll take a few minutes to compile), then close and reopen the terminal window, and try typing celltool -h into the terminal to make sure you've got it working. Also, type where celltool and make sure that you're running it from the Anaconda directory. (On a Mac, this should show something like /Users/[your username]/opt/anaconda/bin/celltool.)

Tutorial

This description assumes that you are familiar with the command-line interface on your computer. If not, please seek out any number of online tutorials. The celltool suite of shape analysis tools is accessed through the command celltool. To see a list of available actions, type celltool --help; to see help for any particular action, type celltool command --help (replacing "command" with the particular action you want to know more about).

The basic workflow is the same for any use of celltool:

1. Convert images to sets of polygonal contours, one for each cell in the image. Optionally resample the contours so that each has the same number of vertices.

2. Align the contours.

3. Make measurements of the individual contours, or of the shape space which the population inhabits (via PCA).

4. Plot individual contours, the PCA shape space, or the results of various measurements thereof.

First, download the tutorial files, decompress them, and navigate to that directory from the command prompt. There's a directory called "Binary" which contain images of Caulobacter crescentus (already converted to binary images via thresholding, and non-bacterial image blobs manually removed). In particular, there are several images for each of four conditions: bacteria with FtsZ knocked down, MreB knocked down, the double-knockdown, and wild-type. We'd like to compare the shapes of these bacteria under various conditions. Note that the microns-per-pixel scale factor for these images is 0.0680209.

So, step one is to get some polygonal contours for the cells from the binary images. To do so, type (all on one line):

celltool extract_contours --min-area=30 --scale=0.0680209 --units=microns  --resample-points=100 --smoothing-factor=0.001 --destination=Contours Binary/*.png

(If on Windows, replace the forward-slash path separator with a back-slash...) This directs celltool to extract the contours from all of the PNG files in the "Binary" directory, discarding as junk blobs of less than 30 pixels. Celltool then scales the polygons into micron units and resamples each to have exactly 100 points. The resampling is performed with a spline, and we can control the level of smoothing that the spline performs (we want some smoothing to get rid of the high-frequency square pixel edges). This smoothing factor is in the spatial units of the contours (in our case, microns), and in general, the amount of smoothing should be on the order of 1/100 of the dimension of the cells. (Though be sure to experiment with different amounts of smoothing!) Finally, the processed contours will be written out into a directory called "Contours" (which will be created if it does not exist), and given names derived from their original image. On the Mac, you'll get a pretty little progress bar; on the PC a scrolling list of files processed.

Also, note that this command, as with every other shown below, is capabl