Latest revision as of 22:01, 20 February 2012

Details

• Goal: This tutorial will show you how to use FARSIGHT tools to generate centerline traces of microglia processes.
• Duration: 15 minutes (depending on processing power)
• Prerequisites: FARSIGHT v0.4.4 (or later) installed, python installed.

In this tutorial we will be working with a small example image titled C1-1unmixed-crop.tif. This is included in your FARSIGHT installation within the data directory. If you'd prefer to do so you can perform this tutorial using another 3D image of microglia.

Overview

This microglia segmentation procedure is divided into two steps. First, we isolate the somata, or cell bodies, of the microglia depicted in the input image. One of the outputs that we obtain from the soma segmentation procedure is a list of the centroids of the somata. These centroids serve as seed points for our second step: microglia process tracing. The output of process tracing is a .swc file.

Once tracing is complete we can view, validate, and edit our results using the FARSIGHT Trace Editor.

Some Words about Image Spacing

The segmentation tools presented in this tutorial have been designed to use information about the input image's spacing. This allows our tools to achieve useful results regardless of the input image's magnification level. By "spacing", we refer to the amount of physical space that is represented by each voxel. Images obtained from confocal microscopes are typically anisotropic. Therefore we consider the image's X/Y spacing separately from its Z spacing.

Some image formats allow you to embed this spacing information within the image's header. In this case, our tools will automatically read & use this information. Other formats do not have this feature. If default image spacing is detected, you will be prompted to supply this information on the command-line prompt.

The segmentation tools presented here expect image spacing to be set in units of microns per pixel.

The example image C1-1unmixed-crop.tif does not have its spacing embedded inside an image header. Therefore, when prompted, you should supply the following values:

Soma Segmentation

These instructions show how to segment somata from the microglia channel. A future tutorial will focus on how to incorporate the Nucleus channel in this task.

In the instructions below, commands are isolated in boxes and preceded by $. Expected output will also be included in the box. It will be distinguished by use of italics. Unless otherwise indicated, all commands are meant to be executed from the command-line. For this tutorial, the current working directory is assumed to be the root of your FARSIGHT installation. This is the location of the following subdirectories: bin, data, lib, python.

To perform soma segmentation we use the ExtractSoma.py python script. This is located within the FARSIGHT bin/ directory. Running this script with no arguments gives us more information about how it is meant to be used:

$ bin/ExtractSomas.py 

bin/ExtractSomas.py <input image> <output image> [spacingXY spacingZ]

The square brackets indicate optional parameters. We can either supply the image spacing on the command-line, or wait for the application to prompt us for this information.

The soma extraction script produces a lot of intermediate results. Therefore, let's create a new directory for our output. This will keep us from cluttering up the data directory.

$ mkdir output

Now we're ready to extract the solitary soma from our example image.

$ bin/ExtractSomas.py data/C1-1unmixed-crop.tif output/C1-soma.tif 0.3 0.5

Preprocessing input image
Reading image spacing from command-line
Input image's spacing now set to [0.3, 0.3, 0.5]
Separating image foreground from background
Eroding away microglia processes
Isolating somata
minimum volume required to be considered a soma: 75
Before pruning, I count 1 distinct somas.
Blob #1 has a volume of 382.5
I count 1 distinct somas.
		(min	avg	max)
Elongation	1.73439	1.73439	1.73439
Flatness	1.26948	1.26948	1.26948
Radius		4.50313	4.50313	4.50313
Size		382	382	382

The ExtractSomas.py script is well-documented. By examining this file in a .txt editor you should be able to gain a greater understanding of the numerical parameters that are used in this procedure.

Process Tracing

The tool we use for this step is aptly named MicrogliaProcessTracer. As before, it can be found within the bin/ subdirectory of your FARSIGHT installation. Again, we can run this command-line executable with no arguments to see what input it expects:

$ bin/MicrogliaProcessTracer 

bin/MicrogliaProcessTracer input-image seedfile.txt soma-image distance-threshold output.swc [spacingXY spacingZ]

The only numerical parameter here is the distance threshold. This determines how far apart (in microns) two connect "interest points" can be. A good default value for this parameter is 3 microns.

$ bin/MicrogliaProcessTracer data/C1-1unmixed-crop.tif output/soma-centroids.txt output/C1-soma.tif 3 
    output/C1-traces.swc 0.3 0.5

Loading the input image
Reading input file data/C1-1unmixed-crop.tif
Input image's spacing now set to [0.3, 0.3, 0.5]
Input file size (after zero padding) is [190, 168, 24]
Reading the start points
Reading the soma image
Distance Threshold: 3
Beginning Tracing

Searching for critical points
Analysis at sigma 1
Number of CTs at this stage: 1012
Analysis at sigma 1.18921
Number of CTs at this stage: 261
Analysis at sigma 1.41421
Number of CTs at this stage: 148
Analysis at sigma 1.68179
Number of CTs at this stage: 48
Analysis at sigma 2
Number of CTs at this stage: 9
Analysis at sigma 2.37841
Number of CTs at this stage: 4
open list size: 334
closed list size: 1
computing adjacency matrix for seed points
computing adjacency matrix for critical points
25 nodes were too far away to get added to a cell model
cleaning up nodes that fall within a soma
writing output to disk
Total time to segmentation is : 3.04034

Post-Segmentation Analysis

main article: Trace Editor

Now that we've successfully traced an image of microglia, open up TraceEdit. On Mac OSX this can be found in the root of your FARSIGHT installation as TraceEdit.app; all other platforms will find the executable within the bin/ subdirectory. You will be greeted with the following welcome dialog:

Trace Editor bootup dialog

This is where we load our data into the Editor.

• Click Trace and select output/C1-traces.swc
• Click Image and select data/C1-1unmixed-crop.tif
• Click Somas and select output/C1-soma.tif
• Click Start

Segmentation results projected against input data

You can gain more analytical information about these results by accessing the following menu options:

• Analysis -> Cell Analysis
• Analysis -> Show Plots

Please see Trace Editor for more information about this tool and its capabilities.