TITLE: QuPath to SCiLS instructions
AUTHORS: Naina Beishembieva, Brittney Gorman, Christopher R Anderton

[DESCRIPTION]
Matrix-assisted laser desorption/ionization mass spectrometry imaging (MALDI-MSI) is an analytical technique which provides the molecular composition directly from cells, tissues and organs. To provide biological context for these molecular maps acquired with MALDI-MSI histology or immunofluorescence is performed on the same or an adjacent tissue section. Methods for alignment, segmentation, and data analysis are required to extract molecular data from various regions within the MALDI images. We have developed a workflow to combine QuPath data and MALDI-MSI data in SCiLS. This data can be then exported to R for statistical analysis to study upregulation/downregulation of certain cell types at the areas of interest. 

QuPath is an open-source software for digital pathology and whole slide image analysis. It allows for the annotation of tissue functional units and immunofluorescence stains. SCiLS (Bruker) is software for analyzing mass spectrometry imaging data. By combining QuPath segmentations with MALDI-MSI results, we are able to obtain the molecular composition of specific tissue functional units or immunofluorescence signals. It is also possible to combine metabolite annotations obtained from the open-source annotation platform METASPACE. 

Part 1 QuPath to SCiLS (instructions on QuPath): 
The process of the tissue annotation according to the immunofluorescence channel or by manual selection of tissue functional units in QuPath, as well as the export of this data into a file that can be recognized by SCiLS.  

Part 2 QuPath to SCiLS (instructions on SCiLS): 
The process of importing the data from QuPath (annotated tissue functional units or areas of interest) and METASPACE annotations (annotated molecules from mass spectrometry images) to SCiLS, as well as the alignment of images from mass spectrometry and microscopy in SCiLS. This will allow for the further export of all the data from SCiLS to the R (SCiLS API) where statistical analysis can be performed to compare the molecular abundances in segmented regions.  

[BEFORE_START]
Install QuPath

[STEPS]
SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
1. Install QuPathtoSCiLS extension
SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
1.1. Open QuPath 
Find file "QuPathToSCiLS-1.4.jar".
My pathway is: C:\Program Files\SCiLS\SCiLS Lab\QuPathPlugin
SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
1.2. Drag the QuPathToSCiLS-1.4.jar file onto the running QuPath window
SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
1.3. If QuPath displays a message that the extensions directory is not specified accept the 
default or specify a different location.

SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
1.4. There should now be two entries “Export annotations to SCiLS Lab” and “Import 
annotations from SCiLS Lab” under QuPath Extensions:


 
If the entry does not show up restart QuPath.

SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
2.  Annotate files in QuPath either using tools to annotate such as magic wand (for example, when annotating H&E tissue)
 
or using thresholding for channels (for example, when have cyclic IF on the tissues)
SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
2.1. Note (if using stained tissue): 
 

 


SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
2.2. Thresholding:
Classify >Pixel classification > Create thresholder
The following window will show up:

 
Then after this window was filled out, press: Create Objects > in the new window at the drop-down menu select either full image or all annotations (if selected only specific area of the tissue for the annotations) > at the next window press "OK" (Note: minimum object size can be changed from 0 to a pixel size IF those are not necessary for thresholding, then it will only mark cells larger than a size you have entered)
The annotation can be now checked here:

 
Important tip:
When choosing resolution of your annotation, to make sure your file can be exported, try to use the lowest resolution that yet produces good results of annotation

SECTION: Part 1. QuPath to SCiLS (instructions on QuPath)
3. After completing all annotations, go to Extensions > Export annotations to SCiLS lab
Save file
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
4. Open SCiLS lab (Premium)
Press New FIle
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
4.1. Import/choose ImzML file 
Press Next
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
4.2. Page "Mass axis settings" must appear
Check: bin size (it must match the bin size indicated in Metaspace -> dataset overview -> m/z tolerance (ppm) value will indicate the bin size. If the value is not the same as in Metaspace, unselect automatic and adjust this value
Change: constant type must be MRMS (Fourier - transform)
Press Next, then Import, name new SCiLS file, press save, press open imported file
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
5. Press File -> open -> choose the new created file from a previous step -> press open
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
6. Press File ->  Import -> choose Region SCiLS Exchange Format -> choose here your annotated in QuPath file
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
6.1. The window with two pictures imported must appear  – one from MSI and from QuPath (note: it will not appear annotated here)
Press Next
It should now redirect to Image Co-registration page (provides instruction on the right side of the window)
After they are well aligned, press Next (good alignment is very important for precise results)
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
7. It will ask to select all needed regions from the list of annotation we have made in QuPath (usually need to select all of them)
Important: check the box "select new region" -> name it
Press Finish (now the annotations of channels or anything is imported and appear in regions section of the main window)
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
8. Press File -> Attribute Editor -> Press "Settings" icon
Select "Use as a region" for your annotations
Close
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
9. Press File -> Import -> Feature list from file (flexImaging, MetaboSpace, SCiLS, CSV, TLST)
Choose file (for example, file imported from Metaspace as CSV) -> Open
Select m/z column and Name column -> press Import
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
10. Go to Feature list at the right side of the screen (At the bottom of the Visualization tabs)
Choose your file that you imported (for example, csv from Metaspace) -> press the globe icon
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
11. Finally, the data now can be found at Ion Images 
SECTION: Part 2. QuPath to SCiLS (instructions on SCiLS)
12. Now that all data is gathered at SCiLS lab, the statistical analysis can be done in R (code provided, follow the instructions provided in the code)