DeepMRSeg

DeepMRSeg is a Python-based package for MRI image segmentation. The package is developed and maintained by the Center for Biomedical Image Computing and Analytics (CBICA) at the University of Pennsylvania. As the name implies, main modules of DeepMRSeg are built upon Deep Learning models that perform a set of image segmentation steps on MRI scans.

DeepMRSeg aims to provide users a robust, accurate and user-friendly toolset for performing common segmentation tasks in neuroimaging. In order to meet these challenges, the development of DeepMRSeg was guided by the following set of fundamental principles:

Efficient network architecture: DeepMRSeg uses a modified UNet architecture that combines an ensemble of learners for a robust segmentation [1].
Model repository with extensively trained models: We provide a set of pre-trained models for various segmentation tasks. We applied model training using very large and diverse MRI datasets with carefully curated and verified ground-truth labels.
Easy installation and application: Using a few simple commands, users can easily install DeepMRSeg on different platforms, download pre-trained models, and apply these models on their images. Most applications require no or minimal pre-processing; thus, users can directly apply them on raw scans.
Extensibility: DeepMRSeg is built using a generic network architecture and a software package that allows extending it with minimal effort. The model repository will grow in the future with regular addition of new models and tasks.

Supported Platforms

We have tested DeepMRSeg on the following platforms:

Windows 10 Enterprise x64
Ubuntu 18.04.3 , 20.04.2 It may also work on other platforms.

Prerequisities

Python 3
If you prefer conda, you may install it from here

Installation Instructions

To setup your GPU for use with tensorflow, please follow the tensorflow guide for GPU support.

1) Direct installation at default location

git clone  https://github.com/CBICA/DeepMRSeg.git
cd DeepMRSeg
python setup.py install #install DeepMRSeg and its dependencies

2) Installation in conda environment

conda create --name DeepMRSeg python=3.7.9
conda activate DeepMRSeg

Then follow steps from direct installation

Usage

After installation of the package, users can call DeepMRSeg commands on the command prompt (or on Anaconda prompt).

Pre-trained models

Pre-trained models for testing are hosted in DeepMRSeg-Models repository. Users can manually download a model from the model repository into a local folder.

Alternatively, the model can be downloaded to a pre-defined local folder (_~/.deepmrseg/trainedmodels) automatically using the command:

deepmrseg_downloadmodel

Training and testing

Users can train their own model using a custom training dataset (training):

deepmrseg_train

or apply a pre-trained model on their image(s) (testing):

deepmrseg_test

Note that _deepmrsegtrain and _deepmrsegtest are generic commands that allow users to run training and testing in an exhaustive way by supplying a set of user arguments.

Applying a task

Alternatively, we provide a simplified interface for the application of a specific segmentation task on user data:

deepmrseg_apply

Note that _deepmrsegapply is a wrapper to _deepmrsegtest, which calls it with a pre-defined model automatically downloaded using _deepmrsegdownloadmodel.

Examples

We provide here few examples using minimal argument sets as a quick reference. These examples also show 3 possible I/O options provided for different use cases (single subject, batch processing using an image list and batch processing of images in a folder).

Testing

Quick application on single subject using the wrapper scripts and a pre-trained model:

# Download the pre-trained ICV segmentation model
deepmrseg_downloadmodel --model dlicv  

# Segment image
deepmrseg_apply --task dlicv --inImg subj1_T1.nii.gz --outImg subj1_T1_DLICV.nii.gz

Quick application for batch processing using an image list:

#   User provides a csv file with columns: ID,InputMod1,InputMod2,...,OutputImage
deepmrseg_apply --task dlicv --sList subjectList.csv

Quick application for batch processing of all images in a folder:

#   Testing is applied individually to all images with the given suffix in the input folder
deepmrseg_apply --task dlicv --inDir myindir --outDir myoutdir --inSuff _T1.nii.gz --outSuff _DLICV.nii.gz

Segmentation using the deepmrseg_test command:

#    
deepmrseg_test --mdldir my/path/to/pretrained/model --sList subjectList.csv

Please see the user manual (or call the command with the -h option) for details of the complete command line arguments for deepmrseg_test.

Training

Training a new model using the deepmrseg_train command:

#    
deepmrseg_train --sList subjectList.csv --mdlDir my/path/to/output/model

Please see the user manual (or call the command with the -h option) for details of the complete command line arguments for deepmrseg_train.

License

How to cite DeepMRSeg

Publications

[1] Doshi, Jimit, et al. DeepMRSeg: A convolutional deep neural network for anatomy and abnormality segmentation on MR images. arXiv preprint arXiv:1907.02110 (2019).

Authors and Contributors

The DeepMRSeg package is currently developed and maintained by:

Others who contributed to the project are:

Grant support

Development of the DeepMRSeg package is supported by the following grants:

Disclaimer

The software has been designed for research purposes only and has neither been reviewed nor approved for clinical use by the Food and Drug Administration (FDA) or by any other federal/state agency.
This code (excluding dependent libraries) is governed by the license provided in https://www.med.upenn.edu/cbica/software-agreement-non-commercial.html unless otherwise specified.
By using DeepMRSeg, you agree to the license as stated in the license file.

Contact

For more information, please contact CBICA Software.

CBICA / DeepMRSeg

readme