Container for Brain Age Identification from Diffusion MRI (BRAID)

About

Singularity container for brain age identification from diffusion MRI (BRAID). Given a diffusion MRI image, a T1w MRI image and the corresponding brain mask, and optionally the age, race, sex of the individual (at the time of scan), this software estimates three types of brain age: WM age (nonrigid), WM age (affine), and GM age (affine, ours), each focusing on different sets of brain features, as described in Gao et al. (Imaging Neuroscience, 2025). While age, race, and sex are optional inputs, they are strongly recommended for calibration and bias correction.

All dependencies (i.e., software, packages, etc.) are pre-installed inside the container. To get the brain age estimates, users simply provide the inputs (following the structure, which will be covered in the following section) and run the container. Source code can be found on GitHub at https://github.com/MASILab/BRAID

Build and Testing Environment

The container was built and tested using a machine running on Ubuntu 22.04, with 64 GB of memory. The CPU is an Intel(R) Xeon(R) W-2255 CPU running at 3.70GHz. Moreover, the container runs successfully on computation nodes with AMD processors using the CENTOS 9 OS. 

Expected Runtime and Memory Usage

Runtime: ~3 hours. Memory usage: ~4 GB.

How to Run

Step 1: Prepare Inputs

Create a folder (e.g., “INPUTS” in our example). In the folder, have the following files (with the exact same naming):

• demog.json: a JSON file containing a dictionary for the demographic information. An example is attached below. There should be three keys, “age”, “sex”, and “race”. The value for “age” should be a float number representing chronological age in years. It is used to correct a common bias in brain age estimation, where older subjects tend to be underestimated and younger subjects overestimated. The value for “sex” should be an integer (0 for female, 1 for male). The value for “race” should be an integer (1 for “White”, 2 for “Asian”, 3 for “Black or African American”, 4 for “American Indian or Alaska Native”, and 0 for “Some Other Race”). If any of the values is not available, put null as the value (e.g., “age”: null).

{"age": 82.0, "sex": 0, "race": 1}

• dwmri.bval: a metadata text file for dMRI (units of s/mm², in the FSL format) for the bvalues of each dMRI volume. If coming from PreQual, it should be already properly formatted.
• dwmri.bvec: a metadata text file for dMRI (normalized unit vectors in the FSL format) for the bvectors of each dMRI volume. If coming from PreQual, it should be already properly formatted.
• dwmri.nii.gz: a 4D dMRI that has been preprocessed with FSL's TOPUP and EDDY using the PreQual preprocessing pipeline (which can be found here: 10.5281/zenodo.14058395 and here: https://github.com/MASILab/PreQual). Is assumed to have at least one b0 volume.
• T1w.nii.gz: a T1w image.
• T1w_seg.nii.gz: brain mask for the T1w image. Segmentation image is also acceptable if the background is labeled as 0 and the brain is labeled with other integer values than 0.

Step 2: Run Singularity

singularity run -e --contain  \
-B /tmp:/tmp  \
-B </path/to/input/directory>:/INPUTS  \
-B </path/to/output/directory>:/OUTPUTS  \
</path/to/singularity/container>

Replace the </path/to/input/directory> with the correct path (e.g., /Users/batman/INPUTS). Replace the </path/to/output/directory> with the correct (and existing) path (e.g., /Users/batman/OUTPUTS). Replace the </path/to/singularity/container> with the correct path (e.g., /Users/batman/braid_v1.0.0.sif).

Step 3: Check Outputs

The final outputs will appear in the “final” folder:

• braid_predictions.csv: a single-row CSV containing individual estimation (unit: year) by each of the five models (from five-fold cross validation), mean value, and standard deviation of the estimates, before and after bias-correction (if chronological age was provided), for WM age (nonrigid), WM age (affine), and GM age (affine, ours), respectively.

• QA.png: a PNG image of visualization of brain images and corresponding brain age estimates.

The other files are intermediate outputs, among which we highlight the following:

• {fa/md}_skullstrip_MNI152.nii.gz: skull-stripped FA (or MD) map affinely registered to the MNI152 template. Input for the WM age (affine) model.
• {fa/md}_skullstrip_MNI152_warped.nii.gz: skull-stripped FA (or MD) map affine+non-linearly registered to the MNI152 template. Input for the WM age (nonrigid) model.
• t1w_brain_MNI152.nii.gz: skull-stripped T1w image affinely registered to the MNI152 template. Input for the GM age (affine, ours) model.
• transform*: transformation matrices computed from the registrations.
• log.txt: log file, which contains the printout of each processing step.

Example data

Input and output data for three subjects are provided in example_data.zip as examples to 1) show how the inputs should be formatted and structured; 2) show what the expected outputs are; and 3) allow users to test run and see if the estimation results can be reproduced. (Note: the image registration is a non-deterministic process, so the results may not be exactly the same.)

Citations

Please cite the following papers if you find the container useful:

[1] “Brain age identification from diffusion MRI synergistically predicts neurodegenerative disease”. Imaging Neuroscience. 2025.

[2] “Predicting age from white matter diffusivity with residual learning”. Medical Imaging 2024: Image Processing. SPIE, 2024. https://doi.org/10.1117/12.3006525