phwegner/enigma repository overview

⁠Project description

The ENIGMA-Ataxia working group has developed this application for FastSurfer and Cerebnet segmentation for event-based modeling analysis of SCA data based on T1-weighted anatomical MRI images. This project aims to define a temporal order of atrophic events in cerebral and cerebellar regions for patient stratification in SCA1, SCA2, SCA3, and SCA6.

This application is freely available for use by the neuroimaging community. If you use this procedure in your work, please acknowledge the ---->>>>>>ENIGMA-Ataxia working group, and provide appropriate attribution & citation of the constituent software, including FreeSurfer/Fastsurfer (https://doi.org/10.1016%2Fj.neuroimage.2012.01.021⁠, https://doi.org/10.1016/j.neuroimage.2022.119703⁠).

Contacts: Jennifer Faber: [email protected]⁠ Mónica Ferreira: [email protected]⁠ Philipp Wegner: [email protected]⁠

⁠Workflow

⁠Requirements & Setup

1. Install Docker (https://www.docker.com/⁠) or Singularity (https://docs.sylabs.io/guides/3.5/user-guide/introduction.html⁠)
2. Get a valid Freesurfer license $\rightarrow$ https://surfer.nmr.mgh.harvard.edu/fswiki/License⁠
3. Pull the image 3.1 Docker: docker pull phwegner/enigma:latest 3.2 Singularity: singularity pull docker://phwegner/enigma:latest (4.) Make sure your system meets the requirements of FastSUrfer/Freesurfer. We recommend at least 16GB of RAM and 4 CPUs. FastSurfer will use a GPU is available.

⁠Required Directory Structure and Data Set-Up

The application expects the following organization of subjects in a folder structure.

⁠Folder Structure

base_folder
    |----input  
    |        |----subj_001_t1.nii.gz
    |        |----subj_002_t1.nii.gz
    |        |----...
    |

⁠Running the application

1. Docker

docker run -it --rm --user $(id -u):$(id -g) -v <YOUR_SUBJECTS_BASE_DIR>:/subjects_indir -v <YOUR_FS_LICENSE>:/license.txt phwegner/enigma

1.1. Example for Docker:

docker run -it --rm --user $(id -u):$(id -g) -v /home/dzne/base_folder:/subjects_indir -v /home/software/freesurfer/license.txt:/license.txt phwegner/enigma

1. Singularity

singularity run -B <YOUR_SUBJECTS_BASE_DIR>:/subjects_indir -B <YOUR_FS_LICENSE>:/license.txt --pwd /fastsurfer enigma_latest.sif

2.1. Example for Singularity:

singularity run -B /home/dzne/base_folder:/subjects_indir -B /home/software/freesurfer/license.txt:/license.txt --pwd /fastsurfer enigma_latest.sif

⁠Segmentation Quality Control:

Prior to segmentation using this container, images should be checked for artefacts and quality. Artefacts or lesions that influence brain anatomy, and images with visible motion artefact (e.g., ripples in the T1w image) should be noted, although not necessarily immediately excluded unless severe. These images will require close visual QC after segmentation.

Note that retrocerebellar arachnoid cysts are a common incidental finding in the general population. Although these are (unlikely) to be pathogenic, when large they will compress the cerebellum and result in non-representative volume estimates. Currently, we don’t have specific advice about how large is too large, but if there is clear deformation of the structure of the cerebellum, then these images should be excluded.

After running the container, the ‘outputs’ folder will contain a QC website (called ‘index.html’, in the ‘qc_webpage’ folder) and a file that flags potentially problematic scans (‘classifier_out_bad_scans.txt’). Open the html file using a web browser, and quickly examine each image segmentation to confirm accuracy. All images should be examined, not just those identified as bad scans. Extra scrutiny should be given to the bad scans and those flagged in step 1 for motion or artifacts. If in doubt, the segmentations should be loaded in an image viewer (e.g., FSLEyes, MRICron, etc) and examined more closely. If the segmentations look accurate, the scan can be retained; otherwise, the scan should be marked for exclusion from subsequent analysis.

⁠Parallelization

If you face a situation where you have a lot of subjects and want to process some of them in parallel instead of sequentially, the container provides a script, that splits your input folder into batches on which you can run the main application on each in parallel. You run the script like this:

docker run --rm -v /path/to/input_folder:/tmp/input -v /path/to/output_folder:/tmp/output phwegner/enigma bash /app/scripts/split_folders.sh /tmp/input <k> /tmp/output

Now you can run the application on each folder created in /path/to/output_folder .

⁠Troubleshoot

For any issues please contact [email protected]⁠

⁠Known Issues

If you get any permission error, make sure your base_folder is readable and writable by your user.

If you abort a run or it fails, clean the input directory. That means ensuring that your base_folder only holds the input directory and no other subfolders or intermediates generated by prior runs.

If you run the pipeline as a SLURM job, make sure that your job has enough memory allocated we recommend at least 16GB.

If you get an error of the form: 'permission denied bash entrypoint.sh', replace the run command with: singularity exec <YOUR_SUBJECTS_BASE_DIR>:/subjects_indir -B <YOUR_FS_LICENSE>:/license.txt --pwd /fastsurfer enigma_latest.sif /app/scripts/main.sh

⁠Generated output

Note that the sned_to_dzne.zip is the entire output needed to be sent to the DZNE. If any corrupted scans were found you can inspect them using the qc_webpage folder in which a single index.html file that displays the faulty scans in several slices.

|-- bad_scans
|   `-- subj-002
|       |-- mri
|       |   |-- aparc.DKTatlas+aseg.deep.mgz
|       |   |-- aseg.auto_noCCseg.mgz
|       |   |-- cerebellum.CerebNet.nii.gz
|       |   |-- mask.mgz
|       |   |-- orig
|       |   |   `-- 001.mgz
|       |   |-- orig.mgz
|       |   `-- orig_nu.mgz
|       |-- scripts
|       |   `-- deep-seg.log
|       `-- stats
|           |-- aseg+DKT.stats
|           `-- cerebellum.CerebNet.stats
|-- fastsurfer
|   `-- subj-001
|       |-- mri
|       |   |-- aparc.DKTatlas+aseg.deep.mgz
|       |   |-- aseg.auto_noCCseg.mgz
|       |   |-- cerebellum.CerebNet.nii.gz
|       |   |-- mask.mgz
|       |   |-- orig
|       |   |   `-- 001.mgz
|       |   |-- orig.mgz
|       |   `-- orig_nu.mgz
|       |-- scripts
|       |   `-- deep-seg.log
|       `-- stats
|           |-- aseg+DKT.stats
|           `-- cerebellum.CerebNet.stats
|-- input
|   `-- subj-001
|       |-- T1_bet_mask.nii.gz
|       |-- T1_bet.nii.gz
|       `-- T1.nii.gz
|-- outputs
|   |-- classifier_out_bad_scans.txt
|   |-- classifier_out.txt
|   |-- outliers.txt
|   |-- qc_webpage
|   `-- volumes_all.csv
`-- send_to_dzne.zip