gamorosino/preopmap repository overview

⁠PreOpMap

PreOpMap is a tool that performs the registration to the Atlas template (MNI152) in order to warp the ROIs of a cortical and subcortical functional atlas based on Direct Electrical Stimulation (DES) from awake brain surgeries⁠ to T1-w subject space.

The tool consists of two major parts:

• Preprocessing of the input T1-w images
• Registration to the template and warp the labels of the atlas to the subject space.

The preprocessing is composed by 3 steps:

1. AC-PC (anterior and posterior commissure) alignment, through rigid registration with the template.
2. Whole brain mask estiamtion obtained by means of a deep learning network (3D U-Net).
3. Bias Field Correction (N4-ITK).

After preprocessing, the T1-w is registered to the tempalte (MNI152, T1 1mm) and then the specific labels selected are warped to the native subject space, applying the inverse of the transformations.

The registration could be Affine or Non-linear (Symmetric Diffeomorphic). In the case of Non-linear transformation, the tumor mask is mandatory as input.

⁠Author

Gabriele Amorosino ([email protected]⁠)

⁠Contributors

Paolo Avesani ([email protected]⁠)

⁠Reference

If you use this code for your research please cite:

Sarubbo S, Annicchiarico L, Corsini F, Zigiotto L, Herbet G, Moritz-Gasser S, Dalpiaz C, Vitali L, Tate M, De Benedictis A, Amorosino G, Olivetti E, Rozzanigo U, Petralia B, Duffau H, Avesani P. Planning Brain Tumor Resection Using a Probabilistic Atlas of Cortical and Subcortical Structures Critical for Functional Processing: A Proof of Concept. Oper Neurosurg (Hagerstown). 2021 Feb 16;20(3):E175-E183. doi: 10.1093/ons/opaa396. PMID: 33372966.

⁠Usage

⁠Create and Run the docker

To use the docker it is first necessary to create the container by pulling the image. For example you can do:

docker create --interactive --tty --name preopmap --mount type=bind,source="$HOME",target=/mnt --user $(id -u):$(id -g) --restart always gamorosino/preopmap bash

where the local home is mounted in the docekr as /mnt

Then you have to start the docker as:

docker start preopmap

Then you can run the script PreOpMap.sh embedded into the docker, for exampe, to warp the label Alexia_cort_P on the T1 present on the local home:

docker exec -it preopmap bash -ic "bash PreOpMap/PreOpMap.sh -i /mnt/T1.nii.gz -c Alexia_cort_P.nii.gz -l -o /mnt/PreOpMap_output "

where the output is stored in /mnt/PreOpMap_output i.e. in the local machine ${HOME}'/PreOpMap_output'

⁠Script Usage

The tool can be used through the PreOpMap.sh script.

PreOpMap.sh [-h] -i <filename> -c <list/filename> -s <list/filename> [-o <filename>]  [-t <filename>] [Options] 


Main arguments:

  -i, --input=<filename>            Input T1-w image. It could be a NifTI file, a dicom folder or a zip cointainting dicoms 
  -c, --cortical-rois=<list>        List of cortical Rois (labels) to be warped to the input T1-w image. Could be 
                                    a comma-separated list or a text file, where each row is a different label.
  -s, --subcortical-rois=<list>     List of subcortical Rois (labels) to be warped to the input T1-w image. Could
                                    be a comma-separated list or a text file, where each row is a different label.
  -t, --tumor-mask=<filename>       Mask of the Brain Tumor (not required if --no-nonlin is set)
   
  -o, --outputdir=<folder>          Output folder. If not specified, the script creates a folder in the input
                                    image directory, with the name as the basename of the input file and the suffix
                                    "_PreOpMap"    
Optional arguments:

  -m, --mask=<filename>             Explicit Full path of T1-w brain mask. If not set, the mask will be estimated 
                                    using a pre-trained 3D U-Net
  -l, --no-nonlin                   Turn off the step that does non-linear transformation
  
  -z, --zip-output                  creates a zip file of the output warped ROIs in the subject space (one zip file
                                    for the cortical rois and one zip file for the subcortical rois)
  -n, --nthreads=<num>              Number of threads used for multithreading operations (defalt=1)
  
  -q, --quality-control             generates two images (one for cortical ROIs and one for subcortical ROIs) composed of 
                                    the T1 image in different slices with the different warped ROIs superimposed.
                                    
  -b, --for-testing                 Set up a few iterations in the registration process (just for testing the script)
  -f, --force                       Force overwrite of output files
  -v, --verbose                     Verbose output
  -h, --help                        Show this help message
  

⁠Output files

The warped ROIs are stored in the output folder (-o, --outputdir) under the subfolder "CorticalROIs_<transform>Warped_SbjSpace/" for the cortical ROIs and "SubCorticalROIs_<transform>Warped_SbjSpace/" for the subcortical ROIs (where the suffix <transform> is Affine in the case of -l, --no-nonlin option, Syn otherwise).

In the case of -z, --zip-output the output folders are compressed in two differnt zip files, one zip file for the cortical ROIs and one zip file for the subcortical ROIs, with the same name as the folder and with the extension .zip.

⁠Examples

Example1: In the case of Non-linear registration to the template, the -t, --tumor-mask input is mandatory.

PreOpMap.sh -i T1.nii -t Tumor_mask.nii -c Anomia_cort_K,Alexia_cort_P -s Anomia_subcort_N

In that case, the list of rois to be projected is provided as a comma separated list

Example2:

In the case of Affine registration, the option -l, --no-nonlin must be specified.

PreOpMap.sh -i T1.nii.gz --no-nonlin -s subcortical.txt -c cortical.txt

In that case, for example, the subcortical list and cortical list is provided as plain text with a row for each label to warp. In this example, the cortical.txt could be a .txt file with two rows as:

Anomia_cort_P
Alexia_cort_P

⁠Brain Mask

The brain mask can also be provided as the m, --mask input and then the script will skip the mask estimation step in the preprocessing stage. The mask must be in the space of the input T1-w image.

⁠Acknowledgement

This docker was developed in the context of the AIMED - Artificial Intelligence in MEDicine project.