BraiAn for QuPath

The first module of BraiAn, also known as BraiAnDetect, consists of a QuPath extension for image analysis of serial brain sections across many animals. It is designed for multichannel cell segmentation across large and variable datasets and ensures consistency in image analysis across large datasets. This module leverages QuPath's built-in algorithms to provide a multi-channel, whole-brain optimised object detection pipeline. BraiAnDetect features options for refining signal quantification, including machine learning-based object classification, region specific cell segmentation, multiple marker co-expression algorithms and an interface for selective exclusion of damaged tissue portions.

It works best if coupled with qupath-extension-abba for importing whole-brain atlas registrations from ABBA as annotations.

Features

BraiAnDetect helps you manage image analysis across multiple QuPath projects ensuring consistency. In particular, it is designed to perform batch analysis across many QuPath projects in an automated manner. Typically, in whole-brain datasets, one brain = one QuPath project and BraiAn makes sure the exact same analysis parameters are consistently applied across different projects. It was first developed to work with ABBA, but can be used for other purposes as well. Its core idea is to move the input image analysis parameters used to analyse multiple QuPath projects of the same cohort/experiment outside of scripts' code (in a YAML configuration file, see below). This allows having a reproducible configuration that can be shared, backed up and ran after long periods of time.

The extensions exposes a proper library API. Here are some examples. It allows you to:

• multi-channel automatic object segmentation (e.g. cell detections)
• machine-learning-based object classification (e.g. apply custom classifiers on different detection types).
• co-localization analysis (i.e. quickly find all detections that are double—or triple/multiple—positive, through BoundingBoxHierarchy)
• fine tune image analysis using channel histograms
• tag certain brain regions to be excluded from further analysis due to tissue, imaging or alignment problems
• export to file the quantification results (number of detections/double+ found in each brain region)
• export to file a list of regions flagged to be excluded

Where to start from, though? Reading this script and the associated config file is a good start!

Installation

You can download the latest release from the the official GitHub page of the project named qupath-extension-braian-<VERSION>.jar. Generally, there is no need to download -javadoc.jar and -sources.jar.
Later you can simply drag the downloaded file onto QuPath, restart and be good to go!

Any new available release of the extension should be notified on QuPath startup, and its update can be handled in QuPath itself.

Getting started

This extension does not currently expose any user-friendly interface, but it mostly offers a set of functions and prebaked scripts that should be easily modifiable from someone with little programming knowledge.

Prebaked scripts

Once you installed the extension, you can load prebaked scripts by clicking on the top menu: Extensions ‣ BraiAn ‣ scripts.

The very same ones can also be checked out from the official repository:

• compute_classify_overlap_export_exclude_detections.groovy: this script reads the YAML configuration file and applies all of its parameters.
• find_threshold.groovy: suggests a threshold to apply with WatershedCellDetection algorithm by choosing a local maximum from the image's histogram.
• run_script_for_multiple_projects.groovy: helps running a script for multiple project at once. It is compatible with the LightScriptRunner.

However, before running any script using this extension, we need to describe how BraiAn works and its assumptions.

Project arrangement

All the brain section images of the same animal should be collected into a single QuPath project. If there are multiple animals, one should create a project for each one of them and save the respective project folders in the same directory (e.g. QuPath_projects/).

Classifiers

When you can't find parameters to automatically segment your markers that are satisfying for all sections and animals of the groups, you might want to try applying an object classifier that filters out the detections that are not correct. In this case, the detection should first be computed with highly permissive parameters that don't miss ~any positive cell; even at the cost of having a high number of false detection: it will be the classifier job to filter them out.

If you don't know how to create an object classifier in QuPath, we suggest you to read the official tutorial. Once the classifier is sufficiently accurate, you can save it and QuPath will create a .json file in <QUPATH_PROJECT>/classifiers/object_classifiers/.
For it to be read by BraiAn, copy it in the same location where the YAML configuration file is.

Configuration file

BraiAn for QuPath can use a YAML configuration file. This configuration file contains all the customizable image analysis parameters in one place and thus allows to apply the exact same signal quantification settings across all projects (i.e. animals) and runs. In addition, this is the place image analysis details are stored and is great to keep track of how the analysis was done even after a long time. The file has to be positioned either in a QuPath project folder or in its parent directory (e.g. QuPath_projects/), depending on whether the analysis is meant for a specific project or multiple ones.

For a detailed explanation on how to format such file and understanding what each parameter does, we suggest to look at this example YAML file.

Detection containers

Managing large numbers of detections that have been computed across many brain regions and channels can be challenging. BraiAnDetect is designed to facilitate this step and prevent classical errors (such as detections computed over overlapping annotations or detections of different image channels colliding in the same area).
To handle annotations derived from multiple channels, BraiAnDetect uses what we call detection containers (or just containers). Containers are QuPath annotations that contain detections computed on each specific channel and belong (in QuPath annotation hierarchy) to the parent annotation containing all detections. If two containers of the same channel overlap, only the detection from one of the two will be kept to avoid having double the cells.

In addition, BraiAnDetect allows you, for each channel, to select a specific subset of annotations in which any image analysis algorithm is run. This allows you, for example, to create AbstractDetections using different parameters for different subsets of brain regions. This is done setting different object classification to each annotations subset.

Region exclusions

Sometimes we would like to discard some parts of a section—be it for problems with the tissue, imaging or registration to an atlas—but we would still like to keep some portions!

In this case you can draw an annotation over the desired portion to exclude from the analysis, making sure that it completely covers the atlas annotations below. This can be done using the Polygon tool or duplicating an atlas annotation (Shift+D) and classifying them with the ad-hoc QuPath classificat·on for the exclusion annotations: "Exclude" (see Fig. 1).

If you want to make sure that you excluded all brain regions you wanted from an image, you can click on Extensions ‣ BraiAn ‣ Show regions currently excluded and see which regions from the atlas have been selected.

Output

AtlasManager.saveResults() and AtlasManager.saveExcludedRegions() will export the data from cell counts and exclusions to a file for each image.

Building

You can build the QuPath BraiAn extension from source with:

./gradlew clean build

The built .jar extension file will be under build/libs.