OpenMAP-BrainAge

OpenMAP-BrainAge predicts brain age from:

• a skull-stripped, rigidly aligned T1 MRI
• a 280-region parcellation volume CSV from OpenMAP-T1

The model follows the design in OpenMAP-BrainAge: Generalizable and Interpretable Brain Age Predictor. Part of the implementation also builds on Heterogeneous Pre-trained Transformers.

The OpenMAP-BrainAge is a publication of The Johns Hopkins University and copyright © 2026 The Johns Hopkins University. All rights reserved.

Quick Start

If you have a folder of raw T1 MRI scans and want final age predictions with the least manual setup, use the full pipeline:

python run_full_pipeline.py \
  --input_dir /path/to/raw_mri_folder \
  --output_dir /path/to/output_folder \
  --openmap_t1_model_dir /path/to/openmap_t1_models \
  --mni_path ./data_processing/MNI_template/MNI_FULL.nii \
  --age_model_checkpoint ./saved_ckpt/trained_model_multiview/checkpoint0199.pth

This one command will:

1. skull-strip the scans
2. rigidly register them to MNI space
3. generate the 280-region parcellation volume CSV
4. build the metadata CSV required by the age model
5. output final brain-age predictions

For more detail, see FULL_PIPELINE_README.md.

Environment Setup

We recommend using Anaconda or Miniconda.

Clone the repository first:

git clone https://github.com/OishiLab/OpenMAP-BrainAge.git
cd OpenMAP-BrainAge

From the repository root:

conda env create -f environment.yml
conda activate openmap-brainage

The provided environment.yml contains the Python and package setup used by this project.

Platform Note

The current version has been tested on Linux and is expected to run properly there.

It has not yet been tested on macOS or Windows.

Input Data Folder Structure

For raw MRI input, we recommend using a folder layout similar to OpenMAP-T1 v2.0.0:

INPUT_FOLDER/
  ├ subject_001.nii
  ├ subject_002.nii
  ├ subject_003.nii.gz
  └ ...

The full pipeline will scan the input directory recursively for .nii and .nii.gz files.

After running the full pipeline, your output folder will look like:

OUTPUT_FOLDER/
  01_skull_removed/
    subject_001.nii
    subject_002.nii
    ...
  02_parcellation/
    subject_001/
      subject_001_280.nii
      subject_001_volume.csv
    subject_002/
      subject_002_280.nii
      subject_002_volume.csv
    ...
  03_metadata/
    full_pipeline_demo_data.csv
  04_predictions/
    age_predictions.csv

Recommended Local Asset Layout

To make the repository easier to use, we recommend the following local folder structure for external assets:

OpenMAP-BrainAge/
  data_processing/
    MNI_template/
      MNI_FULL.nii
  saved_ckpt/
    openmap_t1/
      CNet/
        CNet.pth
      SSNet/
        SSNet.pth
      PNet/
        coronal.pth
        sagittal.pth
        axial.pth
      HNet/
        coronal.pth
        axial.pth
    trained_model_multiview/
      checkpoint0199.pth

MNI template location

We recommend placing the provided MNI template at:

./data_processing/MNI_template/MNI_FULL.nii

Then you can pass it to the full pipeline with:

--mni_path ./data_processing/MNI_template/MNI_FULL.nii

saved_ckpt structure

We recommend placing the trained OpenMAP-BrainAge checkpoints under:

./saved_ckpt/trained_model_multiview/

For example:

saved_ckpt/
  trained_model_multiview/
    checkpoint0199.pth

This matches the checkpoint path used in Inference.ipynb:

./saved_ckpt/trained_model_multiview/checkpoint0199.pth

To obtain the trained OpenMAP-BrainAge age-predictor checkpoint for inference, please submit the model-weight request form: Microsoft Forms.

OpenMAP-T1 checkpoints in saved_ckpt

We also recommend placing the OpenMAP-T1 preprocessing checkpoints under:

./saved_ckpt/openmap_t1/

Expected structure:

./saved_ckpt/openmap_t1/
  CNet/
    CNet.pth
  SSNet/
    SSNet.pth
  PNet/
    coronal.pth
    sagittal.pth
    axial.pth
  HNet/
    coronal.pth
    axial.pth

These checkpoints are used by the preprocessing scripts in data_processing/ and by the full pipeline through:

--openmap_t1_model_dir ./saved_ckpt/openmap_t1

Repository Structure

The most important files and folders are:

OpenMAP-BrainAge/
  README.md
  environment.yml
  run_full_pipeline.py
  FULL_PIPELINE_README.md
  Inference.ipynb
  train_ADNI_multiview.py
  train_ADNI_multiview.sh
  dataADNI_multiview.py
  modelADNI.py
  data/
    demo_data.csv
  data_processing/
    README.md
    skull_removal.py
    parcellation_from_skull_removed_img.py
    utils/
    level/
  hpt/
  hpt_pretrained_model/

What each part is for

• run_full_pipeline.py Main end-to-end script from raw MRI folder to final age prediction.

• data_processing/ Preprocessing code for skull stripping, rigid registration, and 280-region parcellation.

• Inference.ipynb Example inference workflow when you already have skull-stripped MRI and parcellation volume CSV files.

• train_ADNI_multiview.py and train_ADNI_multiview.sh Training code for users who want to train their own OpenMAP-BrainAge model.

• data/demo_data.csv Example metadata CSV showing the required input format for inference and training.

Which Workflow Should I Use?

1. I have raw MRI scans with skull and no registration

Use:

• run_full_pipeline.py

This is the recommended path for most clinical users.

2. I only want preprocessing outputs

Use:

• data_processing/skull_removal.py
• data_processing/parcellation_from_skull_removed_img.py

This is useful if you want skull-stripped images and regional volume CSV files but do not want to run age prediction yet.

For details, see:

• data_processing/README.md

3. I already have skull-stripped MRI and parcellation volume CSV files

Use:

• Inference.ipynb

This is the best route if your preprocessing has already been done.

4. I want to train my own brain-age model

Use:

• train_ADNI_multiview.py
• train_ADNI_multiview.sh

Full Pipeline: Raw MRI to Brain Age

The full pipeline expects:

• raw T1 MRI scans in .nii or .nii.gz
• OpenMAP-T1 preprocessing checkpoints
• an MNI template
• a trained OpenMAP-BrainAge checkpoint

The output directory will contain:

<OUTPUT_DIR>/
  01_skull_removed/
  02_parcellation/
  03_metadata/
    full_pipeline_demo_data.csv
  04_predictions/
    age_predictions.csv

The generated CSV in 03_metadata/full_pipeline_demo_data.csv follows the same format as data/demo_data.csv.

A typical command using the recommended repo-local asset layout is:

python run_full_pipeline.py \
  --input_dir ./INPUT_FOLDER \
  --output_dir ./OUTPUT_FOLDER \
  --openmap_t1_model_dir /path/to/openmap_t1_models \
  --mni_path ./data_processing/MNI_template/MNI_FULL.nii \
  --age_model_checkpoint ./saved_ckpt/trained_model_multiview/checkpoint0199.pth

If You Already Have Skull-Stripped Images and Parcellation Data

You do not need to run the preprocessing scripts again if you already have:

• skull-stripped, rigidly aligned MRI scans
• 280-region parcellation volume CSV files

In that case, follow the example in Inference.ipynb.

The notebook shows how to:

1. load the pretrained HPT backbone
2. build the OpenMAP-BrainAge model
3. load a trained age-prediction checkpoint
4. read a metadata CSV
5. output the predicted brain age

The expected CSV format is:

path_full,age,path_rigid_parcellation_volume
/path/to/subject001.nii,,/path/to/subject001_volume.csv

Notes:

• path_full should point to the skull-stripped, rigidly aligned MRI image
• path_rigid_parcellation_volume should point to the 280-region volume CSV
• for inference-only use, the age column can be left blank

See also:

• data/demo_data.csv

If You Want to Train Your Own Model

If you want to build a new brain-age model on your own cohort, the typical workflow is:

1. preprocess your MRI scans
2. generate the parcellation volume CSV for each case
3. prepare a metadata CSV in the same style as data/demo_data.csv
4. train using train_ADNI_multiview.py

The default training launcher is:

bash train_ADNI_multiview.sh

You will usually need to update:

• training and validation CSV paths
• checkpoint paths
• output path
• hyperparameters for your experiment

Important training files:

• train_ADNI_multiview.sh
• train_ADNI_multiview.py
• dataADNI_multiview.py
• modelADNI.py

The training output checkpoint is typically written under:

./trained_model_multiview/

Pretrained Files

Depending on your workflow, you may need:

• OpenMAP-T1 preprocessing model files for data_processing/
• pretrained HPT trunk files for training
• pretrained 3D ResNet18 files for training
• a trained OpenMAP-BrainAge checkpoint for inference

For the trained OpenMAP-BrainAge age-predictor checkpoint used in inference, please submit the model-weight request form: Microsoft Forms.

Please contact the project authors if access to any other required pretrained checkpoints is not already available to you.

Additional Documentation

• FULL_PIPELINE_README.md More detail on the raw-MRI-to-age-prediction pipeline

• data_processing/README.md More detail on the preprocessing folder and scripts

• Inference.ipynb Example notebook for direct inference on prepared inputs