TITLE: Quantifying Synaptic Colocalizations with SynBot (ilastik Thresholding)
AUTHORS: Justin T Savage, Juan Ramirez, Dolores Irala, Cagla Eroglu

[DESCRIPTION]
Protocol for quantifying synapse numbers using the ilastik thresholding method in SynBot.

[STEPS]
SECTION: Installation
1. Install/Update FIJI. The newest version of Fiji can be found at https://fiji.sc/ Some features may not function properly if your Fiji is not up to date.
SECTION: Installation
2. Visit the Syn_Bot GitHub repository (https://github.com/Eroglu-Lab/Syn_Bot) and download the ilastik4ij_Syn_Bot-1.8.2-SNAPSHOT.jar file.
SECTION: Installation
3. Navigate to your Fiji application and open the package contents
SECTION: Installation
4. Navigate to the plugins folder of your Fiji application
SECTION: Installation
5. Copy the ilastik4ij_Syn_Bot-1.8.2-SNAPSHOT.jar file into the plugins folder
SECTION: Installation
6. Be sure to close and reopen Fiji after installing any plugins. You should now see SynBot listed in the Plugins drop-down menu. 
SECTION: ilastik Installation
7. Go to https://www.ilastik.org/download.html and download and install the most recent, stable version of ilastik for your OS.
SECTION: ilastik Installation
8. Within FIJI, go to Help-> Update…
SECTION: ilastik Installation
9. Click “Manage update sites” in the popup window
SECTION: ilastik Installation
10. Scroll down and click the checkbox next to ilastik   
SECTION: ilastik Installation
11. Click “Apply Changes”   
SECTION: ilastik Installation
12. Be sure to close and reopen Fiji after installing any plugins. You should now see ilastik listed in the Plugins drop-down menu
SECTION: Generating a Training Set
16. Open FIJI and click and drag the extract_channels.ijm macro to open it in the script editor
SECTION: Generating a Training Set
17. Click the run button in the bottom left of the window
SECTION: Generating a Training Set
18. Select the training set folder of images, the red channel images folder, and then the green channel folder in the ImageJ file explorer prompts.
SECTION: Generating a Training Set
13. Create a folder on your computer that contains a haphazard sample of images that you want to analyze for this experiment (~6 images should be enough). It is best if these images represent the range of intensity values in the data set and come from each of your conditions. This folder will be your training set.
SECTION: Generating a Training Set
15. Create an empty folder to store the red channel images of your training set and an empty folder to store the green channel images of your training set.
SECTION: Generating a Training Set
19. ImageJ will now generate your single-channel images which can be used to train ilastik.
SECTION: Generating a Training Set
14. 
 

SECTION: ilastik Model Training
20. Open your ilastik application.
SECTION: ilastik Model Training
21. Under "Create New Project", click the Pxel Classification option.
SECTION: ilastik Model Training
22. Choose a location to save your ilastik project. You should name your project something that corresponds to the channel and conditions of your training data.
SECTION: ilastik Model Training
23. On the left of the screen you will see the basic steps of the ilastik workflow.
  

SECTION: ilastik Model Training
24. With "Input Data" selected in the workflow menu, click the "Add New" button. In the dropdown menu select "add separate image(s)". 
SECTION: ilastik Model Training
25. Select all of your red channel images from your training set.
SECTION: ilastik Model Training
26. Click the "Feature Selection" tab in the workflow menu.
SECTION: ilastik Model Training
27. Click "Select Features"
SECTION: ilastik Model Training
28. Select which image features to use for thresholding in the "Features" pop-up window.
  For cell culture images where there are fewer synapses and less noise, we recommend using Ctrl+A to select all of the image features. For images from mouse tissue sections, we recommend selecting the Color/Intensity features with Sigma values of 0.30, 0.70, 1.00, and 1.60.

SECTION: ilastik Model Training
29. Once image features are selected, you can click on the feature names in the lower left "Features" box to view what these image features look like for your images. 
SECTION: ilastik Model Training
30. Click the "Training" button in the workflow menu.
SECTION: ilastik Model Training
31. You will now see the training options in the workflow menu
  With "Label 1" selected, you can annotate examples of foreground pixels (i.e. synaptic puncta) in your images. With the "Label 2" selected, you can annotate examples of background in your images. You can use the "Size" dropdown to change the size of your annotation to make sure they are accurate. 

SECTION: ilastik Model Training
32. Annotate approximately 20 examples of foreground objects (i.e. synaptic puncta) in your image with the Label 1 selected. You can use Shift_++ to zoom in your image if necessary. You can also use the - key to zoom out.+
SECTION: ilastik Model Training
33. Annotate some background in your images using the Label 2. This can be done by increasing the size of your annotation and clicking and dragging to annotate a line of background. Your annotated image should now look something like the example below.
  

SECTION: ilastik Model Training
34. Now click the "Live Update" button in the workflow menu. This will give you a preview of how your ilastik model will threshold your image.   

SECTION: ilastik Model Training
35. With Live Update turned on, you can continue to annotate your image until the preview looks accurate. 
SECTION: ilastik Model Training
36. Once the preview looks accurate for the first image, use the "Current view" dropdown in the workflow menu to switch to the next image in your training set. Check the preview on this image and make additional annotations if necessary. Repeat with the rest of the images in the training set.
SECTION: ilastik Model Training
37. Once you are satisfied with the Live Update preview for all of your images, save the ilastik project using Ctrl+S. You can then close ilastik without continuing to the "Prediction Export" or "Batch Processing" section of the workflow as these steps will be handled by SynBot.
SECTION: ilastik Model Training
38. Repeat the above steps to train a model for your green channel training set.
SECTION: Preparing your images for SynBot
39. Before running SynBot, it is recommended to convert your images into the Tiff format, though SynBot can run on a variety of file types, this is a frequent source of error. (See the extra_code folder at https://github.com/Eroglu-Lab/Syn_Bot for example image type conversion macros). 


 

 

SECTION: Preparing your images for SynBot
40. Create a folder for your experiment with subfolders for experimental groups. Each experimental group folder should contain only image files. Multiple experimental groups are not required, but your files must follow the Experiment/Group/Image structure. 

    
SECTION: Running SynBot
41. Open your version of FIJI where you installed the ilastik4ij_Syn_Bot-1.8.2-SNAPSHOT.jar file.

SECTION: Running SynBot
42. Visit the Syn_Bot GitHub repository (https://github.com/Eroglu-Lab/Syn_Bot) and download the Syn_Bot.ijm file.
SECTION: Running SynBot
43. Click and drag the Syn_Bot.ijm file into FIJI to open it in the FIJI script editor.
SECTION: Running SynBot
44. Click the run button on the bottom left corner of the script editor to run the macro.
SECTION: Running SynBot
45. Once the macro begins running, the following start-up menu will appear:
  

SECTION: Running SynBot
46. Channels: Select the appropriate number of channels to be analyzed (2 or 3). Images will be converted to the RedGreenBlue (RGB) format and the Red and Green channels will be analyzed for 2-Channel Colocalization and the Red, Green, and Blue channels will be analyzed for 3-Channel Colocalization. If necessary, image channels can be changed to fit these colors using the Pick Channels option.
SECTION: Running SynBot
47. Preprocessing: Select whether or not to use the noise reduction or brightness adjustment preprocessing functions. Noise reduction is recommended for most in vivo imaging applications. Brightness Adjustment is not recommended unless absolutely necessary since it alters the intensity of the original images, but can be helpful if all images are uniformly dim. 
SECTION: Running SynBot
48. Thresholding: Select the desired thresholding method from the provided options. This protocol will focus on the ilastik thresholding option where each channel of each image is assigned a threshold by ilastik. 
SECTION: Running SynBot
49. ROI Type: Select the desired region of interest (ROI) type from the provided options. Whole Image should be selected unless there is a specific ROI within the image to focus analysis around. 
SECTION: Running SynBot
50. Within ROI Type, the user also selects minimum and maximum pixel values for each channel. These are the bounds on the area (in pixel units) of the smallest and largest puncta to be included in the analysis.  
SECTION: Running SynBot
51. Analysis Type: Select either the circular-approximation or pixel-overlap analysis modes. The pixel-overlap method is recommended for most applications and uses the individual pixels of each channel to determine colocalizations. The circular-approximation mode uses the area and location of the puncta for each channel to approximate each puncta as a circle and then determine if the circles from each channel are overlapping and is only recommended when comparing to results obtained with previous algorithms that used circular-approximation (such as Puncta Analyzer). 
SECTION: Running SynBot
52. Experiment Directory: Click the browse button and select the Experiment level folder that we set up earlier. You must select the Experiment-level folder rather than the Group-level folder or image files.
SECTION: Running SynBot
53. Once the desired settings have been entered, click the OK button to begin running SynBot
SECTION: ilastik Thresholding
54. With the ilastik threshold mode selected, a pup-up window called "Select ilastik files" will allow you to choose the location of your ilastik application and ilastik project files.
SECTION: ilastik Thresholding
55. Click the first browse button and select the ilastik application. On Mac, this will simply be the ilastik app in your Applications folder. On Windows, you should select the ilastik.exe file within the ilastik folder where the application is installed. This ilastik folder will most likely be in your Program Files folder.
SECTION: ilastik Thresholding
56. Use the second and third browse buttons to select the red and green ilastik project (ilp) files that you created earlier.
SECTION: ilastik Thresholding
57. Click OK once all file locations have been filled in.
SECTION: ilastik Thresholding
58. SynBot will now run on your images using the provided ilastik projects. No more user input is required. You can monitor SynBot's progress in the "Log" window. Once SynBot is finished running, it will print "done" and the time that it took to run as well as displaying the Summary output results window.
SECTION: Data Outputs
59. Once thresholding all images is completed, a results file called Summary.csv will be displayed. This file is automatically saved within the Experiment-level folder selected earlier and can be closed.

 

SECTION: Data Outputs
60. Navigate to the Group-level folders within the Experiment-level folder selected earlier. These Group folders will now each contain an Output folder which includes several useful outputs:
A copy of the original image converted to RGB (i.e. image_1.tif)
A copy of the original image with white overlays labeling each counted colocalization (i.e. image_1_colocs.tif)
The thresholded image for each channel (i.e. image_1_redThresholded_0.tiff)
The full set of measurements of each punctum counted for each channel (i.e. image_1_redResults_0.csv)
These files should be reviewed to ensure the program is counting colocalizations as desired. 
SECTION: Data Outputs
61. Returning to the Experiment-level folder shows the Summary.csv file which includes the summary statistics for each image that serve as the primary outputs of the SynBot analysis including:
Puncta counts for each channel
Colocalized puncta count
Min Pixel values used