brainles-preprocessing 0.4.0__tar.gz → 0.6.0__tar.gz

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: brainles_preprocessing
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -20,17 +20,16 @@ Provides-Extra: all
 Provides-Extra: itk-elastix
 Provides-Extra: picsl-greedy
 Requires-Dist: antspyx (>=0.5.4,<1.0.0)
-Requires-Dist: auxiliary (>=0.0.42)
-Requires-Dist: black (>=22.1.0,<23.0.0)
+Requires-Dist: auxiliary (>=0.3.1)
 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: nibabel (>=3.2.1)
 Requires-Dist: numpy (>=1.23.0,<2.0.0)
-Requires-Dist: path (>=16.10.0,<17.0.0)
 Requires-Dist: pathlib (>=1.0.1,<2.0.0)
 Requires-Dist: picsl_greedy (>=0.0.6,<0.0.7) ; extra == "all" or extra == "picsl-greedy"
 Requires-Dist: rich (>=13.6.0,<14.0.0)
 Requires-Dist: scipy (<1.14)
+Requires-Dist: simpleitk (>=2.2.1)
 Requires-Dist: tqdm (>=4.64.1,<5.0.0)
 Requires-Dist: ttictoc (>=0.5.6,<0.6.0)
 Requires-Dist: typer (>=0.15.0,<0.16.0)
@@ -49,9 +48,10 @@ Description-Content-Type: text/markdown
 
 `BrainLes preprocessing` is a comprehensive tool for preprocessing tasks in biomedical imaging, with a focus on (but not limited to) multi-modal brain MRI. It can be used to build modular preprocessing pipelines:
 
-This includes **normalization**, **co-registration**, **atlas registration** and **skulstripping / brain extraction**.
+This includes **normalization**, **co-registration**, **atlas registration**, **skullstripping / brain extraction**, **N4 Bias correction** and **defacing**.
+We provide means to transform images and segmentations in both directions between native and atlas space.
 
-BrainLes is written `backend-agnostic` meaning it allows to swap the registration, brain extraction tools and defacing tools.
+BrainLes is written modular and `backend-agnostic` meaning it allows to skip or swap registration, brain extraction, N4 bias correction and defacing tools.
 
 <!-- TODO include image here -->
 
@@ -125,7 +125,7 @@ moving_modalities = [
     )
 ]
 
-# instantiate and run the preprocessor using defaults for registration/ brain extraction/ defacing backends
+# instantiate and run the preprocessor using defaults for backends (registration, brain extraction, bias correction, defacing)
 preprocessor = Preprocessor(
     center_modality=center,
     moving_modalities=moving_modalities,
@@ -149,9 +149,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)
@@ -166,6 +182,9 @@ We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default)
 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.
 
+### N4 Bias correction
+We currently provide support for N4 Bias correction based on [SimpleITK](https://simpleitk.org/)
+
 ### Brain extraction
 We currently provide support for [HD-BET](https://github.com/MIC-DKFZ/HD-BET).
 

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/README.md

@@ -10,9 +10,10 @@
 
 `BrainLes preprocessing` is a comprehensive tool for preprocessing tasks in biomedical imaging, with a focus on (but not limited to) multi-modal brain MRI. It can be used to build modular preprocessing pipelines:
 
-This includes **normalization**, **co-registration**, **atlas registration** and **skulstripping / brain extraction**.
+This includes **normalization**, **co-registration**, **atlas registration**, **skullstripping / brain extraction**, **N4 Bias correction** and **defacing**.
+We provide means to transform images and segmentations in both directions between native and atlas space.
 
-BrainLes is written `backend-agnostic` meaning it allows to swap the registration, brain extraction tools and defacing tools.
+BrainLes is written modular and `backend-agnostic` meaning it allows to skip or swap registration, brain extraction, N4 bias correction and defacing tools.
 
 <!-- TODO include image here -->
 
@@ -86,7 +87,7 @@ moving_modalities = [
     )
 ]
 
-# instantiate and run the preprocessor using defaults for registration/ brain extraction/ defacing backends
+# instantiate and run the preprocessor using defaults for backends (registration, brain extraction, bias correction, defacing)
 preprocessor = Preprocessor(
     center_modality=center,
     moving_modalities=moving_modalities,
@@ -110,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)
@@ -127,6 +144,9 @@ We currently provide support for [ANTs](https://github.com/ANTsX/ANTs) (default)
 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.
 
+### N4 Bias correction
+We currently provide support for N4 Bias correction based on [SimpleITK](https://simpleitk.org/)
+
 ### Brain extraction
 We currently provide support for [HD-BET](https://github.com/MIC-DKFZ/HD-BET).
 

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/brainles_preprocessing/brain_extraction/brain_extractor.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Optional, Union
 from enum import Enum
 
-from auxiliary.nifti.io import read_nifti, write_nifti
+from auxiliary.io import read_image, write_image
 from brainles_hd_bet import run_hd_bet
 
 
@@ -55,8 +55,8 @@ class BrainExtractor:
 
         try:
             # Read data
-            input_data = read_nifti(str(input_image_path))
-            mask_data = read_nifti(str(mask_path))
+            input_data = read_image(str(input_image_path))
+            mask_data = read_image(str(mask_path))
         except FileNotFoundError as e:
             raise FileNotFoundError(f"File not found: {e.filename}") from e
         except Exception as e:
@@ -70,10 +70,10 @@ class BrainExtractor:
         masked_data = input_data * mask_data
 
         try:
-            write_nifti(
+            write_image(
                 input_array=masked_data,
-                output_nifti_path=str(bet_image_path),
-                reference_nifti_path=str(input_image_path),
+                output_path=str(bet_image_path),
+                reference_path=str(input_image_path),
                 create_parent_directory=True,
             )
         except Exception as e:

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/brainles_preprocessing/constants.py

@@ -6,8 +6,9 @@ class PreprocessorSteps(IntEnum):
     COREGISTERED = 1
     ATLAS_REGISTERED = 2
     ATLAS_CORRECTED = 3
-    BET = 4
-    DEFACED = 5
+    N4_BIAS_CORRECTED = 4
+    BET = 5
+    DEFACED = 6
 
 
 class Atlas(str, Enum):
@@ -23,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.4.0 → brainles_preprocessing-0.6.0}/brainles_preprocessing/defacing/defacer.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Union
 
-from auxiliary.nifti.io import read_nifti, write_nifti
+from auxiliary.io import read_image, write_image
 
 
 class Defacer(ABC):
@@ -52,8 +52,8 @@ class Defacer(ABC):
 
         try:
             # Read data
-            input_data = read_nifti(str(input_image_path))
-            mask_data = read_nifti(str(mask_path))
+            input_data = read_image(str(input_image_path))
+            mask_data = read_image(str(mask_path))
         except Exception as e:
             raise RuntimeError(
                 f"An error occurred while reading input files: {e}"
@@ -67,9 +67,9 @@ class Defacer(ABC):
         masked_data = input_data * mask_data
 
         # Save the defaced image
-        write_nifti(
+        write_image(
             input_array=masked_data,
-            output_nifti_path=str(defaced_image_path),
-            reference_nifti_path=str(input_image_path),
+            output_path=str(defaced_image_path),
+            reference_path=str(input_image_path),
             create_parent_directory=True,
         )

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/brainles_preprocessing/defacing/quickshear/quickshear.py

@@ -2,10 +2,11 @@ from pathlib import Path
 from typing import Union
 
 import nibabel as nib
+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 auxiliary.nifti.io import write_nifti
+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,
@@ -56,8 +66,11 @@ class QuickshearDefacer(Defacer):
 
         bet_img = nib.load(str(input_image_path))
         mask = run_quickshear(bet_img=bet_img, buffer=self.buffer)
-        write_nifti(
+
+        # transpose to match simpletik order
+        mask = mask.transpose(2, 1, 0)
+        write_image(
             input_array=mask,
-            output_nifti_path=str(mask_image_path),
-            reference_nifti_path=str(input_image_path),
+            output_path=str(mask_image_path),
+            reference_path=str(input_image_path),
         )

{brainles_preprocessing-0.4.0 → brainles_preprocessing-0.6.0}/brainles_preprocessing/modality.py

@@ -4,10 +4,10 @@ import warnings
 from pathlib import Path
 from typing import Dict, Optional, Union
 
-from auxiliary.nifti.io import read_nifti, write_nifti
+from auxiliary.io import read_image, write_image
 
 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,6 +15,7 @@ from brainles_preprocessing.registration import (  # TODO: this will throw warni
     NiftyRegRegistrator,
 )
 from brainles_preprocessing.registration.registrator import Registrator
+from brainles_preprocessing.utils.zenodo import verify_or_download_atlases
 
 logger = logging.getLogger(__name__)
 
@@ -34,6 +35,7 @@ class Modality:
         normalized_skull_output_path (str or Path, optional): Path to save the normalized modality data with skull. Requires a normalizer.
         normalized_defaced_output_path (str or Path, optional): Path to save the normalized defaced modality data. Requires a normalizer.
         atlas_correction (bool, optional): Indicates whether atlas correction should be performed.
+        n4_bias_correction (bool, optional): Indicates whether N4 bias correction should be performed.
 
     Attributes:
         modality_name (str): Name of the modality.
@@ -47,6 +49,7 @@ class Modality:
         normalized_defaced_output_path (str or Path, optional): Path to save the normalized defaced modality data. Requires a normalizer.
         bet (bool): Indicates whether brain extraction is enabled.
         atlas_correction (bool): Indicates whether atlas correction should be performed.
+        n4_bias_correction (bool): Indicates whether N4 bias correction should be performed.
         coregistration_transform_path (str or None): Path to the coregistration transformation matrix, will be set after coregistration.
 
     Example:
@@ -72,6 +75,7 @@ class Modality:
         normalized_skull_output_path: Optional[Union[str, Path]] = None,
         normalized_defaced_output_path: Optional[Union[str, Path]] = None,
         atlas_correction: bool = True,
+        n4_bias_correction: bool = False,
     ) -> None:
         # Basics
         self.modality_name = modality_name
@@ -79,6 +83,7 @@ class Modality:
         self.current = self.input_path
         self.normalizer = normalizer
         self.atlas_correction = atlas_correction
+        self.n4_bias_correction = n4_bias_correction
         self.transformation_paths: Dict[PreprocessorSteps, Path | None] = {}
 
         # Check that atleast one output is generated
@@ -195,12 +200,12 @@ class Modality:
 
         # Normalize the image
         if self.normalizer:
-            image = read_nifti(str(self.current))
+            image = read_image(str(self.current))
             normalized_image = self.normalizer.normalize(image=image)
-            write_nifti(
+            write_image(
                 input_array=normalized_image,
-                output_nifti_path=str(self.current),
-                reference_nifti_path=str(self.current),
+                output_path=str(self.current),
+                reference_path=str(self.current),
             )
         else:
             logger.info("No normalizer specified; skipping normalization.")
@@ -291,7 +296,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,
@@ -320,14 +325,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,
@@ -424,65 +442,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,
@@ -505,12 +498,12 @@ class Modality:
         if normalization:
             if self.normalizer is None:
                 raise ValueError("Normalizer is required for normalization.")
-            image = read_nifti(str(self.current))
+            image = read_image(str(self.current))
             normalized_image = self.normalizer.normalize(image=image)
-            write_nifti(
+            write_image(
                 input_array=normalized_image,
-                output_nifti_path=str(output_path),
-                reference_nifti_path=str(self.current),
+                output_path=str(output_path),
+                reference_path=str(self.current),
             )
         else:
             shutil.copyfile(
@@ -534,6 +527,7 @@ class CenterModality(Modality):
         normalized_skull_output_path (str or Path, optional): Path to save the normalized modality data with skull. Requires a normalizer.
         normalized_defaced_output_path (str or Path, optional): Path to save the normalized defaced modality data. Requires a normalizer.
         atlas_correction (bool, optional): Indicates whether atlas correction should be performed.
+        n4_bias_correction (bool, optional): Indicates whether N4 bias correction should be performed.
         bet_mask_output_path (str or Path, optional): Path to save the brain extraction mask.
         defacing_mask_output_path (str or Path, optional): Path to save the defacing mask.
 
@@ -549,6 +543,7 @@ class CenterModality(Modality):
         normalized_defaced_output_path (str or Path, optional): Path to save the normalized defaced modality data. Requires a normalizer.
         bet (bool): Indicates whether brain extraction is enabled.
         atlas_correction (bool): Indicates whether atlas correction should be performed.
+        n4_bias_correction (bool): Indicates whether N4 bias correction should be performed.
         bet_mask_output_path (Path, optional): Path to save the brain extraction mask.
         defacing_mask_output_path (Path, optional): Path to save the defacing mask.
 
@@ -575,6 +570,7 @@ class CenterModality(Modality):
         normalized_skull_output_path: Optional[Union[str, Path]] = None,
         normalized_defaced_output_path: Optional[Union[str, Path]] = None,
         atlas_correction: bool = True,
+        n4_bias_correction: bool = False,
         bet_mask_output_path: Optional[Union[str, Path]] = None,
         defacing_mask_output_path: Optional[Union[str, Path]] = None,
     ) -> None:
@@ -589,6 +585,7 @@ class CenterModality(Modality):
             normalized_skull_output_path=normalized_skull_output_path,
             normalized_defaced_output_path=normalized_defaced_output_path,
             atlas_correction=atlas_correction,
+            n4_bias_correction=n4_bias_correction,
         )
         # Only for CenterModality
         self.bet_mask_output_path = (
@@ -604,6 +601,7 @@ class CenterModality(Modality):
         bet_dir_path: Union[str, Path],
     ) -> Path:
         """
+
         Extract the brain region using the specified brain extractor.
 
         Args:
@@ -613,66 +611,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.0/brainles_preprocessing/n4_bias_correction/__init__.py

@@ -0,0 +1,2 @@
+from .n4_bias_corrector import N4BiasCorrector
+from .sitk.sitk_n4_bias_corrector import SitkN4BiasCorrector

brainles_preprocessing-0.6.0/brainles_preprocessing/n4_bias_correction/n4_bias_corrector.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class N4BiasCorrector(ABC):
+
+    @abstractmethod
+    def correct(
+        self,
+        input_img_path: Any,
+        output_img_path: Any,
+    ) -> None:
+        pass