Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This is a deep learning workflow for Progressive Multifocal Leukoencephalopathy (PML) lesion and brain segmentation from brain MRI using Python 3, Keras, and TensorFlow. The model generates segmentation masks of the brain parenchyma and lesions in PML patients.

TNS Logo

This work was conducted at the Neuroimmunology Clinic (NIC) and Translation Neuroradiology Section (TNS) of the National Institute of Neurological Disorders and Stroke (NINDS), in collaboration with colleagues at the National Institute of Mental Health, and the Henry Jackson Foundation at the National Institutes of Health. This work utilized the computational resources of the NIH HPC Biowulf cluster, and the software is distributed under the GNU General Public License v3.0.

If this repository is helpful for your research, please cite the following articles:

Al-Louzi O, Roy S, Osuorah I, et al. Progressive multifocal leukoencephalopathy lesion and brain parenchymal segmentation from MRI using serial deep convolutional neural networks. Neuroimage Clin. 2020;28:102499. doi:10.1016/j.nicl.2020.102499


The basic code skeleton was adopted from the following source ( with several notable changes. We have created two tailored scripts for PML brain parechymal extraction and lesion segmentation training. We have also introduced improvements in training/validation split which is now undertaken at the atlas level to remove patch overlap effects during sampling, included support for Tensorboard logging, and generation of training/validation accuracy and loss graphs automatically at the end of model training. For the testing implementation, we fixed a previous bug with image padding for different patch sizes, added a new 4D image padding function, and replaced the slice-by-slice format previously used to generate model predictions on unseen images with a new method that uses a moving 3D window applied serially across the image volume. This allows higher resolution images to fit into available GPU memory. In addition, the method now offers support for 3 different trainable network acrchitechures:

  1. 3D Unet
  2. Feature pyramid network-ResNet50 (with bottleneck ResNet modules)
  3. Panoptic feature pyramid network-ResNet50 (with preactivated ResNet modules)

Prerequisites before running JCnet


A few standard MRI preprocessing steps are necessary before training or testing a JCnet model:

  1. Bias field correction - can use either N4 bias correction or MICO.
  2. Skull-stripping - we recommend using the MONSTR skull-stripping algorithm in PML cases, which is publicly available and can be found here.
  3. Transformation to the standard MNI-ICBM 152 atlas space, which is available for download here.
  4. Co-registration of different MRI channels or contrasts (i.e. T1-weighted, fluid-attenuated inversion recovery, T2-weighted, and proton density images).

Hardware Requirements:

  1. Operating System: Linux.
  2. CPU Number/Speed: we recommend using a processor with at least 8 cores, 2GHz speed, and multithreading capability.
  3. RAM: 64+GB recommended (depending on the size of the training dataset and maximum number of training patches per subject).
  4. GPU: recommend a dedicated graphics card with at least 8GB of VRAM (ex. NVIDIA RTX 2080 Ti, Titan X, or v100 models). If our current pre-trained models do not fit into GPU memory during testing, we recommend downscaling the network parameters (base filters, patch size, or architechure in this order). These models can be provided upon request.

Software Requirements:

  1. Python v3.6
  2. Keras v2.2.4
  3. Tensorflow GPU version v1.13+ (TF v2 is not currently supported)
  4. Several open source python packages, please see requirements.txt To install python dependency packages, you can point your pip manager using the terminal to the text file as follows:
pip3 install -r requirements.txt 

Training call examples

# Brain Extraction training:
python --atlasdir /path/to/atlas/dir/ --natlas 31 --psize 64 64 64 --maxpatch 1000 --batchsize 8 --basefilters 32 --modalities T1 FL T2 PD --epoch 50 --outdir /path/to/output/dir/to/save/models/ --save 1 --gpuids 0 1 2 3 --loss focal --model FPN
# Lesion Segmentation training:
python --atlasdir /path/to/atlas/dir/ --natlas 31 --psize 64 64 64 --maxpatch 1000 --batchsize 8 --basefilters 32 --modalities T1 FL T2 PD --epoch 50 --outdir /path/to/output/dir/to/save/models/ --save 1 --gpuids 0 1 2 3 --loss focal --model FPN

Testing call examples

# Brain Extraction testing:
python --models /path/to/model/files/containing/in/\*Orient012\*.h5 /path/to/model/files/ending/in/\*Orient120\*.h5 /path/to/model/files/ending/in/\*Orient201\*.h5  --images /path/to/T1/niftifile/\*.nii.gz /path/to/FL/niftifile/\*.nii.gz /path/to/T2/niftifile/\*.nii.gz /path/to/PD/niftifile/\*.nii.gz --modalities T1 FL T2 PD --psize 64 64 64 --outdir /path/to/output/dir/to/save/results/ --threshold 0.5
# Lesion Segmentation testing:
python --models /path/to/model/files/containing/in/\*Orient012\*.h5 /path/to/model/files/ending/in/\*Orient120\*.h5 /path/to/model/files/ending/in/\*Orient201\*.h5  --images /path/to/T1/niftifile/\*.nii.gz /path/to/FL/niftifile/\*.nii.gz /path/to/T2/niftifile/\*.nii.gz /path/to/PD/niftifile/\*.nii.gz --modalities T1 FL T2 PD --psize 64 64 64 --outdir /path/to/output/dir/to/save/results/ --threshold 0.35


Deep learning workflow for Progressive Multifocal Leukoencephalopathy lesion and brain segmentation from MRI




No releases published


No packages published