Documentation of the Aligning Big Brains & Atlases Fiji plugin.
Once your dataset is opened in ABBA. You will be able to position slices first along the slicing axis (position multiple slices along “z”), then to perform 2d adjustment for each slice (tilt and roll atlas slicing correction, 2d affine and spline in-plane registrations).
When you start ABBA, you will be in the Positioning mode
, where the Allen brain atlas is displayed with slices regularly spaced on top of the slices present on your dataset.
trackpad
aficionado, the interface is much easier to use with a mouse
The way ABBA works is by acting on selected slices and by performing actions on them. Each slice has a round handle which serve to indicate if it is selected (green) or not (yellow).
There are two ways of selecting slices:
shift
) or remove (ctrl
) slices to the current selection:
hold and left-click
draw a rectangle to select slicesctrl + hold and left-click
remove slices from the current selectionshift + hold and left-click
add slices to the current selection you need to hold the modifier keys BEFORE drawing the rectangle in order to take their effect into account.
Gif below : adding slices to selection using shift+rectangle
, removing from the selection with ctrl+rectangle
, finally selecting all slices with ctrl+a
.
Slices Display
card table:ctrl+a
allows to select all slices, ctrl+shift+a
allows to deselect all slices. For mac users, you may need to use cmd
instead of ctrl
.
It will be convenient for the registration to have your slices properly displayed. Depending on your use case, you may want to display a subset of the available channels, and adjust the min and max value displayed for a good contrast.
But first, in multi series files like vsi files it could happen that you end up with unwanted images (label or macro image). In this case, you will need to remove these slices. For vsi files, these unwanted images, because they are rgb images, appear black in the slice display table. It is thus easy to select them. The selected slices can then be removed form ABBA by right clicking in the viewer window of ABBA and selecting Remove Selected Slices
(also accessible in the menu bar : Edit > ABBA - Remove Selected Slices
).
Usually, slices will have multiple channels, autodetected by bio-formats, but while some channels will be useful for analysis, some will be useful just for the sake of registration to the atlas. In order to display only certain channels, you can activate or deactivate the display of selected slices by clicking on the header of the slice display table:
You can set the color and the min and max display values of these slices:
If needed, the display of each slice can be customised by modifying the corresponding line in the table.
This procedure starts first by a manual step, which has two goals:
warning: If your slices are of sufficient quality, do not forget to check ABBA’s DeepSlice integration in order to skip the initial manual registration steps.
In order to position each slice approximately along the slicing axis, ABBA tries to provide a convenient interface to manipulate series of slices.
It could happen that the acquired slices were flipped or rotated compared to the atlas. The tab Edit Selected Slices
provides 4 actions which can be used to correct this:
The first two buttons rotate selected slices by 90 degrees CW or CCW. The next two buttons flip slices vertically or horizontally.
Contrary to a lot of other actions in ABBA, these actions (flip rotate) are not undone with ctrl+Z
(and redone with ctrl+shift+z
). These actions can be easily reversed by applying an opposite rotation / flip.
In the top menu bar Edit>ABBA - Interactive Transform
can be used to apply a transformation on the selected slices. You can rotate, translate and scale anisotropically the sections (which are often shrunk in Y by about 20 % because of the slicing).
This can be convenient if you need a fast visual feedback to the transformations you are applying. Simply close the Interactive transform
window when you are satisfied with the result. This also works in review mode or with a different overlap mode, if you want to be more precise.
Contrary to a lot of other actions in ABBA, this interactive command cannot be undone with ctrl+Z
(and redone with ctrl+shift+z
). However, you can restore the original transformation if you click the Restore initial settings
button.
Before any registration can be started, you will need to position the slices along the Z axis, and also correct the atlas slicing angles to match those of your dataset. The atlas slicing angle will be the same for all slices, which is the reason why it’s convenient to register one animal at a time.
First of all, it may happen that your slices are not sorted correctly along the atlas axis. If this is the case, you can select slices which are not at their correct position and drag them along the axis. You can create some interval if necessary in between two slices in order to let others in between if needed.
You can select one or several slices and then, by dragging the rectangles located below the atlas, you can shift selected slices along the slicing axis:
In order to apply the same spacing between each selected slices, you can either click the button distribute spacing
in the card Edit Selected Slices
or press the shortcut key d
. This action, as many other, can be cancelled by pressing ctrl+z
and redone by pressing ctrl+shift+z
:
When no slice is a key slice ( see next section ), distribute spacing
keeps constant the position of the first and last selected slices.
By using ABBA interface, you will be able (and will need), to switch between a zoomed-out overview and a zoomed-in view where you look precisely at how a particular slice matches the atlas.
Generally, to align the position of slices along the atlas, a convenient workflow is the following:
key slice
(select this slice only, right click and select Set as key slice
in the popup menu). As long as you don’t drag this slice, each key slice has its z position locked in the atlas: Distribute Spacing
won’t affect the position of key slices.Distribute spacing
Automatically, the position of the slices within the dataset will be adjusted to the new atlas slicing. It’s important to understand that the slicing spacing currently displayed does not affect the registration in any way. Internally, all slices all positioned with 10 microns precision, corresponding to the atlas highest resolution.
This coarse display allows, by dragging slices, to adjust approximately all slices along the atlas.
Then, you can zoom in, drag slices until you find a corresponding slice between your dataset and the atlas.
It’s possible, once a matching atlas slice is found, to select the slice of interest and set it as a Key Slice (right-click menu), as shown below:
When key slices are selected, they will keep their position along the axis when other slices are dragged (you can still directly drag the key slice if you need to move it). The other slices are stretched along the axis while maintaining their spacing ratio.
You can set multiple key slices in specific positions along your sections, usually the ones with the most recognizable features.
2 or 3 key slices can be sufficient for a correct positioning along the atlas axis. The distribute
button or action will equalize spacing between selected slices while respecting the position of selected key slices (and the position of the first and last selected slices).
In the positioning mode used so far, it is easy to move slices around, but it is not convenient to overlay the sections to the atlas.
It is possible to switch to a review mode by either:
Review
in the card Display&Navigation > Modes
Display > Review Mode
In this mode, a single slice is displayed at a time overlaying the atlas. The slice which is being displayed is the current slice. The current slice is indicated by a white circle around the slice handle.
You can navigate along the slices by pressing the left and right arrow keys or by pushing Previous
and Next
in the Display & Navigation
card.
If you notice a problem in the review mode, you can switch back any time to the positioning mode
in order to correct the slice position or the atlas slicing angle.
Right
and Left
key to change the current slice also works in the positioning mode.
A card named Atlas Slicing
contains two sliders which allow to tune the atlas slicing angles:
You can use slices with recognizable features to orient the atlas slicing. The atlas slicing angles will identical for all sections. It is possible to tilt the atlas, but not to “bend” it.
If you are using the Allen Brain Atlas and registering coronal sections, you can use DeepSlice to automate this first part of the workflow.
Once the slices have been correctly oriented and positioned along the slicing axis, they can be registered to the atlas in 2D, linearly or in a non-linear way.
For automated registration, ABBA uses elastix with pre-defined registration parameters and takes advantage of its knowledge of the sections’ calibration as well as on the atlas physical voxel size in order to have an almost parameter free registration. The metric used to measure the ‘distance’ between fixed and moving image is the Mattes mutual information metric, which should allow for reasonable results when registering different imaging modalities.
If your image file format does not contain multiple resolution levels (level of details (LOD), pyramids, multiresolution), ABBA will not downsample cleanly the image and this could result in bad registration results. You can click
show registration results as ImagePlus
in order to visualize how the slice and the atlas are downsampled for registration.
For manual registration, ABBA calls Fiji’s BigWarp plugin.
When a registration ‘job’ is started for a slice, an indicator of the registration state is added below the slice handle. Its shape is round for an automated registration, and rectangular for a manual registration. This indicator is initially red when the job is not started, orange when it is being processed, and green when the registration is done.
You can start the registrations for all slices in parallel. Depending on your computer, between 4 and 32 registrations will be started in parallel (click on the menu Cards > Add resources monitor
and check the Resources monitor
card to see how busy is your CPU). You can continue browsing ABBA during the registrations, which are processed asynchronously. As soon as any registration is done, its result is displayed in ABBA.
Below: registration of 80 sections, with, for each slice the following registration sequence:
(real time ~ 10 min)
It is possible (and advised) to perform several successive registration. You will usually start by an affine registration followed by one or two spline registrations. For ‘difficult slices’ where the automated registration result are bad, you can either start by a manual registration to facilitate a following automated registration, or, alternatively, you can directly edit the result of a spline transform, in order to improve it and even to add landmarks in regions in which you are more interested.
If once or several slices are broken into pieces, achieving a good result over the whole slice could be really difficult or impossible. ABBA does not deal well with discontinuous deformations.
You can select the slices you want to register and start an affine registration by clicking, in the top menu bar:
Align > ABBA - Elastix Registration (Affine)
.
You will need to select one or several channels for both the atlas and the sections for this affine registration.
In a lot of cases, an affine registration on the DAPI channel of your sections vs the atlas Nissl atlas channel (0) is a good choice for a first registration.
Multichannel registration is also supported. Each channel contributes equally to the ‘cost’ function that is optimized for the registration. It is not rare to have a channel which is autofluorescent as part of a dataset. This will be good idea to register to the ARA channel of the Allen Brain Atlas. But what is even better is use several channels at the same time. For instance, in the first test dataset of the documentation, the channel 0, DAPI, matches the Nissl channel, while the channel 1 has significant autofluorescence, thus matching channel 1 (Ara) of the atlas.
Here’s how to set up a registration taking both channels into consideration:
If you have several channels matching a channel from the atlas, you can repeat the atlas channel. You can even repeat one of your data channel if needed. Suppose your channel 1 and 3 are both nuclear signals, you could fill in the registration parameters like this:
A few extra options are available:
Registration re-sampling (micrometers)
specified in micrometer, is the pixel size of the images that will be send to Elastix for the registration task. Check Show registration results as ImagePlus
to see how the resampled images look like.Show registration results as ImagePlus
, if checked, will display the raw data used for elastix registrationBackground offset value
can be left at zero in most cases. If your camera has a significant zero offset value in comparison to the channel intensities, this offset can be specified here for a better registration.You can select the slices you want to register and start a spline registration by clicking, in the top menu bar:
Align > ABBA - Elastix Registration (Spline)
In spline registration, a grid of size “Number of control points along X
” is used to perform a spline registration between selected slice and the atlas. Again only a single channel registration is supported.
It is advised to use a value for control point between 5 (25 max total number of landmarks) to 20 (400 max total number of landmarks).
BigWarp can be used if you want to have a full control over the registration. This method allows to place your own landmarks manually. Since this method is manual, slices are processed sequentially by the user.
When the last registration of a slice is either a BigWarp registration or a spline registration, the result can be manually edited by selected the slice and then clicking in the top menu bar Align > ABBA - Edit Last Registration
.
if you select a lot of slices before clicking Edit Last Registration, each editing will be launched successively. If this is what you want, great! Otherwise, take care.
This editing will launch BigWarp interface in both cases, but with landmarks from the previous registration already put in place. Using BigWarp’s standard commands, which are summarized below, you can move these landmarks or even add new ones. Click the window when you’re done editing the transformation, and the new result should appear in ABBA window (take care, the editing cannot be canceled!).
BigWarp commands summary:
space
= toggle for landmark modectrl + left click
= pin a new landmark on both the fixed (atlas) and the moving (section) image.drag + left click
= in landmark mode, drag an existing landmarkf
= display fused transform and fixed image (toggle)t
= transform the image or not (toggle)You can check BigWarp documentation for more information about its interface, or look at the relevant part in the youtube tutorial.
After editing a registration, you can export it again (to QuPath for instance), and reload it.
If you are not happy with the result of a registration, you can select the slices where you want to remove the last registration, and:
Align > ABBA - Remove Last registration
Remove Last registration
This removal can be cancelled.
If you want to investigate quickly the different registration steps, you can click in the card Display & Navigation
: Browse: View Previous [P]
and View Next [N]
. Note how the registrations indicators are switching from green to gray when they are ignored in the display.
The registration methods (BigWarp, Elastix spline, affine…) are plugins automatically discovered by ABBA. While the documentation is lacking for the moment, it is possible to make a registration plugin of your own and use it in ABBA.
A typical registration may be obtained using the following successive steps, performed on all slices:
This takes about 10 minutes for 50 slices on a laptop.
At each step of the workflow, you can save the current state of your work (as long as no job is being processed).
To save your project, you can click, in the top menu bar File > ABBA - Save State (+View)
. An .abba
extension will be automatically added to the filename. This abba file in fact a set of text files zipped together.
All files are text files, which are fast to save and rather small (in comparison to the images…). So do not hesitate to save multiple successive files all along your workflow. Consider your work done when you have obtained regions in QuPath, but the ABBA state file has less guarantee on the long term.
To open a project where you left it, it is compulsory to close ABBA session and restart it. Once restarted, click in the top menu bar File > ABBA - Load State (+View)
, and select your previously saved .abba
file.
If you move your image files, your qupath project, or the other files associated to the state file, ABBA may not be able to find your images because absolute file path are used. If you opened images from a QuPath project, fix URIs in QuPath first before reopening ABBA.