QuPath BraiAn extension

Extends QuPath's functionalities 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 brain atlas annotations from ABBA
• braian: the associated python library for whole-brain analysis and visualization

YSK: BraiAn's names stands for Brain Analysis.

I suggest you to listen to "Brianstorm" by Arctic Monkey while working with BraiAn ;)

Features

This extension 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!

Citing

If you use BraiAn in your work, please cite the paper below, currently in pre-print:

Important

Chiaruttini, N., Castoldi, C. et al. ABBA, a novel tool for whole-brain mapping, reveals brain-wide differences in immediate early genes induction following learning. bioRxiv (2024). https://doi.org/10.1101/2024.09.06.611625

Installation

Using QuPath Catalogs

This is only possible in newer QuPath versions (0.6.0, or newer):

• Open QuPath extension manager by clicking on Extensions > Manage extensions;
• Click on Manage extension catalogs;
• Paste the following URL and click the Add button: https://github.com/carlocastoldi/qupath-extension-braian-catalog;
• In the extension manager, click on the + symbol next to BraiAn extension.

This new installation method for third-party extensions was introduced in QuPath to help users keep them up to date.

Manual

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 drag the downloaded file onto QuPath, restart and be good to go!

Up until QuPath 0.5.1 (included), new extension releases are notified by QuPath on startups. You'll then be able to update them through QuPath's extension manager with one click.
From QuPath 0.6.+, extensions installed manually no longer receive updates.

Contributing

We decided to publish the BraiAn pipeline (i.e. this QuPath extension and the twin python libray) with the most libre licence possible because we find maximum value in learning from others and sharing our own—small—knowledge.

We, developers in neuroscience, are islands that often work alone and frequently end up reinventing the wheel rather then spending time finding, pickup up and adapting the work that somebody, from the other side of the world, did with no intention to publish. For this reason we spent a great amount of our personal time making the modules as usable, extensible, and long-lasting as we could. And yet, we know it could be better, that there could be bugs, unforeseen scenarios and missing features.

For this reason we hope that, if you find our work useful, you will find time and will to contribute back upstream with issues, PRs, documentation, tests, feature requests... Any activity makes us happy!

Building

You can build the QuPath BraiAn extension from source with:

./gradlew clean build

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