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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: brainles_preprocessing
-Version: 0.3.6
+Version: 0.5.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
@@ -19,17 +19,18 @@ Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: all
 Provides-Extra: itk-elastix
 Provides-Extra: picsl-greedy
-Requires-Dist: antspyx (>=0.4.2,<0.5.0)
-Requires-Dist: auxiliary (>=0.0.42)
+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)
+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)
@@ -48,9 +49,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 -->
 
@@ -124,7 +126,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,
@@ -165,6 +167,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.3.6 → brainles_preprocessing-0.5.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,
@@ -127,6 +128,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.3.6 → brainles_preprocessing-0.5.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.3.6 → brainles_preprocessing-0.5.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):

{brainles_preprocessing-0.3.6 → brainles_preprocessing-0.5.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.3.6 → brainles_preprocessing-0.5.0}/brainles_preprocessing/defacing/quickshear/quickshear.py

@@ -2,10 +2,10 @@ 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
 
 
 class QuickshearDefacer(Defacer):
@@ -56,8 +56,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.3.6 → brainles_preprocessing-0.5.0}/brainles_preprocessing/modality.py

@@ -2,13 +2,18 @@ import logging
 import shutil
 import warnings
 from pathlib import Path
-from typing import Optional, Union
+from typing import Dict, Optional, Union
+
+from auxiliary.io import read_image, write_image
 
-from auxiliary.nifti.io import read_nifti, write_nifti
 from brainles_preprocessing.brain_extraction.brain_extractor import BrainExtractor
 from brainles_preprocessing.constants import 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
+    ANTsRegistrator,
+    NiftyRegRegistrator,
+)
 from brainles_preprocessing.registration.registrator import Registrator
 
 logger = logging.getLogger(__name__)
@@ -29,6 +34,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.
@@ -42,6 +48,8 @@ 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:
         >>> t1_modality = Modality(
@@ -66,6 +74,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
@@ -73,6 +82,8 @@ 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
         if not any(
@@ -128,6 +139,7 @@ class Modality:
             self.normalized_defaced_output_path = None
 
         self.steps = {k: None for k in PreprocessorSteps}
+        self.steps[PreprocessorSteps.INPUT] = self.input_path
 
     @property
     def bet(self) -> bool:
@@ -187,16 +199,36 @@ 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.")
 
+    def _find_transformation_matrix(
+        self, transform_incomplete_path: Path
+    ) -> Optional[Path]:
+        possible_Files = list(
+            transform_incomplete_path.parent.glob(f"{transform_incomplete_path.stem}.*")
+        )
+        if len(possible_Files) == 0:
+            logger.warning(
+                f"No transformation matrix found for {transform_incomplete_path}. "
+                "Returning None."
+            )
+            return None
+        elif len(possible_Files) > 1:
+            # TODO: Handle this case more gracefully, e.g., try to find proper extension based on the registrator
+            logger.warning(
+                f"Multiple transformation matrices found for {transform_incomplete_path}. "
+                "Returning the first one."
+            )
+        return possible_Files[0]
+
     def register(
         self,
         registrator: Registrator,
@@ -213,6 +245,7 @@ class Modality:
             fixed_image_path (str or Path): Path to the fixed image.
             registration_dir (str or Path): Directory to store registration results.
             moving_image_name (str): Name of the moving image.
+            step (PreprocessorSteps): The current preprocessing step.
 
         Returns:
             Path: Path to the registration matrix.
@@ -224,7 +257,7 @@ class Modality:
         registered_log = registration_dir / f"{moving_image_name}.log"
 
         # Note, add file ending depending on registration backend!
-        registered_matrix = registration_dir / f"{moving_image_name}"
+        registered_matrix = registration_dir / f"M_{moving_image_name}"
 
         registrator.register(
             fixed_image_path=fixed_image_path,
@@ -235,6 +268,11 @@ class Modality:
         )
         self.current = registered
         self.steps[step] = registered
+
+        self.transformation_paths[step] = self._find_transformation_matrix(
+            transform_incomplete_path=registered_matrix
+        )
+
         return registered_matrix
 
     def apply_bet_mask(
@@ -320,7 +358,7 @@ class Modality:
             registration_dir_path (str or Path): Directory to store transformation results.
             moving_image_name (str): Name of the moving image.
             transformation_matrix_path (str or Path): Path to the transformation matrix.
-
+            step (PreprocessorSteps): The current preprocessing step.
         Returns:
             None
         """
@@ -331,15 +369,42 @@ class Modality:
         transformed = registration_dir_path / f"{moving_image_name}.nii.gz"
         transformed_log = registration_dir_path / f"{moving_image_name}.log"
 
-        registrator.transform(
-            fixed_image_path=fixed_image_path,
-            moving_image_path=self.current,
-            transformed_image_path=transformed,
-            matrix_path=transformation_matrix_path,
-            log_file_path=transformed_log,
-        )
+        if (
+            isinstance(registrator, (ANTsRegistrator, NiftyRegRegistrator))
+            and step == PreprocessorSteps.ATLAS_REGISTERED
+        ):
+            # we test uniting transforms for these registrators
+            assert (
+                self.transformation_paths.get(PreprocessorSteps.COREGISTERED, None)
+                is not None
+            ), "Coregistration must be performed before applying atlas registration."
+
+            registrator.transform(
+                fixed_image_path=fixed_image_path,
+                moving_image_path=self.steps[PreprocessorSteps.INPUT],
+                transformed_image_path=transformed,
+                matrix_path=[
+                    self.transformation_paths[
+                        PreprocessorSteps.COREGISTERED
+                    ],  # coregistration matrix
+                    transformation_matrix_path,  # atlas registration matrix
+                ],
+                log_file_path=transformed_log,
+            )
+        else:
+            registrator.transform(
+                fixed_image_path=fixed_image_path,
+                moving_image_path=self.current,
+                transformed_image_path=transformed,
+                matrix_path=transformation_matrix_path,
+                log_file_path=transformed_log,
+            )
+
         self.current = transformed
         self.steps[step] = transformed
+        self.transformation_paths[step] = self._find_transformation_matrix(
+            transform_incomplete_path=transformation_matrix_path
+        )
 
     def extract_brain_region(
         self,
@@ -444,12 +509,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(
@@ -473,6 +538,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.
 
@@ -488,6 +554,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.
 
@@ -514,6 +581,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:
@@ -528,6 +596,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 = (

brainles_preprocessing-0.5.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.5.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

brainles_preprocessing-0.5.0/brainles_preprocessing/n4_bias_correction/sitk/sitk_n4_bias_corrector.py

@@ -0,0 +1,82 @@
+from pathlib import Path
+from typing import Callable, Optional, Union
+
+import SimpleITK as sitk
+from auxiliary.io import write_image
+
+from brainles_preprocessing.n4_bias_correction.n4_bias_corrector import N4BiasCorrector
+
+
+class SitkN4BiasCorrector(N4BiasCorrector):
+
+    def __init__(
+        self,
+        mask_func: Optional[Callable[[sitk.Image], sitk.Image]] = None,
+        n_max_iterations: Optional[int] = None,
+        n_fitting_levels: int = 3,
+    ) -> None:
+        """
+        N4 Bias Corrector using SimpleITK.
+
+        Args:
+            mask_func (Optional[Callable[[sitk.Image], sitk.Image]], optional):
+                Function that generates a mask from an image.
+                Defaults to: `lambda img_itk: sitk.OtsuThreshold(img_itk, 0, 1, 200)`.
+            n_max_iterations (Optional[int], optional):
+                Maximum number of iterations for bias field correction.
+            n_fitting_levels (int, optional):
+                Number of fitting levels. Default is 3.
+        """
+
+        if mask_func is None:
+            mask_func = lambda img_itk: sitk.OtsuThreshold(img_itk, 0, 1, 200)
+        self.mask_func = mask_func
+        self.n_max_iterations = n_max_iterations
+        self.n_fitting_levels = n_fitting_levels
+
+    def compute_mask(self, img_itk: sitk.Image) -> sitk.Image:
+        """
+        Compute the mask for the input image using the provided mask function.
+
+        Args:
+            img_itk (SimpleITK.Image): The input image in SimpleITK format.
+
+        Returns:
+            SimpleITK.Image: The computed mask.
+        """
+
+        return self.mask_func(img_itk)
+
+    def correct(
+        self,
+        input_img_path: Union[str, Path],
+        output_img_path: Union[str, Path],
+    ) -> None:
+        """
+        Correct the bias field of the input image using SimpleITK.
+
+        Args:
+            input_img_path (Union[str, Path]): Path to the input image.
+            output_img_path (Union[str, Path]): Path where the corrected image will be saved.
+
+        Returns:
+            None
+        """
+        img_itk = sitk.ReadImage(str(input_img_path))
+
+        mask_itk = self.compute_mask(img_itk)
+
+        corrector = sitk.N4BiasFieldCorrectionImageFilter()
+        if self.n_max_iterations is not None:
+            corrector.SetMaximumNumberOfIterations(
+                [self.n_max_iterations] * self.n_fitting_levels
+            )
+
+        corrected_img = corrector.Execute(img_itk, mask_itk)
+        corrected_img = sitk.GetArrayFromImage(corrected_img)
+
+        write_image(
+            input_array=corrected_img,
+            output_path=str(output_img_path),
+            reference_path=str(input_img_path),
+        )