BraTS 0.0.0.dev0__py3-none-any.whl

brats/preprocessing.py

@@ -0,0 +1,435 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional, Union
+
+from brats.constants import (
+    Algorithms,
+    MissingMRIAlgorithms,
+    PediatricAlgorithms,
+    AdultGliomaPreAndPostTreatmentAlgorithms,
+    MeningiomaRTAlgorithms,
+)
+
+try:
+    from brainles_preprocessing.modality import Modality, CenterModality
+    from brainles_preprocessing.preprocessor import (
+        AtlasCentricPreprocessor,
+        NativeSpacePreprocessor,
+    )
+    from brainles_preprocessing.constants import Atlas
+    from brainles_preprocessing.normalization import Normalizer
+except ImportError as e:
+    raise ImportError(
+        "The `brainles_preprocessing` extra is required for preprocessing tasks, please ensure you installed it via `pip install brats[preprocessing]`. Note that this is only supported for Python >= 3.10."
+    ) from e
+
+
+def _coreg_atlasreg_bet(
+    atlas: Atlas,
+    t1_input: Optional[Union[str, Path]] = None,
+    t1c_input: Optional[Union[str, Path]] = None,
+    t2_input: Optional[Union[str, Path]] = None,
+    flair_input: Optional[Union[str, Path]] = None,
+    t1_output: Optional[Union[str, Path]] = None,
+    t1c_output: Optional[Union[str, Path]] = None,
+    t2_output: Optional[Union[str, Path]] = None,
+    flair_output: Optional[Union[str, Path]] = None,
+    allow_missing: bool = False,
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+
+    # Build modality mapping in a cleaner way
+    modality_pairs = [
+        ("t1", t1_input, t1_output),
+        ("t1c", t1c_input, t1c_output),
+        ("t2", t2_input, t2_output),
+        ("flair", flair_input, flair_output),
+    ]
+
+    # Filter valid modalities (both input and output must be provided)
+    valid_modalities = {
+        name: {"input_path": inp, "raw_bet_output_path": out}
+        for name, inp, out in modality_pairs
+        if inp is not None and out is not None
+    }
+
+    # Validate minimum requirements
+    min_required = 3 if allow_missing else 4
+    if len(valid_modalities) < min_required:
+        missing_desc = "at least three" if allow_missing else "all four"
+        raise ValueError(
+            f"Need {missing_desc} modalities with valid input/output paths"
+        )
+
+    # Choose center modality (prefer t1c, fallback to t1)
+    center_name = "t1c" if "t1c" in valid_modalities else "t1"
+    center_data = valid_modalities[center_name]
+
+    center = CenterModality(
+        modality_name=center_name,
+        input_path=center_data["input_path"],
+        raw_bet_output_path=center_data["raw_bet_output_path"],
+        atlas_correction=False,
+        normalizer=normalizer,
+    )
+
+    # Create moving modalities (all except center)
+    moving_modalities = [
+        Modality(
+            modality_name=name,
+            input_path=data["input_path"],
+            raw_bet_output_path=data["raw_bet_output_path"],
+            atlas_correction=False,
+            normalizer=normalizer,
+        )
+        for name, data in valid_modalities.items()
+        if name != center_name
+    ]
+
+    preprocessor = AtlasCentricPreprocessor(
+        center_modality=center,
+        moving_modalities=moving_modalities,
+        atlas_image_path=atlas,
+    )
+
+    preprocessor.run()
+
+
+def _coreg_atlasreg_deface(
+    t1_input: Union[str, Path],
+    t1c_input: Union[str, Path],
+    t2_input: Union[str, Path],
+    flair_input: Union[str, Path],
+    t1_output: Union[str, Path],
+    t1c_output: Union[str, Path],
+    t2_output: Union[str, Path],
+    flair_output: Union[str, Path],
+    atlas: Atlas,
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+
+    center = CenterModality(
+        normalizer=normalizer,
+        modality_name="t1c",
+        input_path=t1c_input,
+        raw_defaced_output_path=t1c_output,
+        atlas_correction=False,
+    )
+
+    moving_modalities = [
+        Modality(
+            normalizer=normalizer,
+            modality_name="t1",
+            input_path=t1_input,
+            raw_defaced_output_path=t1_output,
+            atlas_correction=False,
+        ),
+        Modality(
+            normalizer=normalizer,
+            modality_name="t2",
+            input_path=t2_input,
+            raw_defaced_output_path=t2_output,
+            atlas_correction=False,
+        ),
+        Modality(
+            normalizer=normalizer,
+            modality_name="flair",
+            input_path=flair_input,
+            raw_defaced_output_path=flair_output,
+            atlas_correction=False,
+        ),
+    ]
+    preprocessor = AtlasCentricPreprocessor(
+        center_modality=center,
+        moving_modalities=moving_modalities,
+        atlas_image_path=atlas,
+    )
+
+    preprocessor.run()
+
+
+#######
+# Preprocessing functions for different BraTS challenges
+#######
+
+
+def preprocess_deface_only(
+    t1c_input: Union[str, Path],
+    t1c_output: Union[str, Path],
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    preprocessor = NativeSpacePreprocessor(
+        center_modality=CenterModality(
+            normalizer=normalizer,
+            modality_name="t1c",
+            input_path=t1c_input,
+            raw_defaced_output_path=t1c_output,
+            atlas_correction=False,
+        ),
+        moving_modalities=[],
+    )
+
+    preprocessor.run()
+
+
+def preprocess_coreg_sri24reg_bet(
+    t1_input: Union[str, Path],
+    t1c_input: Union[str, Path],
+    t2_input: Union[str, Path],
+    flair_input: Union[str, Path],
+    t1_output: Union[str, Path],
+    t1c_output: Union[str, Path],
+    t2_output: Union[str, Path],
+    flair_output: Union[str, Path],
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    """t1, t1c, t2, flair to SRI24 with co-registration and BET (most segmentation challenges and inpainting)
+
+    Args:
+        t1_input (Union[str, Path]): Path to the input T1 image.
+        t1c_input (Union[str, Path]): Path to the input T1c image
+        t2_input (Union[str, Path]): Path to the input T2 image.
+        flair_input (Union[str, Path]): Path to the input FLAIR image.
+        t1_output (Union[str, Path]): Path to the output preprocessed T1 image
+        t1c_output (Union[str, Path]): Path to the output preprocessed T1c image
+        t2_output (Union[str, Path]): Path to the output preprocessed T2 image
+        flair_output (Union[str, Path]): Path to the output preprocessed FLAIR image
+        normalizer (Optional[Normalizer]): Normalizer to apply during preprocessing
+
+    Returns:
+        None
+
+    """
+    _coreg_atlasreg_bet(
+        t1_input=t1_input,
+        t1c_input=t1c_input,
+        t2_input=t2_input,
+        flair_input=flair_input,
+        t1_output=t1_output,
+        t1c_output=t1c_output,
+        t2_output=t2_output,
+        flair_output=flair_output,
+        atlas=Atlas.BRATS_SRI24,
+        normalizer=normalizer,
+    )
+
+
+def preprocess_coreg_sri24reg_defacing(
+    t1_input: Union[str, Path],
+    t1c_input: Union[str, Path],
+    t2_input: Union[str, Path],
+    flair_input: Union[str, Path],
+    t1_output: Union[str, Path],
+    t1c_output: Union[str, Path],
+    t2_output: Union[str, Path],
+    flair_output: Union[str, Path],
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    """t1, t1c, t2, flair to SRI24 with co-registration and defacing (pediatric challenge)
+
+    Args:
+        t1_input (Union[str, Path]): Path to the input T1 image.
+        t1c_input (Union[str, Path]): Path to the input T1c image
+        t2_input (Union[str, Path]): Path to the input T2 image.
+        flair_input (Union[str, Path]): Path to the input FLAIR image.
+        t1_output (Union[str, Path]): Path to the output preprocessed T1 image
+        t1c_output (Union[str, Path]): Path to the output preprocessed T1c image
+        t2_output (Union[str, Path]): Path to the output preprocessed T2 image
+        flair_output (Union[str, Path]): Path to the output preprocessed FLAIR image
+        normalizer (Optional[Normalizer]): Normalizer to apply during preprocessing
+
+    Returns:
+        None
+
+    """
+    _coreg_atlasreg_deface(
+        t1_input=t1_input,
+        t1c_input=t1c_input,
+        t2_input=t2_input,
+        flair_input=flair_input,
+        t1_output=t1_output,
+        t1c_output=t1c_output,
+        t2_output=t2_output,
+        flair_output=flair_output,
+        atlas=Atlas.BRATS_SRI24,
+        normalizer=normalizer,
+    )
+
+
+def preprocess_coreg_mni152reg_bet(
+    t1_input: Union[str, Path],
+    t1c_input: Union[str, Path],
+    t2_input: Union[str, Path],
+    flair_input: Union[str, Path],
+    t1_output: Union[str, Path],
+    t1c_output: Union[str, Path],
+    t2_output: Union[str, Path],
+    flair_output: Union[str, Path],
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    """t1, t1c, t2, flair to MNI152 with co-registration and BET (GLI Post)
+
+    Args:
+        t1_input (Union[str, Path]): Path to the input T1 image.
+        t1c_input (Union[str, Path]): Path to the input T1c image
+        t2_input (Union[str, Path]): Path to the input T2 image.
+        flair_input (Union[str, Path]): Path to the input FLAIR image.
+        t1_output (Union[str, Path]): Path to the output preprocessed T1 image
+        t1c_output (Union[str, Path]): Path to the output preprocessed T1c image
+        t2_output (Union[str, Path]): Path to the output preprocessed T2 image
+        flair_output (Union[str, Path]): Path to the output preprocessed FLAIR image
+        normalizer (Optional[Normalizer]): Normalizer to apply during preprocessing
+
+    Returns:
+        None
+
+    """
+    _coreg_atlasreg_bet(
+        t1_input=t1_input,
+        t1c_input=t1c_input,
+        t2_input=t2_input,
+        flair_input=flair_input,
+        t1_output=t1_output,
+        t1c_output=t1c_output,
+        t2_output=t2_output,
+        flair_output=flair_output,
+        atlas=Atlas.BRATS_MNI152,
+        normalizer=normalizer,
+    )
+
+
+def preprocess_coreg_sri24reg_bet_allow_missing(
+    t1_input: Optional[Union[str, Path]] = None,
+    t1c_input: Optional[Union[str, Path]] = None,
+    t2_input: Optional[Union[str, Path]] = None,
+    flair_input: Optional[Union[str, Path]] = None,
+    t1_output: Optional[Union[str, Path]] = None,
+    t1c_output: Optional[Union[str, Path]] = None,
+    t2_output: Optional[Union[str, Path]] = None,
+    flair_output: Optional[Union[str, Path]] = None,
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    """t1, t1c, t2, flair to SRI24 with co-registration and BET while allowing one missing modality (missing MRI challenge)
+
+    Args:
+        t1_input (Optional[Union[str, Path]]): Path to the input T1 image.
+        t1c_input (Optional[Union[str, Path]]): Path to the input T1c image
+        t2_input (Optional[Union[str, Path]]): Path to the input T2 image.
+        flair_input (Optional[Union[str, Path]]): Path to the input FLAIR image.
+        t1_output (Optional[Union[str, Path]]): Path to the output preprocessed T1 image
+        t1c_output (Optional[Union[str, Path]]): Path to the output preprocessed T1c image
+        t2_output (Optional[Union[str, Path]]): Path to the output preprocessed T2 image
+        flair_output (Optional[Union[str, Path]]): Path to the output preprocessed FLAIR image
+        normalizer (Optional[Normalizer]): Normalizer to apply during preprocessing
+
+    Returns:
+        None
+
+    """
+    _coreg_atlasreg_bet(
+        t1_input=t1_input,
+        t1c_input=t1c_input,
+        t2_input=t2_input,
+        flair_input=flair_input,
+        t1_output=t1_output,
+        t1c_output=t1c_output,
+        t2_output=t2_output,
+        flair_output=flair_output,
+        atlas=Atlas.BRATS_SRI24,
+        allow_missing=True,
+        normalizer=normalizer,
+    )
+
+
+def preprocess_for_challenge(
+    challenge: Algorithms,
+    t1_input: Optional[Union[str, Path]] = None,
+    t1c_input: Optional[Union[str, Path]] = None,
+    t2_input: Optional[Union[str, Path]] = None,
+    flair_input: Optional[Union[str, Path]] = None,
+    t1_output: Optional[Union[str, Path]] = None,
+    t1c_output: Optional[Union[str, Path]] = None,
+    t2_output: Optional[Union[str, Path]] = None,
+    flair_output: Optional[Union[str, Path]] = None,
+    normalizer: Optional[Normalizer] = None,
+) -> None:
+    """Automatically select the correct preprocessing pipeline for a specific BraTS challenge.
+
+    Args:
+        challenge (Algorithms): The BraTS challenge algorithm enum
+        t1_input (Optional[Union[str, Path]]): Path to the input T1 image.
+        t1c_input (Optional[Union[str, Path]]): Path to the input T1c image
+        t2_input (Optional[Union[str, Path]]): Path to the input T2 image.
+        flair_input (Optional[Union[str, Path]]): Path to the input FLAIR image.
+        t1_output (Optional[Union[str, Path]]): Path to the output preprocessed T1 image
+        t1c_output (Optional[Union[str, Path]]): Path to the output preprocessed T1c image
+        t2_output (Optional[Union[str, Path]]): Path to the output preprocessed T2 image
+        flair_output (Optional[Union[str, Path]]): Path to the output preprocessed FLAIR image
+        normalizer (Optional[Normalizer]): Normalizer to apply during preprocessing
+
+    Raises:
+        ValueError: If required modalities are missing for the challenge
+    """
+    challenge_name = str(challenge)
+
+    # Helper to validate all modalities are present
+    def _require_all_modalities():
+        all_paths = [
+            t1_input,
+            t1c_input,
+            t2_input,
+            flair_input,
+            t1_output,
+            t1c_output,
+            t2_output,
+            flair_output,
+        ]
+        if any(path is None for path in all_paths):
+            raise ValueError(
+                f"All modalities required for {challenge_name} preprocessing"
+            )
+        return all_paths  # Type checker knows these are not None after the check
+
+    # Route to appropriate preprocessing function
+    if str(AdultGliomaPreAndPostTreatmentAlgorithms.__name__) in challenge_name:
+        paths = _require_all_modalities()
+        preprocess_coreg_mni152reg_bet(
+            *paths,  # type: ignore
+            normalizer=normalizer,
+        )
+
+    elif str(PediatricAlgorithms.__name__) in challenge_name:
+        paths = _require_all_modalities()
+        preprocess_coreg_sri24reg_defacing(
+            *paths,  # type: ignore
+            normalizer=normalizer,
+        )
+
+    elif str(MissingMRIAlgorithms.__name__) in challenge_name:
+        preprocess_coreg_sri24reg_bet_allow_missing(
+            t1_input,
+            t1c_input,
+            t2_input,
+            flair_input,
+            t1_output,
+            t1c_output,
+            t2_output,
+            flair_output,
+            normalizer=normalizer,
+        )
+    elif str(MeningiomaRTAlgorithms.__name__) in challenge_name:
+        if t1c_input is None or t1c_output is None:
+            raise ValueError(
+                f"T1c modality required for {challenge_name} preprocessing"
+            )
+        preprocess_deface_only(
+            t1c_input=t1c_input,
+            t1c_output=t1c_output,
+            normalizer=normalizer,
+        )
+    else:  # Most challenges use SRI24 with BET
+        paths = _require_all_modalities()
+        preprocess_coreg_sri24reg_bet(
+            *paths,  # type: ignore
+            normalizer=normalizer,
+        )

brats/utils/algorithm_config.py

@@ -0,0 +1,102 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+from brats.utils.exceptions import AlgorithmConfigException
+
+import yaml
+from dacite import DaciteError, from_dict
+
+
+@dataclass
+class MetaData:
+    """Dataclass for the meta data"""
+
+    authors: str
+    """The authors of the algorithm"""
+    paper: str
+    """If available, a url to the paper of the algorithm"""
+    challenge: str
+    """The challenge name the algorithm was submitted to"""
+    challenge_manuscript: str
+    """Arxiv url to the manuscript of the challenge"""
+    rank: str
+    """The rank of the algorithm in the challenge"""
+    year: int
+    """The year the algorithm was submitted"""
+    dataset_manuscript: Optional[str] = None
+    """If available, a url to the dataset manuscript of the algorithm. Optional since some algorithms do not have a dataset manuscript"""
+
+
+@dataclass
+class RunArgs:
+    """Dataclass for the run arguments"""
+
+    docker_image: str
+    """The Docker image containing the algorithm"""
+    input_name_schema: str
+    """The input name schema for the algorithm"""
+    parameters_file: bool = False
+    """Whether the algorithm requires a parameters file"""
+    requires_root: bool = False
+    """Whether the Docker container requires root access. This is !discouraged! but some submission do not work without it"""
+    shm_size: Optional[str] = "4gb"
+    """The required shared memory size for the Docker container"""
+    cpu_compatible: Optional[bool] = False
+    """Whether the algorithm is compatible with CPU"""
+    subject_modality_separator: str = "-"
+    """The separator between the subject ID and the modality, differs e.g. for BraTS24 Meningioma Challenge"""
+
+
+@dataclass
+class AdditionalFilesData:
+    """Dataclass for the additional files data"""
+
+    record_id: str
+    """The Zenodo record ID of the additional files"""
+    param_name: Optional[List[str]] = field(default_factory=lambda: ["weights"])
+    """The parameter(s) that specify additional file(s) in the algorithm execution, typically 'weights' but differs for some and can be multiple"""
+    param_path: Optional[List[str]] = None
+    """The path(s) to specific file(s) / folder(s) in the additional files folder. Not required since some algorithms accept the entire additional files folder"""
+
+
+@dataclass
+class AlgorithmData:
+    """Dataclass for the algorithm data"""
+
+    meta: MetaData
+    """The meta data of the algorithm"""
+    run_args: RunArgs
+    """The run arguments of the algorithm"""
+    additional_files: Optional[AdditionalFilesData]
+    """The additional files of the algorithm. Optional since some algorithms include them in the docker image"""
+
+
+@dataclass
+class AlgorithmList:
+    algorithms: Dict[str, AlgorithmData]
+
+
+def load_algorithms(file_path: Path) -> Dict[str, AlgorithmData]:
+    """Load the algorithms data from the specified yaml file
+
+    Params:
+        file_path (str): The path to the yaml file
+
+    Raises:
+        FileNotFoundError: If the file is not found
+
+    Returns:
+        Dict[str, AlgorithmData]: Dict of algorithm @AlgorithmKeys:@AlgorithmData  pairs
+    """
+    try:
+        with open(file_path, "r") as file:
+            data = yaml.safe_load(file)
+    except FileNotFoundError:
+        raise FileNotFoundError("Algorithm meta data file not found")
+
+    try:
+        # Convert the dictionary to the dataclass
+        algorithms = from_dict(data_class=AlgorithmList, data=data).algorithms
+    except DaciteError as e:
+        raise AlgorithmConfigException(f"Error loading algorithm data: {e}")
+    return algorithms

brats/utils/data_handling.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, Optional, Tuple
+
+import nibabel as nib
+from loguru import logger
+
+
+def remove_tmp_folder(folder: Path):
+    """Remove a temporary folder and log a warning if it fails.
+
+    Args:
+        folder (Path): Path to the folder to be removed
+    """
+    try:
+        shutil.rmtree(folder)
+    except PermissionError as e:
+        logger.warning(
+            f"Failed to remove temporary folder {folder}. This is most likely caused by bad permission management of the docker container. \nError: {e}"
+        )
+    except FileNotFoundError as e:
+        logger.warning(f"Failed to delete folder {folder}. {e}")
+
+
+def add_log_file_handler(log_file: Path | str) -> int:
+    """
+    Add a log file handler to the logger.
+
+    Args:
+        log_file (Path | str): Path to the log file
+
+    Returns:
+        int: The logger id
+    """
+    log_file = Path(log_file)
+    logger_id = logger.add(log_file, level="DEBUG", catch=True)
+    logger.info(
+        f"Logging console logs and further debug information to: {log_file.absolute()}"
+    )
+
+    return logger_id
+
+
+@contextmanager
+def InferenceSetup(
+    log_file: Optional[Path | str] = None,
+) -> Generator[Tuple[Path, Path], None, None]:
+    """
+    Context manager for setting up the inference process. Creates temporary data and output folders and adds a log file handler if requested.
+
+    Yields:
+        (data folder, output folder) (Tuple[Path, Path]): Two temporary folders (data folder, output folder)
+    """
+    if log_file is not None:
+        logger_id = add_log_file_handler(log_file)
+
+    tmp_data_folder = Path(tempfile.mkdtemp(prefix="data_"))
+    tmp_output_folder = Path(tempfile.mkdtemp(prefix="output_"))
+
+    try:
+        yield tmp_data_folder, tmp_output_folder
+    finally:
+        remove_tmp_folder(tmp_data_folder)
+        remove_tmp_folder(tmp_output_folder)
+
+        if log_file is not None:
+            logger.remove(logger_id)
+
+
+def input_sanity_check(
+    t1n: Optional[Path | str] = None,
+    t1c: Optional[Path | str] = None,
+    t2f: Optional[Path | str] = None,
+    t2w: Optional[Path | str] = None,
+    mask: Optional[Path | str] = None,
+):
+    """
+    Check if input images have the default shape (240, 240, 155) and log a warning if not.
+    Supports different input combinations for segmentation and inpainting tasks.
+
+    Args:
+        t1n (Path | str): T1n image path (required for segmentation and inpainting)
+        t1c (Path | str, optional): T1c image path (required for segmentation)
+        t2f (Path | str, optional): T2f image path (required for segmentation)
+        t2w (Path | str, optional): T2w image path (required for segmentation)
+        mask (Path | str, optional): Mask image path (required for inpainting)
+    """
+
+    # Filter out None values to only include provided images
+    images = {
+        "t1n": t1n,
+        "t1c": t1c,
+        "t2f": t2f,
+        "t2w": t2w,
+        "mask": mask,
+    }
+
+    # Load and check shapes
+    shapes = {
+        label: nib.load(img).shape for label, img in images.items() if img is not None
+    }
+
+    assert shapes, "No input images provided. At least one image is required."
+
+    if any(shape != (240, 240, 155) for shape in shapes.values()):
+        logger.warning(
+            "Input images do not have the default shape (240, 240, 155). This might cause issues with some algorithms and could lead to errors."
+        )
+        logger.warning(f"Image shapes: {shapes}")
+        logger.warning(
+            "If your data is not preprocessed yet, consider using our preprocessing package: https://github.com/BrainLesion/preprocessing"
+        )

brats/utils/exceptions.py

@@ -0,0 +1,25 @@
+from dacite import DaciteError
+
+
+class AlgorithmNotCPUCompatibleException(Exception):
+    """Exception raised when an CPU-incompatible algorithm tries to run on CPU."""
+
+    pass
+
+
+class BraTSContainerException(Exception):
+    """Exception raised when an algorithm container fails"""
+
+    pass
+
+
+class AlgorithmConfigException(DaciteError):
+    """Exception raised when the algorithm config file has issues."""
+
+    pass
+
+
+class ZenodoException(Exception):
+    """Exception raised when Zenodo is unreachable or returns an error."""
+
+    pass