MR-CLOVER (Tool for Assessing MR-based Clinical resOlution brain VolumEtRics) is a Python-based pipeline that combines publicly available tools from ANTs and Freesurfer to extract the brain from clinical MRI scans and return segmented grey and white matter masks. It facilitates various MRI image processing tasks, including bias field correction, brain extraction, intensity normalization, and intracranial volume segmentation using advanced computational methods.
The pipeline is modular - each processing step is only executed when its corresponding output is requested, allowing for flexible usage from simple skull stripping to comprehensive tissue segmentation.
This is what the pipeline looks like:
- Modular Pipeline: Run only the components you need - each output triggers its required processing steps
- Bias Field Correction: Adjusts the MRI scan to minimize intensity inhomogeneities (dual-pass correction available)
- Brain Extraction: Segments the brain from the surrounding skull and other non-brain structures using SynthStrip
- Intensity Normalization: Standardizes the intensity values across different scans for consistent analysis
- Grey/White Matter Segmentation: Segments and masks grey and white matter within the extracted brain
- Intracranial Volume Calculation: Optionally calculates the total intracranial volume (ICV) using SynthSeg
- Quality Validation: Automatic validation of ICV masks to detect segmentation failures
- Color-coded Logging: Clear visual feedback with color-coded error, warning, success, and debug messages
- Debug Mode: Keep intermediate files and get verbose output for troubleshooting
- Smart Resource Management: Automatically detects and uses optimal number of CPU threads
- GPU Acceleration: Optional GPU support for SynthStrip and SynthSeg (requires NVIDIA GPU with CUDA)
- Modular Architecture: Pipeline components now run only when their outputs are requested
- Enhanced Error Handling: Comprehensive validation checks with informative color-coded messages
- ICV Validation: Basic, automatic detection of ICV segmentation failures
- Improved SynthSeg Integration: Uses
--keepgeomflag to eliminate registration step,--robustfor better quality - Smart Threading: Automatically uses 90% of available CPU cores for optimal performance
- Debug Mode: New
--debugflag for keeping temporary files and verbose output - Optional Parcellation: Added
--parcflag for SynthSeg parcellation output
- Python 3.x
- NumPy
- SciPy
- scikit-image
- ANTs (Advanced Normalization Tools)
- Freesurfer (specifically mri_synthstrip and mri_synthseg)
- Warnings module for handling potential errors during execution
Ensure that all dependencies are installed using pip:
pip install -r requirements.txtANTs and Freesurfer need to be installed separately. Please see the corresponding websites for instructions.
Clone the repository or download the source code from GitHub. No additional setup is required beyond ensuring the required libraries are installed.
To use MR-CLOVER, prepare your MRI data in NIfTI format and run the tool from the command line. The pipeline is modular - it will only run the processing steps needed for your requested outputs.
Simple brain extraction only:
python mr_clover.py -i patient.nii.gz --brain brain_mask.nii.gzBias correction only:
python mr_clover.py -i patient.nii.gz --bias bias_corrected.nii.gzFull pipeline with GM/WM segmentation:
python mr_clover.py -i patient.nii.gz -o gmwm_mask.nii.gzComplete processing with all outputs:
python mr_clover.py -i patient.nii.gz -o gmwm_mask.nii.gz --brain brain_mask.nii.gz --icv icv_mask.nii.gz --norm normalized.nii.gz --bias bias_corrected.nii.gz --stats volumes.csv-i: Input NIfTI image file
-o: Output grey/white matter mask (triggers intensity normalization + GM/WM segmentation)--brain: Output brain mask from skull stripping--icv: Output intracranial volume mask (triggers SynthSeg)--norm: Output intensity-normalized brain image--bias: Output bias field corrected image--stats: Output CSV file with volumes and normalization values
--sub: Subject ID for statistics file (defaults to input filename)--gpu: Enable GPU acceleration (requires NVIDIA GPU with CUDA)--parc: Enable parcellation output from SynthSeg--debug: Enable debug mode (keeps temporary files, verbose output)
The pipeline intelligently determines which processing steps to run based on your requested outputs:
- Core steps (always run): Initial bias correction → Brain extraction
- Second bias correction: Only if
--bias,--norm, or-ospecified - Intensity normalization: Only if
--normor-ospecified - GM/WM segmentation: Only if
-ospecified - ICV extraction: Only if
--icvspecified
- Currently optimized for CSF-dark modalities (T1, FLAIR)
- GM/WM segmentation uses simple thresholding (GMM-based refinement planned for v0.4)
- Future versions will support T2 and other modalities using SynthSeg tissue masks for normalization
MR-CLOVER is an open-source project developed by MDS at Massachusetts General Hospital and Harvard Medical School. Contributions are welcome, particularly in improving the algorithms for brain tissue segmentation and volume calculation.
For issues, suggestions, or contributions, please contact the lead developer at mschirmer1@mgh.harvard.edu.
If you find this tool useful for your work, please cite:
[1] Alhadid, Kenda, et al. "Brain volume is a better biomarker of outcomes in ischemic stroke compared to brain atrophy." arXiv preprint arXiv:2403.12788 (2024).
Please also cite the relevant papers for ANTs and the Freesurfer packages SynthStrip and SynthSeg.
- 0.3 (January 2025): Major refactoring with modular architecture, enhanced error handling, ICV validation, and debug mode
- 0.2 (March 2024): Latest stable release with enhanced feature set and performance improvements compared to the tools found in WMHP
Feel free to reach out or contribute to making MR-CLOVER a more robust tool for clinical and research applications in neuroimaging!