Welcome to VentMapp3r’s documentation!¶

VentMapp3r (pronounced ventmapper) is a CNN-based segmentation technique of the ventricular system using MRI images from BrainLab. It can deal with brains with extensive atrophy and segments the ventricles in seconds. It can segment the ICV with either T1-weighted image as the only input, or with different combinations involving a T1, T2, and FLAIR image.

Before installing VentMapp3r¶

Acknowledging this work¶

If you wish to include results generated by VentMapp3r in a publication, please include a line such as the following:

Ventricular segmentation was performing using the VentMapp3r algorithm (ventmapp3r.readthedocs.io) based on a convolutional neural network.

Reference¶

The paper is currently in preparation. The citation will be provided upon publication.

License¶

VentMapp3r is licensed under the terms of the GNU General Public License v3.0.

VentMapp3r is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. You should have received a copy of GNU General Public License v3.0 along with VentMapp3r.

The code is released for academic research use only. For commercial use, please contact maged.goubran@sri.utoronto.ca.

Local Install¶

Python¶

For the main required Python packages (numpy, scipy, etc.) we recommend using Anaconda for Python 3.6

Installing package and dependencies for VentMapp3r locally¶

Clone repository

 git clone https://github.com/mgoubran/VentMapp3r.git VentMapp3r

 (or install zip file and uncompress)

 cd VentMapp3r

If you want to create a virtual environment where VentMapp3r can be run,

 conda create -n ventmapper python=3.6 anaconda
 source activate ventmapper

To end the session,

 source deactivate

To remove the environment

 conda env remove --name ventmapper

Install dependencies

 pip install git+https://www.github.com/keras-team/keras-contrib.git

If the computer you are using has a GPU:

 pip install -e .[ventmapper_gpu]

If not:

 pip install -e .[ventmapper]

Test the installation by running
```
 ventmapper --help
```
To confirm that the command line function works, and
```
 ventmapper
```
To launch the interactive GUI.

Download deep models¶

Download the models from this link and place them in the “models” directory

For tab completion¶

pip3 install argcomplete
activate-global-python-argcomplete

Updating VentMapp3r¶

To update VentMapp3r, navigate to the directory where VentMapp3r was cloned and run

git pull
pip install -e .[{option}] -process-dependency-links

where “option” is dependent on whether or not you have a GPU (see package installation steps above)

Getting started¶

You can use VentMapp3r through the graphical user interface (GUI) or command line:

For GUI¶

To start the GUI, type

ventmapper

A GUI that looks like the image below should appear. You can hover any of buttons in the GUI to see a brief description of the command.

_images/ventmapper_gui.png Graphical user interface for the VentMapper application

You can get the command usage info by click the “Help” box on any of the pop-up windows.

_images/ventmapper_help.png Help screen for graphical user interface for Dasher application

For Command Line¶

You can see all the ventmapper commands by typing either of the following lines:

ventmapper -h
ventmapper --help

Once you know the command you want to know from the list, you can see more information about the command. For example, to learn more about seg_hfb:

ventmapper seg_vent -h
ventmapper seg_vent --help

Ventricular volumes¶

To extract ventricular volumes use the GUI (Stats/ventricular Volumes) or command line:

ventmapper stats_vent -h

QC¶

QC files are automatically generated in a sub-folder within the subject folder. They are .png images that show a series of slices in the brain to help you quickly evaluate if your command worked successfully, especially if you have run multiple subjects. They can also be created through the GUI or command line:

ventmapper seg_qc -h

The QC image should look like this:

_images/ventricles_seg_qc.png Quality control imagefor ventricular segmentation

Logs¶

Log files are automatically generated in a sub-folder within the subject folder. They are .txt files that contain information regarding the command and can be useful if something did not work successfully.

File conversion¶

To convert from one filetype to another (namely Analyze to Nifti, or vice versa)

ventmapper filetype

Required arguments:
-i , --in_img    input image, ex:MM.img
-o , --out_img   output image, ex:MM.nii

Example:
ventmapper filetype --in_img subject_T1.img --out_img subject_T1.nii.gz

Segmentation tutorials¶

GUI¶

Watch this video tutorial:

IMAGE ALT TEXT

Or follow the steps below:

After opening the VentMapp3r GUI, click “Ventricle” under the “Segmentation” tab. Wait for a new pop-up window to appear. The window should look like the image below.

_images/ventmapper_vent_popup.png ventricle pop up window

Click “Select t1w” and chose your T1 image. Click “Run”. Click either or both “Select t2w” and “Select flair” (with respect to the sequences you have) and select the correspending images. Type your desired output name in the “out” box. Check the box next to “force” if you want to overwrite a previous output. Click “Run”. Your output file will automatically appear in your t1w folder.

Command Line¶

ventmapper seg_vent

Optional arguments:
-h, --help            show this help message and exit
-s , --subj           input subject
-fl , --flair         input Flair
-t1 , --t1w           input T1-weighted
-t2 , --t2w           input T2-weighted
-m , --mask           brain mask
-o , --out            output prediction
-f, --force           overwrite existing segmentation
-ss , --session       input session for longitudinal studies

Examples:
ventmapper seg_vent -s subjectname -b
ventmapper seg_vent -t1 subject_T1_nu.nii.gz -o subject_vent.nii.gz

The output should look like this.:

_images/vent_seg_example.png ventricle segmentation

Issues¶

Docker / Singularity¶

If you intend to use Singularity, scroll down to the Singularity section. Otherwise, the steps to use the image in Docker can be found below.

Before using Docker image for VentMapp3r¶

If you want to use Docker to run VentMapp3r, you must first install Docker on your system. While the installation method differs per system, instructions can be found for the following:

Once Docker is installed, open the docker terminal and test it with the command

docker run hello-world

Pulling VentMapp3r’s Docker immge¶

While you can download various Docker images, for the sake of this tutorial pull the VentMpp3r image

docker pull mgoubran/ventmapper:latest

Verify that the image was pulled successfully by checking all images on your system

docker images

Running the Docker image¶

If you have installed Docker for the first time. and have verified that the hello-world image was running, then VentMapper can be run on your syste.

The simplest way to run the container is:

docker run -it mgoubran/ventmapper seg_vent -t1 /VentMapp3r/data/test_case/mprage.nii.gz

Using VentMapper on Singularity¶

Docker images can still be used on Singularity. This is especially good if you are processing images using Compute Canada clusters. The following instructions are based on the steps provided on the Compute Canada wiki.

Load the specific Singularity module you would like to use.

module load singularity/3.5

Although VentMapper is stored as a Docker image, it can be built in singularity by calling:

singularity build ventmapper.sif docker://mgoubran/ventmapper

To ensure that the Docker image has been built in Singularity, run

singularity exec ventmapper.sif ventmapper --help