AIDAmri

Atlas-based Imaging Data Analysis Pipeline (AIDA) for structural and functional MRI of the mouse brain

Please read this README completely before using AIDAmri. Here you will find the detailed user manual.

Key Features of AIDAmri

1. Automated Preprocessing
   It performs tasks like image re-orientation, bias-field correction, and brain extraction with minimal user input required.

2. Atlas-Based Registration
   AIDAmri uses the Allen Mouse Brain Reference Atlas for accurate region-based analysis of MRI data, allowing researchers to compare results across different studies efficiently. A modified atlas version with larger labels to better match MRI resolution is provided. Users can define specific regions of interest (ROIs) for analysis, such as stroke lesions.

3. Modular Design
   The pipeline is developed in Python, making it cross-platform and open-source, allowing for easy integration and modification.

4. Validation
   The pipeline was validated with different MRI datasets, including those involving stroke models, demonstrating its robustness even in the presence of significant brain deformations.

5. Functional and Structural Connectivity Analysis
   The output of the pipeline includes connectivity matrices that can be used for further analysis of brain network changes in health and disease.

Pipeline overview from Pallast et al.

Version history

Information latest Version 3.0

Information about Version 2.0
Information about Version 1.2 (Docker stable release)
Information about Version 1.1.1 (Docker pre-release)
Information about Version 1.1 (Stable)
Information about Version 1.0

BRANCHES

AIDAmri is organized into multiple branches to support development, collaboration, and species-specific adaptations:

• main – the stable branch containing officially released and validated versions of AIDAmri for mice.
• open-dev – the public development branch that can be used by external contributors to implement code modifications, enhancements, or bug fixes.
  Researchers and developers are welcome to fork the repository, work within the open-dev branch, and submit pull requests for review.
• rat – a dedicated branch for rat MRI data, including modified atlas and template versions optimized for rat brain imaging and analysis. Note: that this branch is based on AIDAmri version 2.

Each branch is continuously synchronized to ensure compatibility with the core AIDAmri framework and Docker-based environment. Use git switch to change between branches:

git switch rat

EXAMPLE FILES

Download the example dataset here. You can test AIDAmri using either the raw_data folder or the already converted nifti folder. The results can then be compared with the preprocessed data provided in the proc_folder.
Mouse MRI data, acquired with Bruker 9.4T - cryo coil setup: adult C57BL7/6 mouse, T2-weighted (anatomical scan), DTI (structural connectivity scan), rs-fMRI (functional connectivity scan).

Data Format and Orientation Requirements

AIDAmri supports data processing exclusively for datasets in NIfTI (.nii/.nii.gz) or Bruker formats. To ensure accurate registration and reproducible results, all input data for preprocessing must be in LIP (Left-Inferior-Posterior) orientation. Furthermore, the image header information must be consistent with the physical orientation of the data array. Any mismatch between the header orientation and the actual voxel layout can lead to registration errors or incorrect alignment with the atlas. It is therefore strongly recommended to verify and, if necessary, correct the header orientation. Please use FSL eyes for visual inspection and fslhd for checking the header information. FSL is already installed inside AIDAmri. More Information about FSL can be find here. If your data is in a different orientation than LIP please use our ReorientBatch.py script in the helpertools folder. The script should be used after convert2Nifti script and before processing any files. ReorientBatch.py can reorient the whole proc_data folder. It is important that the folder contains only the NIFTI files to be reoriented. The folder must not contain any NIFTI files that have already been processed. Furthermore, please note that after reorientation, tools such as Fiji or other tools that do not read the header of a NIFTI file will display the images only as the data was saved after reorientation. For this reason, we recommend FSL Eyes, as this tool provides more information about the orientation.

Troubleshooting / Common Issues

This section lists frequently encountered problems when using AIDAmri and possible solutions.

If your problem is not listed here, please use our Gitter Chat or open an issue on GitHub and include:

• OS
• Docker version
• Command used
• Full error log

---

Running Container Warning

ARM useres (e.g. Apple Silicon) may see the following warning when starting the conatiner:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

The warning appears because the image was built for the AMD64 architecture, while the host uses ARM64. Docker can run the image using emulation, although performance may be reduced. It can be ignored and does not affect the functionality of the container.

General debugging tips

Always process T2 data first

Visually inspect outputs after:

• Bias correction

• Brain extraction

• Registration

Check logs instead of relying only on exit codes

NIfTI orientation problems

Symptom

• Atlas is flipped or registration fails

• Brain appears flipped or rotated

Explanation

AIDAmri expects LIP orientation for preprocessing.

Solution

We recommend verifying the NIfTI header information and the actual image orientation using the FSL tools fsleyes and fslhd.

In cases where the images are not in a consistent LIP orientation, the provided reorientation script should be applied after convert2nifti and prior to preprocessing.:

python ReorientBatch.py -i proc_data -o proc_data_reoriented

Docker build takes a very long time, finishes after under 1 min or aborts

Symptom

docker build hangs for several minutes or fails during apt-get / FSL installation

Explanation

• Possible causes

• Slow internet connection

• Docker build cache corrupted

• Insufficient disk space

Solution

docker system prune -a

docker build --no-cache -t aidamri:latest .

A is singular, uses pseudoinverse in updateB

Symptom

Warning: A is singular, uses pseudoinverse in updateB

Explanation

This warning originates from the MICO bias-field correction and usually indicates:

• Low SNR

• Strong intensity inhomogeneities

• Empty or corrupted slices

Solution

• Usually safe to ignore if preprocessing finishes successfully

• Check input image for NaNs, zero-only slices or low voxel values

• Verify correct image orientation before preprocessing

Brain extraction fails (SVD did not converge)

Symptom

Error in brain extraction

SVD did not converge

Explanation

• Corrupted NIfTI header

• NaN or Inf values in the image

• Extreme bias-field artifacts

Solution

• Re-run bias-field correction

• Reorient the image manually before preprocessing

• Check header consistency:

fslhd input.nii.gz

ARA CREATOR

Matlab script to generate a custom version of the Allen Mouse Brain Atlas.

CONTACT

If you encounter problems, report directly in

or

join our Open Office Hour - each Thursday 3:00 pm (UTC+2)

Please note that the Open Office Hour may not take place on public holidays in Germany.

For all other inquiries: Markus Aswendt (aswendtATmed.uni-frankfurt.de)

LICENSE/CITATION

GNU General Public License v3.0

If you use our software or modify parts of it and use it in other ways, please cite:

Pallast N, Diedenhofen M, Blaschke S, Wieters F, Wiedermann D, Hoehn M, Fink GR, Aswendt M. Processing Pipeline for Atlas-Based Imaging Data Analysis of Structural and Functional Mouse Brain MRI (AIDAmri). Front Neuroinform. 2019 Jun 4;13:42.doi: 10.3389/fninf.2019.00042.

---

REFERENCES

• Brain Connectivity Toolbox
  • M. Rubinov and O. Sporns (2010). Complex Network Measures of Brain Connectivity: Uses and Interpretations. NeuroImage 52 (3), 1059–69.
• Allen Mouse Brain Reference Atlas
  • Wang et al. (2020). The Allen Mouse Brain Common Coordinate Framework: A 3D Reference Atlas. Cell 181 (4), 936-953.
• Niftyreg
  • Ourselin, et al. (2001). Reconstructing a 3D structure from serial histological sections. Image and Vision Computing, 19(1-2), 25–31.
  • Modat, et al. (2014). Global image registration using a symmetric block- matching approach. Journal of Medical Imaging, 1(2), 024003–024003.
  • Rueckert, et al.. (1999). Nonrigid registration using free-form deformations: Application to breast MR images. IEEE Transactions on Medical Imaging, 18(8), 712–721.
  • Modat, et al. (2010). Fast free-form deformation using graphics processing units. Computer Methods And Programs In Biomedicine,98(3), 278–284.
• FSL
  • M.W. Woolrich, S. Jbabdi, B. Patenaude, M. Chappell, S. Makni, T. Behrens, C. Beckmann, M. Jenkinson, S.M. Smith. Bayesian analysis of neuroimaging data in FSL. NeuroImage, 45:S173-86, 2009
  • S.M. Smith, M. Jenkinson, M.W. Woolrich, C.F. Beckmann, T.E.J. Behrens, H. Johansen-Berg, P.R. Bannister, M. De Luca, I. Drobnjak, D.E. Flitney, R. Niazy, J. Saunders, J. Vickers, Y. Zhang, N. De Stefano, J.M. Brady, and P.M. Matthews. Advances in functional and structural MR image analysis and implementation as FSL. NeuroImage, 23(S1):208-19, 2004
  • M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. FSL. NeuroImage, 62:782-90, 2012
• DSIstudio
  • Yeh, Fang-Cheng, et al. Deterministic diffusion fiber tracking improved by quantitative anisotropy. (2013): e80713. PLoS ONE 8(11)