TITLE: QUINT Workflow for Fluorescence
AUTHORS: Michael X. Henderson

[DESCRIPTION]
This protocol describes QUINT workflow for fluorescence.

[GUIDELINES]
Purpose

The purpose of this workflow is to enable mouse brain segmentation, registration, and quantification of regional signals. The simplest segmentation is done in QuPath because this program handles whole slide images and has good segmentation algorithms. Registration is done using 3 programs: QuickNII (aligns to a 3D atlas, typically the 2017 CCFv3 Allen Brain Atlas), VisuAlign (allows for non-linear warp transformation of the atlas to match sections), QMask (masks each side of the brain to allow for bilateral assessment of brain regions). Segmentations and registrations are then brought together in Nutil, enabling the generation of quantitative measures for every region of the brain.

Necessary Programs and Locations

6. QuPath: https://qupath.github.io/ 
7. QuickNII: https://www.nitrc.org/projects/quicknii (SELECT ABA Mouse Edition) 
8. VisuAlign: https://www.nitrc.org/projects/visualign/
9. QMask: \\pn.vai.org\projects_secondary\henderson\NOAH\QMask-Standalone 
10. Nutil: https://www.nitrc.org/projects/nutil/
*QuickNII, VisuAlign, and Nutil can be a bit finicky, and we have found it is best to have these folders on the desktop.

Scanned Slides  

To enable high throughput, slides are scanned on the Axioscan microscope. After slide scanning, images will be found at \\pn.vai.org\projects_primary\henderson\vari-core-generated-data\Axioscan\RNAScope. Move the slides into either the Human or Mouse folder and then into its corresponding stain and channel folder. If a folder does not exist, create one following the naming convention (i.e., Stain3_Slc17a7_Gad1_pS129).

Folder Organization 

The programs for registration and quantification rely on having exact file paths from which to call the data. Therefore, it is easiest to set these folders up from the beginning and using the following layout: 

1. QUINT Workflow 
     a. slide#stain# 
 


       i. QVN (for QuickNII, VisuAlign, Nutil) 
          1. Atlas 
          2. Input 
          3. Mask 
          4. Output_Left 
          5. Output_Right 

[STEPS]
SECTION: QuPath Visualization/Segmentation
1. 
 
Open the QuPath application. Select ‘Create project’.
SECTION: QuPath Visualization/Segmentation
2. Select your slide/stain folder within your QUINT Workflow project folder (i.e., slide24stain19).
SECTION: QuPath Visualization/Segmentation
3. Select ‘Add images’ > ‘Choose files’. Navigate to the image file and select ‘Open’. Set image type to Fluorescence. Select ‘Import’.
SECTION: QuPath Visualization/Segmentation
4. Double click on the first image for it to appear in the viewing window.
SECTION: QuPath Visualization/Segmentation
5. Open the Brightness & contrast window (  ) and leave it open.

SECTION: QuPath Visualization/Segmentation
6. Select ‘Automate’ > ‘Show script editor’. Run the following script (change the channel names to the corresponding channels for your stain). This will change your channel names to the appropriate names. 
 
SECTION: QuPath Visualization/Segmentation
7. Stay on the first image. In the script editor window select ‘Run’ > ‘Run for project’. Move all the images over to the selected column except for the first image. You cannot run a script for the whole project on an image that you have currently open in the viewer. Select ‘OK’. Close the script editor.
SECTION: QuPath Visualization/Segmentation
8. For each image, adjust the Min and Max display in the Brightness & contrast window for each channel as needed to make the scan easier to see. This only changes your visual, no actual properties of the scan. Pathology Stain Segmentation
SECTION: QuPath Visualization/Segmentation
9. Create annotation classifications for any new channel names you have previously not worked with. Select the ‘Annotations’ tab > three dots in the bottom right of the window > populate from image channels. Ensure that the class color matches the channel color.
 
SECTION: QuPath Visualization/Segmentation: Image Export for Registration
10. Select the rectangle button (   ) and select your ROI around the first brain. 
SECTION: QuPath Visualization/Segmentation: Image Export for Registration
11. Lock the rectangle by selecting the annotation (the rectangle will appear yellow). Right click inside the rectangle, select ‘Annotations’ > ‘Lock’. This will lock the rectangle, so it is not accidentally moved.
SECTION: QuPath Visualization/Segmentation: Image Export for Registration
12. MAKE SURE THE RECTANGLE IS SELECTED (YELLOW) AS YOU COMPLETE THIS STEP. Select ‘File’ > ‘Export Images’ > ‘Rendered RBG (with overlays)’. Set the export format to (PNG). Set the downsample factor to 12.0. Select OK.
SECTION: QuPath Visualization/Segmentation: Image Export for Registration
13. Save in the QVN folder with the appropriate naming designation (i.e., sl18st3sc1_s041, sl18st3sc2_s042_).
SECTION: QuPath Visualization/Segmentation: Image Export for Registration
14. Repeat steps 10-13 for each image.
SECTION: QuPath Visualization/Segmentation: Cell Detection
15. Select ‘Analyze’ > ‘Cell Detection’ > ‘Cell Detection’ to open the cell detection window.
SECTION: QuPath Visualization/Segmentation: Cell Detection
16. Adjust the Cell Detection parameters as needed. The most helpful parameters to adjust are Sigma, Minimum Area, Maximum Area, Threshold, and Cell Expansion.

a. Minimum Area and Maximum Area will be dependent on whether you are analyzing mouse or human tissue.
b. Keep all checkboxes checked “Split by Shape”, “Include Cell Nucleus”, “Smooth Boundaries”, and “Make Measurements”.
c. A lower Sigma value will break up nuclei more. A higher Sigma value will combine nuclei more often. 
d. Once you are satisfied with the parameters, you can save the Cell Detection script to easily apply it to your other images. The same cell detection parameters must be applied to all images.
SECTION: QuPath Visualization/Segmentation: Cell Detection
17. Remove cells from areas of damaged tissue or outside the brain. 
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
18. Select the three dots to the right of ‘Auto Set’ > ‘Add/Remove…’ > ‘Add class’. Name the new class ‘Training’. 
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
19. Choose 6-7 regions across all 8 images to use as training images. These regions should be ones that contain a variety of staining to properly train the classifier.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
20. For each annotation rectangle created for the training classifier, set its class to ‘Training’ by right clicking in the annotation rectangle > ‘Set class’ > ‘Training’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
21. Once you have created all your training annotations, select ‘Classify’ > ‘Training images’ > ‘Create training image’. Set the classification of your combined training annotations to ‘Training’ and select ‘Rectangles only’. Set the image type of your combined training annotations to ‘Fluorescence’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
22. Create a duplicate of the combined training annotations for each different channel you have (excluding your nuclear stain). Rename the image to include the channel name. To duplicate, right click on the combined training annotation image and select ‘Duplicate image(s)’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
23. Draw a rectangle annotation around each training image. Lock the annotation. Run cell detection with the same parameters as your individual images.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
24. Select ‘Classify’ > ‘Object classification’ > ‘Train object classifier’. Set the object filter to ‘Cells’, the classifier to ‘Artificial neural network (ANN_MLP)’, features to ‘Selected measurements’, classes to ‘All classes’, and training to ‘All annotations’. Select ‘Select’ to the right of ‘Selected measurements’ and select all measurements corresponding to the selected training channel. Leave the window open.

SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
25. Open the points window (   ). Select ‘Add’ two times to add two annotations. Set the first annotation to ‘Ignore*’ by right clicking on the annotation and select ‘Set class’ > ‘Ignore*’. Set the second annotation to the channel you are training.

SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
26. In the Brightness & contrast window, turn off all channels except the channel you are training.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
27. Train the classifier by using the points annotations to identify cells as either positive for the channel or ignore. Continue training the classifier until you are satisfied with the predicted output. Select live update to view how the points you select are affecting the classifier.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
28. Give the classifier a name with the slide number, stain number, the channel, and the date (i.e., slide24stain19_Nr4a2_12.16.22). Select ‘Save’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
29. Repeat steps 24-28 for every training image.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
30. Select ‘Classify’ > ‘Object classification’ > ‘Create composite classifier’. Move the individual classifiers to the ‘selected’ side of the window in the order you want them to be applied. Enter a name for the combined classifier (i.e., sl18st19_composite_11.22.22) and select ‘Save & apply’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
31. For each whole brain image, select ‘Classify’ > ‘Object classification > ‘Load object classifier’, select the composite classifier you just created and ‘Apply classifier’.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
32. To show sub-classes identified from your composite classifier (cells identified as positive for multiple channels) navigate to the ‘Annotations’ tab > three dots button in the bottom right of the window > ‘Populate from existing objects’ > ‘All classes (including sub-classes)’. Select ‘Yes’ when asked if you want to keep the existing available classes.
SECTION: QuPath Visualization/Segmentation: Training Object Classifiers
33. Write down the 6-digit web color code for each sub-class in your annotation window. You will need this information for Nutil. Double click the channels listed in the annotations tab to view the color code.
 
SECTION: QuPath Visualization/Segmentation: Export Segmentation
34. Navigate to each scene image and rename the annotation that is off the entire brain image. Rename by right-clicking on the selected annotation image > ‘Annotations’ > ‘Set properties’. Rename the annotation using the following naming convention: ‘sl18st19sc1input_s041_’ ; ‘sl18st19sc2input_s042_’.
SECTION: QuPath Visualization/Segmentation: Export Segmentation
35.  Navigate to one of your combined training images.
SECTION: QuPath Visualization/Segmentation: Export Segmentation
36. Select ‘Automate’ > ‘Show script editor’. 
SECTION: QuPath Visualization/Segmentation: Export Segmentation
37. Enter the script in the blue box below at line 1. You can export multiple cell classifications together to simplify the downstream Nutil input. To do so, add more lines with
  “.addLabel(‘Name of classification’, #).
SECTION: QuPath Visualization/Segmentation: Export Segmentation
38. Select ‘Run’ > ‘Run for project’. Move each scene image over to the ‘Selected’ window and select ‘OK’. 
 

SECTION: QuPath Visualization/Segmentation: Export Segmentation
39. Find the exported images in the export folder. The segmentation image should be white with objects in their WEB ID color. The images should be the exact same dimensions of the earlier region of interest image you created as a PNG with a downsize factor of 12.
SECTION: QuPath Visualization/Segmentation: Export Segmentation
40. Scenes with smaller annotation regions that you used to make your training images will have a second segmentation. Delete the segmentation image that corresponds to the smaller annotation.
SECTION: QuPath Visualization/Segmentation: Export Segmentation
41. Copy the images to the ‘Input’ folder in the QVN folder. These images will be used in the final step of Nutil. Close the QuPath application.
SECTION: QuickNII Brain Atlas Registration
42. Open the QuickNII program folder.
SECTION: QuickNII Brain Atlas Registration
43. Open Filebuilder.
SECTION: QuickNII Brain Atlas Registration
44. Navigate to the QVN folder with the brain image exports from QuPath. These images are not the segmentation exports, but the original brain image exports. These images must all be surrounded by a yellow rectangle.
SECTION: QuickNII Brain Atlas Registration
45. Select all the images to be registered and select ‘Open’. It is useful to add a shortcut of your QUINT Workflow folder to your desktop for simpler navigation.
SECTION: QuickNII Brain Atlas Registration
46. Select ‘Save XML’. Navigate to the QVN folder and save as ‘Filebuilder XML’. Make sure to save this file in the same folder as the brain image exports from QuPath.
SECTION: QuickNII Brain Atlas Registration
47. Close Filebuilder.
SECTION: QuickNII Brain Atlas Registration
48. Open the QuickNII application. Select ‘Manage data’ > ‘Load’ and select the XML file that was just generated in step 5.
SECTION: QuickNII Brain Atlas Registration
49. Double click on the first image in Filebuilder to have it show up in the viewing window in the QuickNII application.

SECTION: QuickNII Brain Atlas Registration
50. Select ‘Rainbow 2017’ from the drop-down menu in the upper left-hand corner of the toolbar (1).
SECTION: QuickNII Brain Atlas Registration
51. You can adjust how you see the atlas overlay by dragging the vertical transparency bar on the left side of the screen (2).
SECTION: QuickNII Brain Atlas Registration
52. For the first section, find the anteroposterior position. To do this, drag the sagittal red dot (3) to the correct rostro-caudal position. Select ‘Store’ to save the position.
SECTION: QuickNII Brain Atlas Registration
53. Repeat step 11 for the last section. This will bring all other sections to the approximately correct position.
SECTION: QuickNII Brain Atlas Registration
54. Adjust each individual section to the appropriate place in the atlas. Many adjustments may need to be made until the correct plane of section is identified. 
 

    a. Rotation: clockwise or counterclockwise (4).
    b. Brain size: in the x and y direction (5). 
    c. Rostro-caudal position: adjust sagittal view. 
    d. Left-right plane: adjust horizontal view. 
    e. Front-back plane: adjust sagittal view.
 
SECTION: QuickNII Brain Atlas Registration
55. Select ‘Store’ before moving off a section or it will not save!
SECTION: QuickNII Brain Atlas Registration
56. Navigate to the next section by double clicking on the section in the Filebuilder, or by selecting the  arrows in the upper-right corner. Edit all sections as noted in step 13.
SECTION: QuickNII Brain Atlas Registration
57. Select ‘Manage data’ > ‘Export Propagation’ and save this XML filed as “QuickN XML.xml” within the QVN folder. It is not automatically recognized as a .xml file, hence the need to add “.xml” to the end of the name.
SECTION: QuickNII Brain Atlas Registration
58. Select ‘Save JSON’ and name it “QuickN JSON” within the QVN folder. This JSON file is used for VisuAlign. Make sure to save the JSON file in the same folder as the brain image exports from QuPath and the Filebuilder XML file.
SECTION: QMask
59.  In the QuickNII application, go back to the first section. Show just the rainbow atlas image.
SECTION: QMask
60. Adjust the horizontal plane to a hemispheric split (completely vertical). Ensure proper bisecting by confirming it within the coronal plane. You want to perfectly bisect the coronal plan. Change the angle if needed.
 
SECTION: QMask
61. Hover the cursor over the brain viewing window and record the x-y-z coordinates (shown in the top left of the window) for the following three parts of the brain: top left, top right, and bottom left. 
 
SECTION: QMask
62. Open the QMask tool and select ‘Pick XML’ and open the QuickN XML file generated in QuickNII.
SECTION: QMask
63. Enter the x-y-z coordinates.
SECTION: QMask
64. Select ‘Destination’ and navigate to the Mask folder within your current project folder and select ‘Open’.
SECTION: QMask
65. Select ‘Go’. The mask output should be a black and white PNG. Close QuickNII and the QMask tool. 
 
SECTION: QMask
66. Ensure the mask files are named using the appropriate naming convention (i.e., sl18st3sc1_s041_mask).
SECTION: QMask
67. You can check to see if your mask outputs accurately bisect for a hemispheric split by comparing the mask output to the output from VisuAlign. 
SECTION: VisuAlign
68. Open the VisuAlign application.
SECTION: VisuAlign
69. Select ‘File’ > ‘Open’ and select the QuickN JSON file you created in QuickNII.
SECTION: VisuAlign
70. Drag the opacity bar all the way to the right towards ‘Outline’. This will display an outline of all the regions. This is the easiest format for transformation. You can change the color of the outline and the marker for easier visualization.
SECTION: VisuAlign
71. Align all regions properly.
SECTION: VisuAlign
71.1.  Hover over an atlas region.
SECTION: VisuAlign
71.2. To create a marker, click the space bar. 
SECTION: VisuAlign
71.3. Drag the maker symbol to the correct location. 
  
SECTION: VisuAlign
71.4. Markers can be moved at any point. To delete a maker, hover over the maker and click delete on the keyboard.
SECTION: VisuAlign
71.5. Markers can be moved at any point. To delete a maker, hover over the maker and click delete on the keyboard.
SECTION: VisuAlign
72. Select the < and > arrows at the top-right to navigate between sections. There is no need to save 
or store these as in QuickNII. 
SECTION: VisuAlign
73. Once all images are complete, select ‘File’ > ‘Save as’ and save as ‘VisuAlign JSON’ in the QVN folder. This can be opened again to continue aligning later.
SECTION: VisuAlign
74. Select ‘File’ > ‘Export’ and navigate to the Atlas folder and select ‘Select Folder’. This will export the files needed for Nutil. These are also the images that you can compare to the Mask outputs to determine the accuracy of your hemispheric split.
SECTION: Nutil
75. Open the Nutil application and navigate to the ‘Operation’ tab. 
SECTION: Nutil
76. Select ‘New’. Select ‘Quantifier’ from the drop-down menu and select ‘Ok’.
SECTION: Nutil
77. Select ‘Save’ to save the overall Nutil project (i.e., “sl24st19.nut”).
SECTION: Nutil
78. Name each project using the following naming convention: ‘sl#st#_classifier_left/right’.
SECTION: Nutil
79. Set the ‘Segmentation folder’ to the ‘Input’ folder within the QVN folder.
SECTION: Nutil
80. Set the ‘Brain atlas map folder’ to the ‘Atlas’ folder within the QVN folder.
SECTION: Nutil
81. Select ‘Reference atlas’ to the ‘Allen Mouse Brain 2017’.
SECTION: Nutil
82. Set the ‘XML or JSON anchoring file’ to the ‘VisuAlign JSON.json’ file.
SECTION: Nutil
83. Set the ‘Output folder’ to the ‘Output_left’ or ‘Output_right’ folder within the QVN folder depending on which hemisphere you are running.