README.md

Qupath Initiation

For more informations about QuPath consult the website "https://qupath.readthedocs.io/en/stable/index.html" or watch the videos in Youtube "https://www.youtube.com/c/QuPath"

Use of QuPath (version 0.4.1)

Create a project

• Press "Create project"
  

• Create an empty directory

• Select the image format compatible with Bioformat : use only 2D image in fluorescence or coloration. Z stack images are readeable but can be processed only slice by slice with specific script

• Select the images with "Add images" or drag and drop directly the images in the software.

• By double-clicking on the selected image, a "set image type" window opens. Select the appropriate image type ("fluo","HE",..).

• To reopen the project, click on "open project" and select "project.qpproj" or drag and drop the project files directly into the sofware. You can also affiliate the file to QuPath with the option "open with". If you lose all the data in your file it is possible to recover them with "project.qpproj.backup".

• You can move the directory of your project, if the images are in the directory of your project, you will have to update the URL of the image which is displayed in red in the "Image" tab, just double click it to update it. By right-clicking on the image, you can open, delete or rename it. You can also add notes using the "Edit Description" function. Or create a folder with the name of the starting image using the "Sort By" -> "URI" option.
  

Properties of the image

The "image" tab allows you to see the properties of the image. Like the name, the file, the pixel size, the dimensions...

Image specific keys 

: Allows you to make the left interface appear or disappear

: Allows you to move image in all directions. You can also use the mouse scroll wheel for zooming.

: Select the channels and their brightness/contrast. You can change the channel name by double-clicking on the top or by using a script.

• Write the channel name as a "notepad or word" on the separate line.

• Copy the lines and select all channels at once and press "Clrl+V"
  

• In the "Annotation" tab, there are classes, you can press the three small dots at the bottom right of the column and select "Populate from image channels" to create classes names from your channel.

• The initial names of the channels are not lost, if you press the "Image" tab, and double-click on "Metadata changed" you can reset the names back.

• To get the optimal intensity, you can play with "Min display" or "Max display". The "Gamma" allows you to amplify low intensity signal.

: By pressing this key, you can see the whole image and freeze it. If you want to move again or to zoom, you have to press the button again.

: Display the overview image in the top right corner.

: Displays the position and intensity of the mouse position in the lower right corner.

: Displays the measurement scale in the lower left corner.

: Positioning a grid over the entire image.

: Set software preferences (live width detection...).

Create annotations

By default, Qupath work only on current/selected annotation. If you want to create a full image annotation, you can use enter ctrl maj A.

There are 3 different objects created in this software: annotation (region of tissue); detections which are a mask (nucleus or whole cell depending which channel you process) ; and cells which is a mask of the whole cell containing three compartments : nucleus, cytoplasm (or membrane) and the whole cell.

The "Annotation" tab allows you to see the annotations you have created. To change the name and colour of the annotation, simply right-click on the annotation and click on "Set Properties". On the right side of the toolbar you see different classes defined by default. The class "None/Unclassified" shows the unclassified cells (by default) and "Ignore" is the class corresponding to the unclassified objects (below the threshold) after the classification process. You can add classes corresponding to cell classes (LT, LB,..) or annotation classes (tumour, follicles). You can also "lock" the annotation so that it cannot be modified.
When you select an annotation and a class and then click on "Set class", your annotation will belong to this the class.
With the three dots you can Add or remove an annotation, remove all the annotation except those used, export the channel name, or show/hide the classe selected (space bar can do it).

Annotation function keys

: Draws a rectangle annotation. (This annotation is saved in the "Annotation" tab). When this annotation is yellow, you can move it, but when it is red, you cannot move it unless you double-click inside.

: Ellipse annotation.

: Create a line

: Create a polygon. Double-click when finished.

: Creat a polyline annotation, either by clicking individual points (with double-click to end) or clicking and dragging

: Create an area with rounded corners. When you draw a large circle, you can fill inside the circle.

: Click and drag to draw with a wand tool. Adjust brightness/contrast or wand preferences to customize the sensitivity and behavior, (wand sensitivity or smoothing).

: Count mannuly cells of the same class. If you want to count cells of another class, you can press "Add". You can save the list of points.

: When this option is selected, it allows the protection of pre-excited annotations and prevents the creation of other annotations.

The three dots or right click on annotation have different functions:

• Unlock: allows the annotation to remain unchanged
• Insert in hierarchy: the annotation is integrated into another annotation (if inside).
• Edit single: "Make inverse" allows to create a complementary annotation of a child annotation from the parent annotation

When several annotations are selected, a new function is available: "Edit multiple" :

• Merge selected : merge the annotations
• Substract selected : allows you to substract two annotations (take care in which order you select annotations)

• Intersect selected : only the region in common will remain

Note : Ctrl Z will reset the last operation

Visualisation of the object hierarchy

The "Hierarchy" tab displays the different object hierarchies, the number of objects present in the different annotations and the object class:
A region included in another region is considered a child annotation. Resolving the hierarchy creates the hierarchy between the annotations

Workflow

The "Workflow" tab allows you to see the different functions used during your session. You can create a script with the different options.

Command menu

File

• Recent project : Open the recent project
• Save : It is important to save your project every time, when you change the image you get a message to save
• Export snapshot (main window content)
• Import objects and export objects (annotation, detections) in format Geojson

Edit

• Undo (Ctrl Z)

Tools

• As in toolbar

View

• Multiview : Insert columns or rows to view images at the same time, you can also do this with a right-click
• "Show channel viewer" allows you to see the different channels at the same time but separately
• "Rotate image" allows you to rotate the image
• Select what you want to see when there is a cells detection "Cell display - Nuclei only - Nuclei and cell boundaries - Centroids only", you can also do this with a right-click

Object

• Delete all the selected object or just annotation and detection
• Select object by class
• In the option "Annotation" you can do more :
  -"Specify annotation" : Create annotation (rectangle or eclipse) with your own mesure
  -Insert into hierarchy just the selected annotation, or resolve hierarchy of all annotations
  -Duplicate or expand/erode an annotation
  -Merge annotation together or split
  -Modify the shape with "Simplify shape" by creating a polygon

Measure

• "Show measurements map " : Assign a colour to cells or detections for measurements (area, distance,...)
  

• "Show measurement manager" : Choose the parameters to measure

• Show annotation measurements or detection measurements

• "Grid views" -> "Annotation grid summary wiew" : See the differents annotations, and the number of detection inside

• "Export measurement" : export the annotations or detections measurements in csv

Automate

• "Show script editor" : create a script or drag and drop an already created script
• You can also import a script directly into the software or drag and drop. Some script need extansion programme in Java. Jar file can also be dragged and drop and will be installed in the extension folder.
• The "Run in project" function allows to run the script on all your images.

Analyse

• "Cell detection" : you can create detections or cells (cell expansion > 0)

- "Positive cell detection" : create cells that belong to the "Positive" class
- "Subcellular detection" : detection of subcellular objects in cells  

• Spatial analysis (distance cells to annotation,..)

• Create a "Density maps" from detections and finally an annotations by thresholding the maps

Classify

• "Object classification" : Allows to classify detections/cells
  
• "Pixel classification" : pixel thresholder or pixel classifier to create automaticaly annotations

Extensions

• Combined extensions with QuPath like Cellpose

Help

• Documentations

  Fonctionnel keys

: Shows only the selected annotation(s).

: Displays the name of the annotations. To name an annotation, you need to go to the "Annotation" tab and double-click on the annotation, then select "Set properties" and change the name.

: Shows the TMA grid in the viewer.

: Shows the contours detections or cells.

: Fills in detections or cells.

. Shows pixels classification in the overlay.

: overlay opacity (detections,..).

: To view measurements of TMAs, annotations or detections and also histogram, save in "txt".

  Shortcut keys  

• When you click into (1,2,3...) you can choose the channel
• When you click into top or down arrow you can choose the Z-stack
• When you click into a letter you can choose the type of annotation :

ALT Key :

• When the Move tool is selected, use the Alt key to click on multiple objects to select them.
• When the Brush or Wand tools are selected, use the Alt key to switch to 'eraser' mode when drawing

Shift Key :

• When the Brush or Wand tools are selected, use the Shift key to continue adding to an existing selected annotation (rather than creating a new one).