brainles-preprocessing 0.5.0__tar.gz → 0.6.1__tar.gz

{brainles_preprocessing-0.5.0 → brainles_preprocessing-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: brainles_preprocessing
-Version: 0.5.0
+Version: 0.6.1
 Summary: Tool for preprocessing tasks in biomedical imaging, with a focus on (but not limited to) multi-modal brain MRI
 License: Apache-2.0
 Keywords: brain tumor,glioma,BraTS,skullstripping,brain extraction
@@ -21,9 +21,9 @@ Provides-Extra: itk-elastix
 Provides-Extra: picsl-greedy
 Requires-Dist: antspyx (>=0.5.4,<1.0.0)
 Requires-Dist: auxiliary (>=0.3.1)
-Requires-Dist: black (>=22.1.0,<23.0.0)
 Requires-Dist: brainles_hd_bet (>=0.0.10,<1.0.0)
 Requires-Dist: itk-elastix (>=0.20.0,<0.21.0) ; extra == "all" or extra == "itk-elastix"
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
 Requires-Dist: nibabel (>=3.2.1)
 Requires-Dist: numpy (>=1.23.0,<2.0.0)
 Requires-Dist: pathlib (>=1.0.1,<2.0.0)
@@ -150,9 +150,25 @@ For further information please have a look at our [Jupyter Notebook tutorials](h
 
 
 
+## Citation
 
+> [!IMPORTANT]
+> If you use `brainles-preprocessing` in your research, please cite it to support the development!
 
-<!-- TODO citation -->
+Kofler, F., Rosier, M., Astaraki, M., Möller, H., Mekki, I. I., Buchner, J. A., Schmick, A., Pfiffer, A., Oswald, E., Zimmer, L., Rosa, E. de la, Pati, S., Canisius, J., Piffer, A., Baid, U., Valizadeh, M., Linardos, A., Peeken, J. C., Shit, S., … Menze, B. (2025). *BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis* [arXiv preprint arXiv:2507.09036](https://doi.org/10.48550/arXiv.2507.09036)
+
+
+```
+@misc{kofler2025brainlesionsuiteflexibleuserfriendly,
+      title={BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis}, 
+      author={Florian Kofler and Marcel Rosier and Mehdi Astaraki and Hendrik Möller and Ilhem Isra Mekki and Josef A. Buchner and Anton Schmick and Arianna Pfiffer and Eva Oswald and Lucas Zimmer and Ezequiel de la Rosa and Sarthak Pati and Julian Canisius and Arianna Piffer and Ujjwal Baid and Mahyar Valizadeh and Akis Linardos and Jan C. Peeken and Surprosanna Shit and Felix Steinbauer and Daniel Rueckert and Rolf Heckemann and Spyridon Bakas and Jan Kirschke and Constantin von See and Ivan Ezhov and Marie Piraud and Benedikt Wiestler and Bjoern Menze},
+      year={2025},
+      eprint={2507.09036},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2507.09036}, 
+}
+```
 
 ## Documentation
 We provide a (WIP) documentation. Have a look [here](https://brainles-preprocessing.readthedocs.io/en/latest/?badge=latest)
@@ -161,11 +177,17 @@ We provide a (WIP) documentation. Have a look [here](https://brainles-preprocess
 Please credit the authors by citing their work.
 
 ### Registration
-We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default), [Niftyreg](https://github.com/KCL-BMEIS/niftyreg) (Linux).
+We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default), [Niftyreg](https://github.com/KCL-BMEIS/niftyreg) (Linux). We also offer basic support for [greedy](https://greedy.readthedocs.io/en/latest/reference.html#greedy-usage) and [elastix](https://pypi.org/project/itk-elastix/0.13.0/).
 
 ### Atlas Reference
-We provide the SRI-24 atlas from this [publication](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2915788/).
-However, custom atlases in NIfTI format are supported.
+We provide a range of different atlases, namely:
+-  [SRI24](https://www.nitrc.org/frs/download.php/4502/sri24_anatomy_unstripped_nifti.zip) and its [skull-stripped version](https://www.nitrc.org/frs/download.php/4499/sri24_anatomy_nifti.zip)
+-  A slightly modified SRI24 atlas as found in the BraTS challenges (also with a skull-stripped version)
+-  MNI152: [MNI_ICBM_2009c_Nonlinear_Symmetric](https://nist.mni.mcgill.ca/icbm-152-nonlinear-atlases-2009/)
+-  A slightly modified MNI152 atlas as found in the BraTS challenge 
+
+We also support supplying a custom atlas in NIfTI format
+
 
 ### N4 Bias correction
 We currently provide support for N4 Bias correction based on [SimpleITK](https://simpleitk.org/)

{brainles_preprocessing-0.5.0 → brainles_preprocessing-0.6.1}/README.md

@@ -111,9 +111,25 @@ For further information please have a look at our [Jupyter Notebook tutorials](h
 
 
 
+## Citation
 
+> [!IMPORTANT]
+> If you use `brainles-preprocessing` in your research, please cite it to support the development!
 
-<!-- TODO citation -->
+Kofler, F., Rosier, M., Astaraki, M., Möller, H., Mekki, I. I., Buchner, J. A., Schmick, A., Pfiffer, A., Oswald, E., Zimmer, L., Rosa, E. de la, Pati, S., Canisius, J., Piffer, A., Baid, U., Valizadeh, M., Linardos, A., Peeken, J. C., Shit, S., … Menze, B. (2025). *BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis* [arXiv preprint arXiv:2507.09036](https://doi.org/10.48550/arXiv.2507.09036)
+
+
+```
+@misc{kofler2025brainlesionsuiteflexibleuserfriendly,
+      title={BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis}, 
+      author={Florian Kofler and Marcel Rosier and Mehdi Astaraki and Hendrik Möller and Ilhem Isra Mekki and Josef A. Buchner and Anton Schmick and Arianna Pfiffer and Eva Oswald and Lucas Zimmer and Ezequiel de la Rosa and Sarthak Pati and Julian Canisius and Arianna Piffer and Ujjwal Baid and Mahyar Valizadeh and Akis Linardos and Jan C. Peeken and Surprosanna Shit and Felix Steinbauer and Daniel Rueckert and Rolf Heckemann and Spyridon Bakas and Jan Kirschke and Constantin von See and Ivan Ezhov and Marie Piraud and Benedikt Wiestler and Bjoern Menze},
+      year={2025},
+      eprint={2507.09036},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2507.09036}, 
+}
+```
 
 ## Documentation
 We provide a (WIP) documentation. Have a look [here](https://brainles-preprocessing.readthedocs.io/en/latest/?badge=latest)
@@ -122,11 +138,17 @@ We provide a (WIP) documentation. Have a look [here](https://brainles-preprocess
 Please credit the authors by citing their work.
 
 ### Registration
-We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default), [Niftyreg](https://github.com/KCL-BMEIS/niftyreg) (Linux).
+We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default), [Niftyreg](https://github.com/KCL-BMEIS/niftyreg) (Linux). We also offer basic support for [greedy](https://greedy.readthedocs.io/en/latest/reference.html#greedy-usage) and [elastix](https://pypi.org/project/itk-elastix/0.13.0/).
 
 ### Atlas Reference
-We provide the SRI-24 atlas from this [publication](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2915788/).
-However, custom atlases in NIfTI format are supported.
+We provide a range of different atlases, namely:
+-  [SRI24](https://www.nitrc.org/frs/download.php/4502/sri24_anatomy_unstripped_nifti.zip) and its [skull-stripped version](https://www.nitrc.org/frs/download.php/4499/sri24_anatomy_nifti.zip)
+-  A slightly modified SRI24 atlas as found in the BraTS challenges (also with a skull-stripped version)
+-  MNI152: [MNI_ICBM_2009c_Nonlinear_Symmetric](https://nist.mni.mcgill.ca/icbm-152-nonlinear-atlases-2009/)
+-  A slightly modified MNI152 atlas as found in the BraTS challenge 
+
+We also support supplying a custom atlas in NIfTI format
+
 
 ### N4 Bias correction
 We currently provide support for N4 Bias correction based on [SimpleITK](https://simpleitk.org/)

{brainles_preprocessing-0.5.0 → brainles_preprocessing-0.6.1}/brainles_preprocessing/constants.py

@@ -24,3 +24,6 @@ class Atlas(str, Enum):
 
     BRATS_MNI152 = "brats_MNI152lin_T1_1mm.nii.gz"
     """Slightly modified MNI152 atlas as found in the BraTS challenges"""
+
+    MNI152 = "mni_icbm152_t1_tal_nlin_sym_09c.nii"
+    """MNI_ICBM_2009c_Nonlinear_Symmetric atlas from https://nist.mni.mcgill.ca/icbm-152-nonlinear-atlases-2009/"""

{brainles_preprocessing-0.5.0 → brainles_preprocessing-0.6.1}/brainles_preprocessing/defacing/quickshear/quickshear.py

@@ -6,6 +6,7 @@ from auxiliary.io import read_image, write_image
 
 from brainles_preprocessing.defacing.defacer import Defacer
 from brainles_preprocessing.defacing.quickshear.nipy_quickshear import run_quickshear
+from brainles_preprocessing.constants import Atlas
 
 
 class QuickshearDefacer(Defacer):
@@ -29,14 +30,23 @@ class QuickshearDefacer(Defacer):
             ```
     """
 
-    def __init__(self, buffer: float = 10.0):
+    def __init__(
+        self,
+        buffer: float = 10.0,
+        force_atlas_registration: bool = True,
+        atlas_image_path: Union[str, Path, Atlas] = Atlas.SRI24,
+    ):
         """Initialize Quickshear defacer
 
         Args:
             buffer (float, optional): buffer parameter from quickshear algorithm. Defaults to 10.0.
+            force_atlas_registration (bool, optional): If True, forces atlas registration of the BET mask before defacing to potentially boost quickshear performance. Defaults to True.
+            atlas_image_path (Union[str, Path, Atlas], optional): Path to the atlas image or an Atlas enum value that will be used for the optional atlas registrations. Defaults to Atlas.SRI24.
         """
         super().__init__()
         self.buffer = buffer
+        self.force_atlas_registration = force_atlas_registration
+        self.atlas_image_path = atlas_image_path
 
     def deface(
         self,

{brainles_preprocessing-0.5.0 → brainles_preprocessing-0.6.1}/brainles_preprocessing/modality.py

@@ -5,9 +5,10 @@ from pathlib import Path
 from typing import Dict, Optional, Union
 
 from auxiliary.io import read_image, write_image
+from loguru import logger
 
 from brainles_preprocessing.brain_extraction.brain_extractor import BrainExtractor
-from brainles_preprocessing.constants import PreprocessorSteps
+from brainles_preprocessing.constants import Atlas, PreprocessorSteps
 from brainles_preprocessing.defacing import Defacer, QuickshearDefacer
 from brainles_preprocessing.normalization.normalizer_base import Normalizer
 from brainles_preprocessing.registration import (  # TODO: this will throw warnings if ANTs or NiftyReg are not installed, not ideal
@@ -15,8 +16,7 @@ from brainles_preprocessing.registration import (  # TODO: this will throw warni
     NiftyRegRegistrator,
 )
 from brainles_preprocessing.registration.registrator import Registrator
-
-logger = logging.getLogger(__name__)
+from brainles_preprocessing.utils.zenodo import verify_or_download_atlases
 
 
 class Modality:
@@ -295,7 +295,7 @@ class Modality:
         if self.bet:
             mask_path = Path(mask_path)
             bet_dir = Path(bet_dir)
-            bet_img = bet_dir / f"atlas__{self.modality_name}_bet.nii.gz"
+            bet_img = bet_dir / f"{self.modality_name}_bet.nii.gz"
 
             brain_extractor.apply_mask(
                 input_image_path=self.current,
@@ -324,14 +324,27 @@ class Modality:
         if self.requires_deface:
             mask_path = Path(mask_path)
             deface_dir = Path(deface_dir)
-            defaced_img = deface_dir / f"atlas__{self.modality_name}_defaced.nii.gz"
-            input_img = self.steps[
-                (
-                    PreprocessorSteps.ATLAS_CORRECTED
-                    if self.atlas_correction
-                    else PreprocessorSteps.ATLAS_REGISTERED
+            defaced_img = deface_dir / f"{self.modality_name}_defaced.nii.gz"
+
+            # For Atlas centric preprocessing, we use the atlas corrected or registered image as input
+            # For Native space preprocessing, we use the coregistered image as input
+            input_img = (
+                self.steps[
+                    (
+                        PreprocessorSteps.ATLAS_CORRECTED
+                        if self.atlas_correction
+                        else PreprocessorSteps.ATLAS_REGISTERED
+                    )
+                ]
+                or self.steps[PreprocessorSteps.COREGISTERED]
+            )
+
+            if input_img is None:
+                raise ValueError(
+                    "Input image for defacing is missing. Ensure that the required preprocessing steps "
+                    "have been performed before defacing."
                 )
-            ]
+
             defacer.apply_mask(
                 input_image_path=input_img,
                 mask_path=mask_path,
@@ -428,65 +441,40 @@ class Modality:
             "Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.",
             category=DeprecationWarning,
         )
-
         bet_dir_path = Path(bet_dir_path)
         bet_log = bet_dir_path / "brain-extraction.log"
 
-        atlas_bet_cm = bet_dir_path / f"atlas__{self.modality_name}_bet.nii.gz"
-        mask_path = bet_dir_path / f"atlas__{self.modality_name}_brain_mask.nii.gz"
+        bet = bet_dir_path / f"{self.modality_name}_bet.nii.gz"
+        mask_path = bet_dir_path / f"{self.modality_name}_brain_mask.nii.gz"
 
         brain_extractor.extract(
             input_image_path=self.current,
-            masked_image_path=atlas_bet_cm,
+            masked_image_path=bet,
             brain_mask_path=mask_path,
             log_file_path=bet_log,
         )
 
         # always temporarily store bet image for center modality, since e.g. quickshear defacing could require it
         # down the line even if the user does not wish to save the bet image
-        self.steps[PreprocessorSteps.BET] = atlas_bet_cm
+        self.steps[PreprocessorSteps.BET] = bet
 
         if self.bet:
-            self.current = atlas_bet_cm
+            self.current = bet
         return mask_path
 
     def deface(
         self,
         defacer,
         defaced_dir_path: Union[str, Path],
-    ) -> Path:
+        registrator: Optional[Registrator] = None,
+    ) -> Path | None:
         """
         WARNING: Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.
-
-        Deface the current modality using the specified defacer.
-
-        Args:
-            defacer (Defacer): The defacer object.
-            defaced_dir_path (str or Path): Directory to store defacing results.
-
-        Returns:
-            Path: Path to the extracted brain mask.
         """
-        warnings.warn(
-            "Legacy method. Please Migrate to use the CenterModality class. Will be removed in future versions.",
-            category=DeprecationWarning,
+        raise RuntimeError(
+            "The 'deface' method has been deprecated and moved to the CenterModality class as its only supposed to be called once from the CenterModality. "
+            "Please update your code to use the 'CenterModality.deface()' method instead."
         )
-        if isinstance(defacer, QuickshearDefacer):
-            defaced_dir_path = Path(defaced_dir_path)
-            atlas_mask_path = (
-                defaced_dir_path / f"atlas__{self.modality_name}_deface_mask.nii.gz"
-            )
-
-            defacer.deface(
-                mask_image_path=atlas_mask_path,
-                input_image_path=self.steps[PreprocessorSteps.BET],
-            )
-            return atlas_mask_path
-        else:
-            logger.warning(
-                "Defacing method not implemented yet. Skipping defacing for this modality."
-            )
-            return None
 
     def save_current_image(
         self,
@@ -612,6 +600,7 @@ class CenterModality(Modality):
         bet_dir_path: Union[str, Path],
     ) -> Path:
         """
+
         Extract the brain region using the specified brain extractor.
 
         Args:
@@ -621,66 +610,95 @@ class CenterModality(Modality):
         Returns:
             Path: Path to the extracted brain mask.
         """
+
         bet_dir_path = Path(bet_dir_path)
         bet_log = bet_dir_path / "brain-extraction.log"
 
-        atlas_bet_cm = bet_dir_path / f"atlas__{self.modality_name}_bet.nii.gz"
-        mask_path = bet_dir_path / f"atlas__{self.modality_name}_brain_mask.nii.gz"
+        bet = bet_dir_path / f"{self.modality_name}_bet.nii.gz"
+        mask_path = bet_dir_path / f"{self.modality_name}_brain_mask.nii.gz"
 
         brain_extractor.extract(
             input_image_path=self.current,
-            masked_image_path=atlas_bet_cm,
+            masked_image_path=bet,
             brain_mask_path=mask_path,
             log_file_path=bet_log,
         )
 
-        if self.bet_mask_output_path:
-            logger.debug(f"Saving bet mask to {self.bet_mask_output_path}")
-            self.save_mask(mask_path=mask_path, output_path=self.bet_mask_output_path)
-
         # always temporarily store bet image for center modality, since e.g. quickshear defacing could require it
         # down the line even if the user does not wish to save the bet image
-        self.steps[PreprocessorSteps.BET] = atlas_bet_cm
+        self.steps[PreprocessorSteps.BET] = bet
 
         if self.bet:
-            self.current = atlas_bet_cm
+            self.current = bet
         return mask_path
 
     def deface(
         self,
-        defacer,
+        defacer: Defacer,
         defaced_dir_path: Union[str, Path],
-    ) -> Path:
+        registrator: Optional[Registrator] = None,
+    ) -> Path | None:
         """
         Deface the current modality using the specified defacer.
 
         Args:
             defacer (Defacer): The defacer object.
             defaced_dir_path (str or Path): Directory to store defacing results.
+            registrator (Registrator, optional): The registrator object for atlas registration.
 
         Returns:
-            Path: Path to the extracted brain mask.
+            Path | None: Path to the defacing mask if successful, None otherwise.
         """
-
         if isinstance(defacer, QuickshearDefacer):
             defaced_dir_path = Path(defaced_dir_path)
-            atlas_mask_path = (
-                defaced_dir_path / f"atlas__{self.modality_name}_deface_mask.nii.gz"
-            )
+            mask_path = defaced_dir_path / f"{self.modality_name}_deface_mask.nii.gz"
 
-            defacer.deface(
-                mask_image_path=atlas_mask_path,
-                input_image_path=self.steps[PreprocessorSteps.BET],
-            )
+            if self.steps.get(PreprocessorSteps.BET, None) is None:
+                raise ValueError(
+                    "Brain extraction must be performed before defacing. "
+                    "Please run brain extraction first."
+                )
 
-            if self.defacing_mask_output_path:
-                logger.debug(f"Saving deface mask to {self.defacing_mask_output_path}")
-                self.save_mask(
-                    mask_path=atlas_mask_path,
-                    output_path=self.defacing_mask_output_path,
+            if defacer.force_atlas_registration and registrator is not None:
+                logger.info("Forcing atlas registration before defacing as requested.")
+                atlas_bet = defaced_dir_path / "atlas_bet.nii.gz"
+                atlas_bet_M = defaced_dir_path / "M_atlas_bet"
+
+                # resolve atlas image path
+                if isinstance(defacer.atlas_image_path, Atlas):
+                    atlas_folder = verify_or_download_atlases()
+                    atlas_image_path = atlas_folder / defacer.atlas_image_path.value
+                else:
+                    atlas_image_path = Path(defacer.atlas_image_path)
+
+                registrator.register(
+                    fixed_image_path=atlas_image_path,
+                    moving_image_path=self.steps[PreprocessorSteps.BET],
+                    transformed_image_path=atlas_bet,
+                    matrix_path=atlas_bet_M,
+                    log_file_path=defaced_dir_path / "atlas_bet.log",
+                )
+
+                deface_mask_atlas = defaced_dir_path / "deface_mask_atlas.nii.gz"
+                defacer.deface(
+                    input_image_path=atlas_bet,
+                    mask_image_path=deface_mask_atlas,
+                )
+
+                registrator.inverse_transform(
+                    fixed_image_path=self.steps[PreprocessorSteps.BET],
+                    moving_image_path=deface_mask_atlas,
+                    transformed_image_path=mask_path,
+                    matrix_path=atlas_bet_M,
+                    log_file_path=defaced_dir_path / "inverse_transform.log",
+                )
+            else:
+                defacer.deface(
+                    input_image_path=self.steps[PreprocessorSteps.BET],
+                    mask_image_path=mask_path,
                 )
 
-            return atlas_mask_path
+            return mask_path
         else:
             logger.warning(
                 "Defacing method not implemented yet. Skipping defacing for this modality."

brainles_preprocessing-0.6.1/brainles_preprocessing/preprocessor/__init__.py

@@ -0,0 +1,15 @@
+import warnings
+from .atlas_centric_preprocessor import AtlasCentricPreprocessor
+from .native_space_preprocessor import NativeSpacePreprocessor
+
+
+# Deprecation warning for Preprocessor alias, added to ensure backward compatibility.
+class Preprocessor(AtlasCentricPreprocessor):
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "Preprocessor has been renamed to AtlasCentricPreprocessor and is deprecated."
+            "The alias will be removed in future releases, please migrate to AtlasCentricPreprocessor.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)