DeepMedic

News

Jan 2021 (v0.8.4):

• Backend capable of receiving input files (images, labels, roi masks) via csv dataframe. (not yet used though)
• Refactored front end modules for easier readability.

29 May 2020 (v0.8.3):

• Reverted back to old algorithm (pre-v0.8.2) for getting down-sampled context, to preserve exact behaviour.
• Models trained with v0.8.3 should now be fully compatible with versions v0.8.1 and before.

26 Apr 2020 (v0.8.2):

• Major codebase changes for compatibility with Tensorflow 2.0.0 (and TF1.15.0) (not Eager yet).
• Redesign/refactor of ./deepmedic/neuralnet modules.
• Improved sampling (faster when multiclass) and logging.
• Changes to configs: ModelConfig: kernelDimFor1stFcLayer -> kernelDimPerLayerFC, new padTypePerLayerFC.

14 Nov 2019 (v0.8.0):

• Logging metrics to Tensorboard.
• Capability to normalize input on-the-fly (Disabled by default). Only z-score norm for now.
• Refactoring & aesthetics in training, testing and sampling.

11 June 2019 (v0.7.4):

• Added augmentation via affine transforms, rotation & scaling. Off by default (slows down training).
• Redistribute samples of non-existent class & code refactoring in sampling.
• Added a wider DM model config, seems to work better in a few studies.

19 Mar 2019 (v0.7.3):

• Default sampling for training now done on a per-class basis. Better now that DM is applied for arbitrary tasks.

16 Mar 2019 (v0.7.2):

• Batch size now in trainConfig and testConfig, not model.
• Improved handling of hunging parallel processes.
• Modularized augmentation, for further extensions.

11 Feb 2019 (v0.7.1):

• Multiprocessing changed from pp to python's builtin module.
• Default suggested python switched to python3.
• Updated default config with non normalized momentum.
• Code for sampling partial cleanup.

27 June 2018 (v0.7.0):

• Back end changed to TensorFlow.
• API/command line options changed slightly. Documentation updated accordingly.
• Updated the default config in ./examples/config/deepmedic with three pathways.
• Refactored/reorganized the code.

Introduction

This project aims to offer easy access to Deep Learning for segmentation of structures of interest in biomedical 3D scans. It is a system that allows the easy creation of a 3D Convolutional Neural Network, which can be trained to detect and segment structures if corresponding ground truth labels are provided for training. The system processes NIFTI images, making its use straightforward for many biomedical tasks.

This document describes how to install and run the software. Accompanying data are provided to run the preset examples and make sure that the system is functioning on your system. This document also describes the main functionality, in order for the user to understand the main processing cycle. For greater details please consult [1]. We hope this project will serve well in making the state-of-the-art Convolutional Networks more accessible in the field of medical imaging.

Citations

The system was initially developed for the segmentation of brain lesions in MRI scans. It was employed for our research presented in [1],[2], where a 3D network architecture with two convolutional pathways was presented for the efficient multi-scale processing of multi-modal MRI volumes. If the use of the software positively influences your endeavours, please cite [1].

[1] Konstantinos Kamnitsas, Christian Ledig, Virginia F.J. Newcombe, Joanna P. Simpson, Andrew D. Kane, David K. Menon, Daniel Rueckert, and Ben Glocker, “[Efficient Multi-Scale 3D CNN with Fully Connected CRF for Accurate Brain Lesion Segmentation][paper1]”, Medical Image Analysis, 2016.

[2] Konstantinos Kamnitsas, Liang Chen, Christian Ledig, Daniel Rueckert, and Ben Glocker, “[Multi-Scale 3D CNNs for segmentation of brain Lesions in multi-modal MRI][paper2]”, in proceeding of ISLES challenge, MICCAI 2015.

Table of Contents

• 1. Installation and Requirements
  • 1.1. Required Libraries
  • 1.2. Installation
  • 1.3. GPU Processing
  • 1.4. Required Data Pre-Processing
• 2. Running the Software
  • 2.1 Training a tiny CNN - Making sure it works
  • 2.2 Running it on a GPU
• 3. How it works
  • 3.1 Architecture
  • 3.2 Training
  • 3.3 Testing
• 4. How to run DeepMedic on your data
• 5. Concluding
• 6. Licenses

1. Installation and Requirements

1.1. Required Libraries

The system requires the following:

• Python: Python 3 by default (works for python 2, but no future guarantees).
• TensorFlow: The Deep Learning library for back end.
• NiBabel: The library used for loading NIFTI files.
• numpy : General purpose array-processing package.
• scipy : Scientific packages. Used for image operations e.g. augmentation.

Latest versions tested:

As of Jan 2021, v0.8.4 was tested using Python 3.6.5, Tensorflow 2.0.0 and Tensorflow 1.15.0, nibabel 3.0.2, numpy 1.18.2.

1.2. Installation

(The below are for unix systems, but similar steps should be sufficient for Windows.)

The software cloned with:

git clone https://github.com/Kamnitsask/deepmedic/

After cloning it, all dependencies can be installed as described below.

Install using a Conda Environment

If you do not have sudo/root privileges on a system, we suggest you install using Conda. From a bash shell, create a conda environment in a folder that you wish.

conda create -p FOLDER_FOR_ENVS/ve_dm_tf python=3.6.5 -y
source activate FOLDER_FOR_ENVS/ve_dm_tf

Install TensorFlow and DeepMedic

Install TensorFlow (TF): Please follow instructions on (https://www.tensorflow.org/install/). By consulting the previous link, ensure that your system has CUDA version and cuDNN versions compatible with the tensorflow version you are installing.

$ pip install tensorflow-gpu==2.6.2
$ pip install cudnn==8.2.1

Install DeepMedic and rest of its dependencies:

$ cd DEEPMEDIC_ROOT_FOLDER
$ pip install .

This will grab rest of dependencies described in Sec.1.

Note: The most common installation issue is when users do not install compatible versions of Python, TF, and cudnn. You need versions that are compatible with each other: Each Python version has specific pre-compiled TF versions. We need TF version 2.0+, and each TF versionis compatible with specific cudnn versions (see TF docs). We need Cudnn that is compatible with TF and your system's Nvidia drivers. We have tested DeepMedic for Python=3.6.5, TF=2.6.2, and cudnn=8.2.1, which should work in 2024.

1.3. GPU Processing

Install CUDA: (Deprecated)

Note: This step may not be required anymore, because recent cudnn versions (installed via conda above) install rest of the required libraries. As long as you have installed GPU drivers, cudnn tends to install the rest. But in case this is not true, have a look at the following.

Small networks can be run on the cpu. But 3D CNNs of considerable size require processing on the GPU. For this, an installation of Nvidia’s CUDA is needed. Make sure to acquire a version compatible with your GPU drivers. TensorFlow needs to be able to find CUDA’s compiler, the nvcc, in the environment’s path. It also dynamically links to cublas.so libraries, which need to be visible in the environment’s.

Prior to running DeepMedic on the GPU, you must manually add the paths to the folders containing these files in your environment's variables. As an example in a bash shell:

$ export CUDA_HOME=/path/to/cuda                   # If using cshell instead of bash: setenv CUDA_HOME /path/to/cuda
$ export LD_LIBRARY_PATH=/path/to/cuda/lib64
$ export PATH=/path/to/cuda/bin:$PATH

1.4. Required Data Pre-Processing

• DeepMedic processes NIFTI files only. All data should be in the .nii format.

• The input modalities, ground-truth labels, ROI masks and other images of each subject need to be co-registered (per-subject, no need for inter-subject registration).

• The images of each subject should have the same dimensions (per subject, no need for whole database). This is, the number of voxels per dimension must be the same for all images of a subject.

• Resample all images in the database to the same voxel size. The latter is needed because the kernels (filters) of the DeepMedic need to correspond to the same real-size patterns (structures) for all subjects.

• Make sure that the ground-truth labels for training and evaluation represent the background with zero. The system also assumes that the task’s classes are indexed increasing by one (not 0,10,20 but 0,1,2).

• You are strongly advised to normalize the intensity of the data within the ROI to a zero-mean, unit-variance space. Our default configuration significantly underperforms if intensities are in another range of values.

Note for large images: Large 3D CNNs are computationally expensive. Consider downsampling the images or reducing the size of the network if you encounter computational difficulties. The default configuration of DeepMedic was applied on scans of size around 200x200x200.

2. Running the Software

The source code of the DeepMedic is provided in the folder deepmedic. Users should not need to touch this folder. The software comes with a command line interface, [deepMedicRun](deepMedic