ABBA - Aligning Big Brains & Atlases

ABBA is a set of software component which allows to register images of thin serial biological tissue sections, cut in any orientation (coronal, sagittal or horizontal) to atlases, usually brain atlases. It has been developed by the BioImaging & Optics Platform at EPFL

ABBA consists of a Fiji plugin for the registration part, which is best used in conjunction with QuPath. Typically, a set of serial sections is defined as a QuPath project, that is registered within Fiji. The registration results are imported back into QuPath for downstream processing (cell detection and classification, cell counting per region, etc.).

Available atlases are the 3D mouse Allen Brain atlas, and the Waxholm Space Atlas of the Sprague Dawley Rat Brain. Depending on the way you install ABBA, you may also use all BrainGlobe atlases.

---

• ABBA - Aligning Big Brains & Atlases
• Documentation
  • Installation
  • Data sources & file formats requirements
  • Example datasets
  • Creating a QuPath project for ABBA
  • Registration workflow & registration export
  • Other export modalities
  • Post-registration analysis in QuPath
  • Post-registration analysis in Python
  • Advanced documentation
    • State file & registration format
    • Javadoc
• Other forms of documentation
  • 1. Youtube tutorial
  • 2. Workshop slides
• Troubleshooting
• Frequent issues / Frequently asked questions
  • The sections are gigantic when opened in ABBA
  • I only have hemi-brain sections. Can I use ABBA ?
  • I can’t start any elastix registrations
  • I cannot see any image after I import my Qupath project
  • I want to use another atlas than the ones available
  • I can’t open my state file anymore

---

Documentation

Installation

Data sources & file formats requirements

Example datasets

Creating a QuPath project for ABBA

Registration workflow & registration export

Other export modalities

Post-registration analysis in QuPath

Post-registration analysis in Python

Advanced documentation

State file & registration format

Javadoc

Other forms of documentation

1. Youtube tutorial

A video tutorial is nice to see ABBA in action, and to check the little details which may have been missed in other documentation forms. However, be aware that, while not very different, the version presented in the video tutorial is not up-to-date with this documentation.

Also, there’s no information about DeepSlice neither QuPath post-processing in the video.

Youtube video tutorial (March 2022).

• Introduction and installation
• 0:00 Introduction
• 0:30 Installation
• Dataset definition, atlas display, and QuPath project import
• 1:27 Dataset presentation
• 2:25 Dataset definition in QuPath
• 4:58 Bdv navigation and Atlas display options
• 7:52 QuPath project import
• Description of ABBA’s interface
• 9:06 Short description of ABBA’s interface (Bdv view, table view)
• 9:56 How to display the sections + how to remove unwanted sections
• 13:46 Selecting sections in the Bdv view
• Manual registration of sections along Z
• 15:20 Translating sections along the Z atlas axis (antero-posterior position)
• 16:05 Tip: reversing section order
• 17:14 How to cancel an action
• 17:38 First key slice
• 19:19 Second key slice (+atlas cutting angle adjustment)
• 21:54 Third key slice
• 23:00 Distribute spacing between sections
• Saving your work
• 23:43 How to save your work (state file)
• 24:04 Closing and reopening from a state file
• In-plane registrations of the sections (manual & automated, linear & non-linear)
• 24:51 Introducing positioning and review modes
• 26:00 Browsing sections in review mode
• 27:15 Manual affine in-plane registration
• 29:50 Automated affine in-plane registration
• 33:28 Automated spline in-plane registration
• Review and improve your registrations if necessary
• 35:30 Browsing registration steps
• 37:30 What you can attempt to improve the registration quality
• Export results to QuPath
• 39:29 Export registration results from Fiji to QuPath
• 40:04 Import registration results in QuPath
• 42:14 How to correct a registration result with BigWarp
• 46:42 Conclusion

2. Workshop slides

A step by step tutorial that details how to register a demo dataset. Installation instructions are also linked in this presentation. Workshop slides

Troubleshooting

If you have an issue with ABBA:

1. Check first Frequently Asked Questions, and have a look at the documentation if possible.
2. Maybe your issue was already posted and fixed ? Please look at the list of questions about ABBA already asked in the Image.sc forum.
3. Still no luck? Ask for help in the image.sc forum (add abba and fiji or qupath tags). If you have already installed ABBA in your Fiji, you can also run the command ABBA - Ask for help in the forum. You will find it either in the Help menu of ABBA, or by typing ask for helpin Fiji’s search bar. With this command, some helpful information from your local installation will be included in your post (note that you will need to create an account on the forum if you don’t have already one).
4. If you feel your question is more tech / dev oriented, and you’re familiar with github, you can also open an issue.

Frequent issues / Frequently asked questions

The sections are gigantic when opened in ABBA

Most probably, your images are either not calibrated, or bio-formats cannot read the calibration. If you are using QuPath, you can override the pixel size in QuPath BEFORE opening the project in Fiji’s ABBA plugin, or, if your files are not pyramidal, you can convert your files to pyramidal OME-Tiff by using Kheops and set the correct voxel size in the conversion process.

I only have hemi-brain sections. Can I use ABBA ?

Yes, you can restrict the registration to a certain rectangular region of interest. Please have a look at this question and the answer just below. Also, there is the possibility to virtually mirror the hemi-section (check point 3). You can then register the whole ‘virtual section’, and remove the virtual extra half at the end.

I can’t start any elastix registrations

Either the elastix executable file location is not set, or you are missing a library, or you are missing some access rights. The installation of external dependencies on multiple OS is pain. To narrow down the issue, you can try to execute this groovy script in Fiji (video of how it should look here). If this did not help you solve the issue, please report the problem in the forum by using Help > ABBA - Ask for help in the forum.

I cannot see any image after I import my Qupath project

It could be because the slices are invisible by default (for faster loading). Select all the slices in the table and click on the header line to make them visible, as well as the channels you want to see, and increase the contrast if necessary. There is a step by step documentation accessible here, check from slice 53 for the display options.

I want to use another atlas than the ones available

The atlases currently available are:

• the adult Allen Mouse Brain atlas CCFv3
• the Waxholm Space atlas of the Sprague Dawley Rat Brain V4
• depending on your installation, all BrainGlobe atlases

There are other atlases, of course, but adding them in ABBA still requires some work because there is no unified way of accessing labels, properties and hierarchical structure (unless it is implemented within BrainGlobe). This is an effort I can make, but there needs to be:

1. several users needing it - and you can do your request through ABBA Help > ABBA - Give your feedback
2. If not implemented in BrainGlobe, the atlas data need to be publicly accessible and shareable. I need to be allowed to repackage it in a different file format and make it accessible through Zenodo like the other ones.
3. ABBA can’t swallow all atlases, there are a number of atlases which consists of well annotated 2d sections, but which are not fully 3D. Such atlases can’t be used within ABBA.
4. I need time.

There’s also a script that allows to create a fake atlas from an image, but no ontology is imported.

Check also this forum post if you want to do modifications to the original Allen Brain CCFv3 atlas.

I can’t open my state file anymore

This issue occurred many times. In most cases, the state can be recovered by editing the ABBA state file(s). Here are the various causes of the issue:

• files being moved around (or drive letter being changed) (post)
• entries being deleted from QuPath project after an ABBA state was created (post)
• Bio-Formats memoization storing the absolute file path of an old location
• before ABBA v0.5, the abba state was stored in three different files. Any of them missing was a problem

Any project created after ABBA v0.5+ will be less susceptible to these issues:

• an ABBA state is not split in three files anymore, but stored in a zipped file with an .abba extension. This also allows to remove some absolute path.
• when required, the absolute path is written as few times as possible, and there’s a mechanism that ask users to update their files if their location is not valid anymore.
• if an entry is removed in QuPath, the state file can nonetheless be opened in ABBA.

You should still fix first your file location in QuPath before fixing the QuPath project path in ABBA

Side note: the new state mechanism allow to share much more easily a registration between collaborators, or even with a publication. A few changes in file path, and you’re done.