Synapse Detection

The synapse detection module of ilastik requires a special binary distribution, which can be found at at the download page. Compared to standard ilastik 0.5 release it contains two additional tabs: connected components and object picking, and an enhanced multivariate threshold widget.


Workflow:

As usual in ilastik, the workflow goes through the tabs from left to right.

1. Load the data

To load the data into ilastik, follow the steps, shown in the video "Loading and Processing stacks of images" here Missing page "Videos" in category "Documentation". The images in the stacks should already be aligned. The Fiji framework includes some popular stack registration tools.

2. Label

We normally use 3 classes: membranes, synapses and the rest. In principle, 2 class labeling of synapses and non-synapses is equivalent from the algorithm point of view, but then you have to be careful to label enough membranes and synapses to have a good representation of your data.

3. Select features

ilastik provides a large set of generic features for classification of all kinds of images. For synapse detection we used the following ones (scale in brackets, ordered by importance): Texture(megahuge), Texture(huge), Color(huge), Color(megahuge), Color(large), Color(medium), Edge(huge), Edge(megahuge), Color(small), Edge(megahuge), Texture(large), Color(small). This feature set is optimized for 5x5x9 nm resolution, if your resolution is significantly lower, you'll have to adjust the scale accordingly. If your machine does not have enough RAM to compute all the features, omit the ones of lower importance. In our experience, the algorithm is fairly stable to feature selection.

4. Classify

First, try out the interactive classification. It will predict the results for the current slice very fast and you can immediately correct the prediction by adding more labels. Once you are happy with the prediction quality on a few slices, press the "Train and Predict" button to predict the whole volume.

5. Threshold

Create a new thresholding overlay. As foreground, select your synapse label. As background, select all other labels. Activate the smoothing (we use a sigma of 5 pixels. Adjust according to your data resolution). Adjust the sliders until the true synapses are still visible, but most of false positive predictions are gone or very small. The probabilities you have selected are printed in the console for reference.

6. From this point on you have a choice of either continuing in fully interactive mode, if your stack of images is not too large, or to process them offline.


6.1 Fully interactive mode

Proceed to Connected Components tab and choose your thresholded overlay (called "My Overlay" by default) as input. Label some pixels (just a few) in the background and press the "CC with background" button. As a result, you should get a new overlay "CC result", showing all synapse candidates as separate objects of different colors. However, there are probably still some false positives, especially very small speckles or very large myelin covered structures. To get rid of them, press the "Filter Synapses" button on the right. A dialog will pop up, asking you for the synapse label number and the sizes to filter. We used 1000 voxels for the lower limit, as it approximately corresponds to the volume occupied by two vesicles, and 200000 as upper limit. You should now have a new overlay "CC Filtered" with the final detected synapses. They can be further corrected in the next "Objects" tab (section 7)

6.2 Offline processing mode

Switch to the Automation tab. To process image stacks as 3D objects, you currently have to convert your stack into a file of hdf5 format. The simplest way to do it, if you have enough memory, is to load the stack into ilastik and use the "Also save to destination file" option of the stack loading dialog. The files, produced in this way, can be added to the list of files to process in the batch processing dialog. Another option is to convert with a simple python script (will be here soon). In the batch processing dialog don't forget to tick the box for "blockwise processing to save memory". Once you press the "Process" button, ilastik will classify the voxels in this file with the classifier you trained in steps 2-4. Once the batch processing is done (this might take a while), you should get a file called <your_input_filename>.h5_processed.h5. Now open a command line console and go to your ilastik directory. There should be files, called "synapse_detection_script.py" and "synapse_detection_script_blockwise.py". To choose which one you need, keep in mind that the first one uses 4*original_data_size of memory (for predictions of the 3 classes + thresholding). If you don't have enough RAM, use the second script, which processes blockwise and dumps intermediate results into a file. The arguments you need to provide for both scripts are 1) the file you got from batch processing (say, test.h5_processed.h5), 2) The number of the label used for synapses. In our examples it's the yellow label, which has the number 2 (we count from 0), 3) The threshold you selected in section 5, 4) minimum synapse size in voxels (we use 1000), 5) maximum synapse size in voxels (we use 200000), 6) The output file name. For example: call the script with "python synapse_detection_script.py test.h5_processed.h5 2 7. 1000 200000 /some_path/synapses_output.h5"

7. Visualization and proof-reading

7.1 Input

If you got here from the fully interactive mode 6.1, switch to the "Objects" tab, select the "CC Filtered" overlay as input and skip to the next paragraph. If you processed your data offline, open a new instance of ilastik. Press the "New" button of the "Project" tab and then press the "Load File" button. Select the file which served as output for the offline processing scripts. If the file is too large to fit in memory, check the "Advanced options" checkbox and select a subset of data. If you now switch to the "Classification Tab", the detected synapses should be displayed in yellow. Switch to the "Connected Components" tab and select the "Labels" overlay as input. Label a few background pixels (just a few) and press the "CC with background" button. The detected synapses should now appear as separate objects of different colors. Switch to the "Objects" tab and select the "CC Results" overlay as input.

7.2 Visualizing single synapses in 3d

Simply click on a synapses to select it. It will be added to the "Selection Results" overlay, which will appear in the list menu in the right part of the screen. To de-select a previously selected synapse, click on it, while pressing the "Shift" key. To visualize the selection results in 3d, right click on the "Selection Results" overlay and select "Display 3d" context menu option. Clicking on the synapses in the 3d view window will automatically change the slice views in ilastik to display the selected point.

7.3 Proofreading

ilastik only has rudimentary proof-reading functionality, which allows to get rid of false positive detections. Press the "Select all" button to select all the synapses. If, while going through the stack, you notice a false positive synapse, de-select it by clicking on it while holding the "Shift" key. The total number of currently selected synapses is printed in the terminal.

7.4 Creating a summary report

Once you are happy with your synapse selection (or if you'd rather do the proof-reading in the report directly), click the "Generate report" button and choose a filename. It will automatically create 2 directories to hold the output images and the report itself in html.