petermcgor/corles-seg-flaws-based repository overview

⁠Cortical Lesion Segmentation using MP2RAGE and FLAWS

⁠Overview

This Docker container implements the cortical lesion segmentation approach presented in:

Gordaliza, P. M., Müller, J., Cagol, A., Molchanova, N., La Rosa, F., Tsagkas, C., Granziera, C., & Bach Cuadra, M. (2025). Fluid and White Matter Suppression Contrasts MRI Improves Deep Learning Detection of Multiple Sclerosis Cortical Lesions. Preprint, DOI: 10.1101/2025.01.19.25320792

The implementation offers an automated solution for cortical lesion segmentation using deep learning, specifically optimized for MP2RAGE and FLAWS MRI sequences. Built upon the nnU-Net framework, it provides state-of-the-art segmentation performance through an easy-to-use interface.

The segmentation model can work with three different input configurations:

1. MP2RAGE (T1) images only
2. FLAWS (HCO and MIN) images only
3. Combined MP2RAGE and FLAWS images

⁠Prerequisites

• NVIDIA GPU with CUDA support
• NVIDIA Docker runtime
• Docker installed on your system
• Input images in NIfTI format (.nii.gz or .nii)

⁠Input Data Requirements

Your input data must follow these guidelines:

1. All images must be in NIfTI format (.nii.gz or .nii)
2. When using multiple sequences for the same subject, maintain consistent naming:

   sub-01_ses-01_T1w.nii.gz 
   sub-01_ses-01_FLAWS-HCO.nii.gz 
   sub-01_ses-01_FLAWS-MIN.nii.gz 
   

   Copy
3. Images should be pre-processed (skull-stripped and registered if necessary)

⁠Usage

Basic command structure:

docker run -it \
  -v /path/to/your/data:/data \
  --gpus device=0 \
  --shm-size=40gb \
  petermcgor/corles-seg-flaws-based:1.0.0 \
  predict \
  -i /data/input_folder \
  -o /data/output_folder \
  [options]

⁠Required Parameters

• -i: Input folder containing your images
• -o: Output folder for segmentation results
• One or more sequence suffix identifiers:
  • --mp2rage_suffix: Suffix for MP2RAGE images (e.g., "T1", "_0000" if you follow nnUNet format, ect.)
  • --flaws-hco_suffix: Suffix for FLAWS-HCO images (e.g., "HCO", "_0001" if you follow nnUNet format, ect.)
  • --flaws-min_suffix: Suffix for FLAWS-MIN images (e.g., "MIN", "_0002" if you follow nnUNet format, ect.)

⁠Optional Parameters

• -f: Specify which model folds to use (default: 0 1 2 3 4)
• -npp: Number of preprocessing processes (default: 3)
• -nps: Number of segmentation processes (default: 3)
• --save_probabilities: Save probability maps
• --disable_tta: Disable test-time augmentation
• --verbose: Enable detailed output
• --disable_progress_bar: Hide progress bar
• --device: Choose computing device (cuda/cpu/mps)

⁠Examples

1. Using MP2RAGE only:

docker run -it \
  -v /path/to/data:/data \
  --gpus device=0 \
  --shm-size=40gb \
  petermcgor/corles-seg-flaws-based:1.0.0 \
  predict \
  -i /data/input \
  -o /data/output \
  --mp2rage_suffix _0000

1. Using all sequences with custom parameters:

docker run -it \
  -v /path/to/data:/data \
  --gpus device=0 \
  --shm-size=40gb \
  petermcgor/corles-seg-flaws-based:1.0.0 \
  predict \
  -i /data/input \
  -o /data/output \
  --mp2rage_suffix T1 \
  --flaws-hco_suffix HCO \
  --flaws-min_suffix MIN \
  -npp 15 -nps 15 \
  --save_probabilities

⁠Resource Requirements and Recommendations

The implementation benefits from powerful computing resources to ensure optimal performance. The container requires an NVIDIA GPU with CUDA support. For optimal performance, we recommend utilizing systems with substantial RAM, as this allows you to increase the number of parallel processes (-npp and -nps parameters) to speed up processing. The default values (npp=3, nps=3) are conservative and can be increased based on your system's available memory.

⁠Implementation Notes

This implementation builds upon the nnU-Net framework, inheriting its robust architecture while specializing in cortical lesion segmentation. While many parameters align with standard nnU-Net usage, we have made specific adaptations for our use case:

1. Sequence Handling: We've added specialized parameters for handling different MRI sequence combinations:

   • MP2RAGE-only processing
   • FLAWS-only processing (HCO and MIN)
   • Combined MP2RAGE and FLAWS processing

2. Simplified Parameters: We've streamlined the interface by removing nnU-Net parameters that aren't relevant for cortical lesion segmentation, making the tool more focused and user-friendly.

3. Fixed Configurations: Some nnU-Net parameters have been fixed to their optimal values for our specific use case, reducing the complexity of usage while maintaining high performance.

For users familiar with nnU-Net, most command-line parameters maintain their original functionality, though some have been preset to optimal values for cortical lesion segmentation. The main additions are the sequence-specific parameters (--mp2rage_suffix, --flaws-hco_suffix, --flaws-min_suffix) that facilitate our multi-sequence approach.

⁠Output

The container generates:

• Segmentation masks in NIfTI format
• Probability maps (if --save_probabilities is used)
• Each output file maintains the naming convention of its input

⁠Troubleshooting

Common issues and solutions:

1. Out of memory errors: Reduce -npp and -nps values
2. File not found: Check input file naming and suffixes
3. GPU issues: Ensure correct NVIDIA drivers and proper --gpus flag

⁠Citation

If you use this tool in your research, please cite:

Gordaliza, P. M., Müller, J., Cagol, A., Molchanova, N., La Rosa, F., Tsagkas, C., Granziera, C., & Bach Cuadra, M. (2025). Fluid and White Matter Suppression Contrasts MRI Improves Deep Learning Detection of Multiple Sclerosis Cortical Lesions, DOI: 10.1101/2025.01.19.25320792⁠

⁠and

Müller, J., La Rosa, F., Beaumont, J., Tsagkas, C., Rahmanzadeh, R., Weigel, M., Bach Cuadra, M., Gambarota, G., & Granziera, C. (2022). Fluid and White Matter Suppression: New Sensitive 3 T Magnetic Resonance Imaging Contrasts for Cortical Lesion Detection in Multiple Sclerosis, Investigative Radiology, 57(9), 592-600. DOI: 10.1097/RLI.0000000000000877⁠

⁠besides, the model is deployed from

Isensee, F., Jaeger, P. F., Kohl, S. A. A., et al. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation, Nature Methods, 18, 203-211. DOI: 10.1038/s41592-020-01008-z⁠

⁠License

[License information to be added]

⁠Contact

For issues, questions, or contributions:

• Maintainer: Pedro Macias Gordaliza
• Email: [email protected]⁠

⁠Acknowledgments

This implementation uses the nnU-Net framework and builds upon previous work in medical image segmentation.