DeepBrainNet inference

Community-maintained inference utilities for the pretrained DeepBrainNet brain-age model described by Bashyam et al. (2020).

DeepBrainNet estimates brain age from a preprocessed T1-weighted MRI. The model uses 80 axial slices from each scan, predicts an age for every slice, and reports the median as the subject-level predicted age.

Important

This is a community-maintained fork of vishnubashyam/DeepBrainNet, not the official implementation maintained by the paper's authors. It is intended for research use only and is not a medical device or a substitute for clinical interpretation.

What this fork adds

• Updated inference scripts for newer Python, Keras, and TensorFlow environments
• Practical preprocessing notes based on ANTs and FSL FLIRT
• Published Docker images for ARM64 and AMD64 systems
• Four example preprocessed NIfTI scans and companion sample metadata

The pretrained model itself was developed by the original DeepBrainNet authors. Please cite the original paper when using it in research.

Quick start with Docker

Docker is the simplest way to run the current repository because it avoids local Python and TensorFlow compatibility issues. The published images include the pretrained model.

1. Clone the repository

git clone https://github.com/tannerjared/DeepBrainNet.git
cd DeepBrainNet

2. Select the image for your computer

Computer architecture	Docker image
ARM64, including Apple Silicon	jjtanner/deepbrainnet:latest
AMD64/x86-64, including Intel and AMD processors	jjtanner/deepbrainnet:amd64

Set DBN_IMAGE to the appropriate image:

# ARM64
DBN_IMAGE=jjtanner/deepbrainnet:latest

# For AMD64/x86-64, use this line instead:
# DBN_IMAGE=jjtanner/deepbrainnet:amd64

The latest tag currently refers specifically to ARM64; it is not a multi-architecture image.

3. Run the included sample data

mkdir -p output
docker pull "$DBN_IMAGE"

docker run --rm \
  --mount type=bind,source="$(pwd)/Data",target=/data,readonly \
  --mount type=bind,source="$(pwd)/output",target=/output \
  "$DBN_IMAGE" \
  -d /data/ -o /output/ -m /app/Models/DBN_model.h5

Predictions are written to output/pred.csv.

Run your own data

Replace $(pwd)/Data with the absolute path to the directory containing your preprocessed .nii.gz files:

mkdir -p output

docker run --rm \
  --mount type=bind,source="/absolute/path/to/preprocessed-scans",target=/data,readonly \
  --mount type=bind,source="$(pwd)/output",target=/output \
  "$DBN_IMAGE" \
  -d /data/ -o /output/ -m /app/Models/DBN_model.h5

The Dockerfile used to build the published images is not currently included on the master branch, so local image-building instructions are not provided here.

Input requirements

The current inference scripts expect the following:

Requirement	Details
Image type	T1-weighted structural MRI
File format	Compressed NIfTI (.nii.gz)
Brain extraction	The image should be skull-stripped
Bias correction	Recommended for the workflow used by this fork
Registration	Affine registration to the same MNI152 1 mm atlas space used for inference
Dimensions	The third image dimension must contain at least 125 slices; matching the target atlas geometry is strongly recommended
Directory contents	Use a directory containing only the NIfTI scans to be processed

Filename convention

Use one scan per subject and name each file as follows:

<subject-id>_T1_BrainAligned.nii.gz

For example:

Subject2008_T1_BrainAligned.nii.gz

The current prediction script treats everything before _T1 as the subject ID. Files sharing that prefix will be combined into the same subject-level result.

Preprocessing

Method reported in the original paper

The original DeepBrainNet study applied minimal automated preprocessing:

1. Skull stripping using a multi-atlas label-fusion method
2. Quality control of the skull-stripped images
3. Affine registration to a common atlas space using FSL FLIRT

See the original publication for the authoritative method description.

Workflow tested for this fork

The maintainer's workflow was:

1. Run antsCorticalThickness.sh for brain extraction, bias correction, and related preprocessing.
2. Use the resulting ExtractedBrain0N4.nii.gz skull-stripped image.
3. Affinely register the extracted brain to the MNI152 1 mm template using FLIRT with 12 degrees of freedom.
4. Rename the aligned image using the filename convention above.

Additional ANTs guidance is available in the maintainer's MRI preprocessing guide.

The original public materials specify affine registration but do not fully document the transformation settings. In the maintainer's testing, 6- and 12-degree-of-freedom registrations produced similar estimates; 12 DOF was selected to normalize brain size more fully. Nonlinearly normalized ANTs outputs produced substantially different predictions and should not be substituted without validation.

These preprocessing observations are fork-specific experience rather than a formal benchmark or an amendment to the published method.

Native installation

The Docker route is recommended. If you need to run the scripts directly, use an isolated Python environment and install Git LFS before cloning so that the model weights are downloaded.

git lfs install
git clone https://github.com/tannerjared/DeepBrainNet.git
cd DeepBrainNet
git lfs pull

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "tensorflow==2.15.*" "keras==2.15.*" nibabel numpy pandas pillow scikit-learn

TensorFlow 2.15 is the compatibility target currently used by this fork. Because master does not yet contain a pinned dependency or environment file, the native environment is less reproducible than the Docker images.

Confirm that the model is approximately 175 MiB rather than a small Git LFS pointer file:

ls -lh Models/DBN_model.h5

If Git LFS is unavailable, the original project also distributes model and support files through the University of Pennsylvania Box folder.

Run inference natively

The current shell script uses paths relative to the Script directory. Input and output paths must include trailing slashes, and the output directory must exist.

mkdir -p output
cd Script
./test.sh -d ../Data/ -o ../output/ -m ../Models/DBN_model.h5

Run ./test.sh -h to display its arguments.

The native scripts currently set CUDA_VISIBLE_DEVICES=0. Using another GPU, or explicitly disabling GPU access in a GPU-enabled environment, requires changing that setting in the scripts. CPU-only TensorFlow installations can run without an NVIDIA GPU.

Output

The pipeline writes a CSV named pred.csv with two columns:

Column	Meaning
ID	Text parsed from the filename before _T1
Pred_Age	Median predicted age, in years, across 80 axial slices

An output file has this general form:

ID,Pred_Age
<parsed-subject-id>,<model-prediction>

The included Sample_Data.csv associates the four example subjects with an Age column, but the inference script does not read that file and the upstream repository does not document those values as expected model predictions. Treat it as companion sample metadata rather than a formal numerical regression test. Row order and the final floating-point digits in model output may vary by software and hardware environment.

The script derives IDs from Keras's relative slice filenames. Depending on the Keras version, an ID may retain a directory prefix such as Test/. Inspect and normalize the ID column before joining predictions to external participant data.

The pipeline reports predicted age only. If chronological age is available, brain-age delta can be calculated separately:

brain-age delta = predicted age - chronological age

How inference works

For each input scan, the current scripts:

1. Load the NIfTI volume with nibabel.
2. Scale voxel intensities so that the 97th percentile equals 185.
3. Extract 80 axial slices at indices 45 through 124.
4. Convert each slice to an RGB JPEG and rescale pixel values for the model.
5. Predict an age independently for each slice.
6. Report the median of the 80 predictions as the subject's predicted age.

This mirrors the published subject-level aggregation procedure, although implementation and preprocessing details in this fork differ from the original research environment.

Known limitations and operational notes

• Brain-age estimates are sensitive to preprocessing, registration, acquisition protocol, scanner characteristics, and population differences.
• Published performance should not be assumed to transfer unchanged to new clinical or research datasets.
• The current native shell script deletes and recreates ../tmp/. Run it from Script/ and do not store valuable files in the repository's tmp directory.
• Native shell arguments are not safely quoted for paths containing spaces. Prefer paths without spaces or use Docker.
• The scripts do not currently validate file extensions, image orientation, atlas geometry, or registration quality before inference.
• Output row order is not guaranteed.

Troubleshooting

The model cannot be loaded

Check the model size. If Models/DBN_model.h5 is only a few hundred bytes, it is a Git LFS pointer rather than the model:

git lfs install
git lfs pull

A NIfTI file cannot be found

For native execution, make sure the input path ends in / and run the command from Script/.

Slice extraction raises an index error

The registered volume must have at least 125 slices along its third array dimension. Confirm that it uses the expected atlas space, dimensions, and orientation.

Subject IDs are incorrect or scans are combined

Use the <subject-id>_T1_BrainAligned.nii.gz naming convention and ensure every subject ID is unique before _T1.

TensorFlow or Keras reports compatibility errors

Use the published Docker image or recreate an environment around TensorFlow and Keras 2.15.

Citation

If you use DeepBrainNet, cite the original publication:

Bashyam VM, et al. MRI signatures of brain age and disease over the lifespan based on a deep brain network and 14,468 individuals worldwide. Brain. 2020;143(7):2312-2324. doi:10.1093/brain/awaa160

@article{bashyam2020deepbrainnet,
  title   = {MRI signatures of brain age and disease over the lifespan based on a deep brain network and 14,468 individuals worldwide},
  author  = {Bashyam, Vishnu M. and others},
  journal = {Brain},
  volume  = {143},
  number  = {7},
  pages   = {2312--2324},
  year    = {2020},
  doi     = {10.1093/brain/awaa160}
}

Please also acknowledge the original DeepBrainNet repository.

License and model terms

This fork does not currently include a license file. Do not assume that the code or pretrained weights may be redistributed under a particular open-source license. Before reuse or redistribution, consult the original authors and any terms accompanying the model files. A future release should state separate, explicit terms for the source code and pretrained weights.