BraTS 0.0.1__tar.gz

brats-0.0.1/BraTS.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.1
+Name: BraTS
+Version: 0.0.1
+Summary: A small example package
+Author-email: Example Author <author@example.com>
+Project-URL: Homepage, https://github.com/pypa/sampleproject
+Project-URL: Issues, https://github.com/pypa/sampleproject/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+[![PyPI version brats-algorithms](https://badge.fury.io/py/brats-algorithms.svg)](https://pypi.python.org/pypi/brats-algorithms/)
+[![Documentation Status](https://readthedocs.org/projects/brats-algorithms/badge/?version=latest)](http://brats-algorithms.readthedocs.io/?badge=latest)
+[![tests](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml/badge.svg)](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml)
+
+# brats-algorithms
+
+Top performing algorithms from the Brain Tumor Segmentation (BraTS) challenges, providing state-of-the-art models for brain lesion segmentation.
+
+## Features
+
+- Access to top-performing algorithms from recent BraTS challenges.
+- Easy-to-use inference API.
+- Extensive documentation and examples. (TODO!)
+
+## Installation
+
+With a Python 3.10+ environment, you can install `PACKAGE_NAME` directly from [PyPI](https://pypi.org/project/PACKAGE_NAME/):
+
+```sh
+pip install PACKAGE_NAME
+```
+
+### Docker and NVIDIA Container Toolkit Setup
+
+To run `PACKAGE_NAME` in a Docker container with GPU support (required for most algorithms), ensure you have Docker and NVIDIA Docker installed. Instructions:
+- **Docker**: Installation instructions on the official [website](https://docs.docker.com/get-docker/)
+- **NVIDIA Container Toolkit**: Installation instructions on the official [GitHub page](https://github.com/NVIDIA/nvidia-container-toolkit) 
+
+## Use Cases and Tutorials
+
+*TODO*
+
+## Contributing
+
+We welcome contributions from the community, including bug reports, feature requests, and code contributions. For more information on how to contribute, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
+## License
+*TODO*

brats-0.0.1/BraTS.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+BraTS.egg-info/PKG-INFO
+BraTS.egg-info/SOURCES.txt
+BraTS.egg-info/dependency_links.txt
+BraTS.egg-info/top_level.txt
+brats/__init__.py
+brats/algorithm_config.py
+brats/algorithms.py
+brats/constants.py
+brats/docker.py
+brats/exceptions.py
+brats/utils.py
+brats/weights.py
+tests/test_algorithm_config.py
+tests/test_utils.py

brats-0.0.1/BraTS.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

brats-0.0.1/BraTS.egg-info/top_level.txt

@@ -0,0 +1 @@
+brats

brats-0.0.1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.1
+Name: BraTS
+Version: 0.0.1
+Summary: A small example package
+Author-email: Example Author <author@example.com>
+Project-URL: Homepage, https://github.com/pypa/sampleproject
+Project-URL: Issues, https://github.com/pypa/sampleproject/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+[![PyPI version brats-algorithms](https://badge.fury.io/py/brats-algorithms.svg)](https://pypi.python.org/pypi/brats-algorithms/)
+[![Documentation Status](https://readthedocs.org/projects/brats-algorithms/badge/?version=latest)](http://brats-algorithms.readthedocs.io/?badge=latest)
+[![tests](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml/badge.svg)](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml)
+
+# brats-algorithms
+
+Top performing algorithms from the Brain Tumor Segmentation (BraTS) challenges, providing state-of-the-art models for brain lesion segmentation.
+
+## Features
+
+- Access to top-performing algorithms from recent BraTS challenges.
+- Easy-to-use inference API.
+- Extensive documentation and examples. (TODO!)
+
+## Installation
+
+With a Python 3.10+ environment, you can install `PACKAGE_NAME` directly from [PyPI](https://pypi.org/project/PACKAGE_NAME/):
+
+```sh
+pip install PACKAGE_NAME
+```
+
+### Docker and NVIDIA Container Toolkit Setup
+
+To run `PACKAGE_NAME` in a Docker container with GPU support (required for most algorithms), ensure you have Docker and NVIDIA Docker installed. Instructions:
+- **Docker**: Installation instructions on the official [website](https://docs.docker.com/get-docker/)
+- **NVIDIA Container Toolkit**: Installation instructions on the official [GitHub page](https://github.com/NVIDIA/nvidia-container-toolkit) 
+
+## Use Cases and Tutorials
+
+*TODO*
+
+## Contributing
+
+We welcome contributions from the community, including bug reports, feature requests, and code contributions. For more information on how to contribute, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
+## License
+*TODO*

brats-0.0.1/README.md

@@ -0,0 +1,38 @@
+[![PyPI version brats-algorithms](https://badge.fury.io/py/brats-algorithms.svg)](https://pypi.python.org/pypi/brats-algorithms/)
+[![Documentation Status](https://readthedocs.org/projects/brats-algorithms/badge/?version=latest)](http://brats-algorithms.readthedocs.io/?badge=latest)
+[![tests](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml/badge.svg)](https://github.com/BrainLesion/brats-algorithms/actions/workflows/tests.yml)
+
+# brats-algorithms
+
+Top performing algorithms from the Brain Tumor Segmentation (BraTS) challenges, providing state-of-the-art models for brain lesion segmentation.
+
+## Features
+
+- Access to top-performing algorithms from recent BraTS challenges.
+- Easy-to-use inference API.
+- Extensive documentation and examples. (TODO!)
+
+## Installation
+
+With a Python 3.10+ environment, you can install `PACKAGE_NAME` directly from [PyPI](https://pypi.org/project/PACKAGE_NAME/):
+
+```sh
+pip install PACKAGE_NAME
+```
+
+### Docker and NVIDIA Container Toolkit Setup
+
+To run `PACKAGE_NAME` in a Docker container with GPU support (required for most algorithms), ensure you have Docker and NVIDIA Docker installed. Instructions:
+- **Docker**: Installation instructions on the official [website](https://docs.docker.com/get-docker/)
+- **NVIDIA Container Toolkit**: Installation instructions on the official [GitHub page](https://github.com/NVIDIA/nvidia-container-toolkit) 
+
+## Use Cases and Tutorials
+
+*TODO*
+
+## Contributing
+
+We welcome contributions from the community, including bug reports, feature requests, and code contributions. For more information on how to contribute, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
+## License
+*TODO*

brats-0.0.1/brats/__init__.py

@@ -0,0 +1,5 @@
+from brats.algorithms import (
+    AdultGliomaSegmenter,
+    MeningiomaSegmenter,
+    PediatricSegmenter,
+)

brats-0.0.1/brats/algorithm_config.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional
+from brats.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 the algorithm was submitted to"""
+
+
+@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
+    """Whether the algorithm requires a parameters file"""
+    requires_root: bool
+    """Whether the Docker container requires root access. This is !discouraged! but some submission do not work without it"""
+    shm_size: Optional[str] = "2gb"
+    """The required shared memory size for the Docker container"""
+    cpu_compatible: Optional[bool] = False
+    """Whether the algorithm is compatible with CPU"""
+
+
+@dataclass
+class WeightsData:
+    """Dataclass for the weights data"""
+
+    record_id: str
+    """The Zenodo record ID of the weights"""
+    param_name: Optional[str] = "weights"
+    """The parameter that specifies the weights folder in the algorithm execution, typically 'weights' but differs for some"""
+
+
+@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"""
+    weights: Optional[WeightsData]
+    """The weights data of the algorithm. Optional since some algorithms include weights 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-0.0.1/brats/algorithms.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from loguru import logger
+
+from brats.algorithm_config import load_algorithms
+from brats.constants import (
+    ADULT_GLIOMA_SEGMENTATION_ALGORITHMS,
+    MENINGIOMA_SEGMENTATION_ALGORITHMS,
+    PEDIATRIC_SEGMENTATION_ALGORITHMS,
+    AdultGliomaAlgorithms,
+    Algorithms,
+    MeningiomaAlgorithms,
+    PediatricAlgorithms,
+)
+from brats.docker import run_docker
+from brats.utils import (
+    standardize_subject_inputs,
+    standardize_subjects_inputs_list,
+)
+
+
+class BraTSAlgorithm:
+    def __init__(
+        self,
+        algorithm: Algorithms,
+        algorithms_file_path: Path,
+        cuda_devices: Optional[str] = "0",
+        force_cpu: bool = False,
+    ):
+        # inference device setup
+        self.force_cpu = force_cpu
+        self.cuda_devices = cuda_devices
+
+        self.algorithm_list = load_algorithms(file_path=algorithms_file_path)
+        # save algorithm identifier for logging etc.
+        self.algorithm_key = algorithm.value
+        # data for selected algorithm
+        self.algorithm = self.algorithm_list[algorithm.value]
+
+        logger.info(
+            f"Instantiated {self.__class__.__name__} with algorithm: {self.algorithm_key} by {self.algorithm.meta.authors}"
+        )
+
+    def _log_algorithm_info(self):
+        """Log information about the selected algorithm."""
+        logger.opt(colors=True).info(
+            f"Running algorithm: <light-green>{self.algorithm.meta.challenge}</>"
+        )
+        logger.opt(colors=True).info(
+            f"<blue>(Docker image)</>: {self.algorithm.run_args.docker_image}"
+        )
+        logger.opt(colors=True).info(
+            f"<blue>(Paper)</> Consider citing the corresponding paper: {self.algorithm.meta.paper} by {self.algorithm.meta.authors}"
+        )
+
+    def infer_single(
+        self,
+        t1c: Path | str,
+        t1n: Path | str,
+        t2f: Path | str,
+        t2w: Path | str,
+        output_file: Path | str,
+        log_file: Optional[Path | str] = None,
+    ):
+        """Perform inference on a single subject with the provided images and save the result to the output file.
+
+        Args:
+            t1c (Path | str): Path to the T1c image
+            t1n (Path | str): Path to the T1n image
+            t2f (Path | str): Path to the T2f image
+            t2w (Path | str): Path to the T2w image
+            output_file (Path | str): Path to save the segmentation
+            log_file (Path | str, optional): Save logs to this file
+        """
+        # setup temp input folder with the provided images
+        temp_data_folder = Path(tempfile.mkdtemp())
+        temp_output_folder = Path(tempfile.mkdtemp())
+        if log_file is not None:
+            inference_log_file = logger.add(log_file, level="INFO")
+            logger.info(f"Logging to: {log_file}")
+
+        try:
+            logger.info(f"Performing single inference ")
+
+            # the id here is arbitrary
+            subject_id = self.algorithm.run_args.input_name_schema.format(id=0)
+
+            standardize_subject_inputs(
+                data_folder=temp_data_folder,
+                subject_id=subject_id,
+                t1c=t1c,
+                t1n=t1n,
+                t2f=t2f,
+                t2w=t2w,
+            )
+
+            self._log_algorithm_info()
+            run_docker(
+                algorithm=self.algorithm,
+                data_path=temp_data_folder,
+                output_path=temp_output_folder,
+                cuda_devices=self.cuda_devices,
+                force_cpu=self.force_cpu,
+            )
+            # rename output
+            segmentation = Path(temp_output_folder) / f"{subject_id}.nii.gz"
+
+            # ensure path exists and rename output to the desired path
+            output_file = Path(output_file).absolute()
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(segmentation, output_file)
+            logger.info(f"Saved segmentation to: {output_file.absolute()}")
+
+        finally:
+            shutil.rmtree(temp_data_folder)
+            shutil.rmtree(temp_output_folder)
+            if log_file is not None:
+                logger.remove(inference_log_file)
+
+    def infer_batch(
+        self,
+        data_folder: Path | str,
+        output_folder: Path | str,
+        log_file: Optional[Path | str] = None,
+    ):
+        """Perform segmentation on a batch of subjects with the provided images and save the results to the output folder. \n
+        Requires the following structure:\n
+        data_folder\n
+        ┣ A\n
+        ┃ ┣ A-t1c.nii.gz\n
+        ┃ ┣ A-t1n.nii.gz\n
+        ┃ ┣ A-t2f.nii.gz\n
+        ┃ ┗ A-t2w.nii.gz\n
+        ┣ B\n
+        ┃ ┣ B-t1c.nii.gz\n
+        ┃ ┣ ...\n
+
+
+        Args:
+            data_folder (Path | str): Folder containing the subjects with required structure
+            output_folder (Path | str): Output folder to save the segmentations
+            log_file (Path | str, optional): Save logs to this file
+        """
+
+        data_folder = Path(data_folder)
+        output_folder = Path(output_folder)
+
+        temp_data_folder = Path(tempfile.mkdtemp())
+        temp_output_folder = Path(tempfile.mkdtemp())
+        if log_file:
+            inference_log_file = logger.add(log_file, level="INFO", catch=True)
+            logger.info(f"Logging to: {log_file.absolute()}")
+        try:
+            self._log_algorithm_info()
+            # find subjects
+            subjects = [f for f in data_folder.iterdir() if f.is_dir()]
+            logger.info(
+                f"Found {len(subjects)} subjects: {', '.join([s.name for s in subjects][:5])} {' ...' if len(subjects) > 5 else '' }"
+            )
+            # map to brats names
+            internal_external_name_map = standardize_subjects_inputs_list(
+                subjects=subjects,
+                temp_data_folder=temp_data_folder,
+                input_name_schema=self.algorithm.run_args.input_name_schema,
+            )
+            logger.info(f"Standardized input names to match algorithm requirements.")
+
+            # run inference in container
+            run_docker(
+                algorithm=self.algorithm,
+                data_path=temp_data_folder,
+                output_path=temp_output_folder,
+                cuda_devices=self.cuda_devices,
+                force_cpu=self.force_cpu,
+            )
+
+            # move outputs and change name back to initially provided one
+            for internal_name, external_name in internal_external_name_map.items():
+                segmentation = Path(temp_output_folder) / f"{internal_name}.nii.gz"
+                output_file = output_folder / f"{external_name}.nii.gz"
+                shutil.move(segmentation, output_file)
+
+            logger.info(f"Saved results to: {output_folder.absolute()}")
+        finally:
+            shutil.rmtree(temp_data_folder)
+            shutil.rmtree(temp_output_folder)
+            if log_file:
+                logger.remove(inference_log_file)
+
+
+class AdultGliomaSegmenter(BraTSAlgorithm):
+
+    def __init__(
+        self,
+        algorithm: AdultGliomaAlgorithms = AdultGliomaAlgorithms.BraTS23_1,
+        cuda_devices: Optional[str] = "0",
+        force_cpu: bool = False,
+    ):
+        """Provides algorithms to perform tumor segmentation on adult glioma MRI data.
+
+        Args:
+            algorithm (AdultGliomaAlgorithms, optional): Select an algorithm. Defaults to AdultGliomaAlgorithms.BraTS23_1.
+            cuda_devices (Optional[str], optional): Which cuda devices to use. Defaults to "0".
+            force_cpu (bool, optional): Execution will default to GPU, this flag allows forced CPU execution if the algorithm is compatible. Defaults to False.
+        """
+        super().__init__(
+            algorithm=algorithm,
+            algorithms_file_path=ADULT_GLIOMA_SEGMENTATION_ALGORITHMS,
+            cuda_devices=cuda_devices,
+            force_cpu=force_cpu,
+        )
+
+
+class MeningiomaSegmenter(BraTSAlgorithm):
+
+    def __init__(
+        self,
+        algorithm: MeningiomaAlgorithms = MeningiomaAlgorithms.BraTS23_1,
+        cuda_devices: Optional[str] = "0",
+        force_cpu: bool = False,
+    ):
+        """Provides algorithms to perform tumor segmentation on adult meningioma MRI data.
+
+        Args:
+            algorithm (AdultGliomaAlgorithms, optional): Select an algorithm. Defaults to MeningiomaAlgorithms.BraTS23_1.
+            cuda_devices (Optional[str], optional): Which cuda devices to use. Defaults to "0".
+            force_cpu (bool, optional): Execution will default to GPU, this flag allows forced CPU execution if the algorithm is compatible. Defaults to False.
+        """
+        super().__init__(
+            algorithm=algorithm,
+            algorithms_file_path=MENINGIOMA_SEGMENTATION_ALGORITHMS,
+            cuda_devices=cuda_devices,
+            force_cpu=force_cpu,
+        )
+
+
+class PediatricSegmenter(BraTSAlgorithm):
+
+    def __init__(
+        self,
+        algorithm: PediatricAlgorithms = PediatricAlgorithms.BraTS23_1,
+        cuda_devices: Optional[str] = "0",
+        force_cpu: bool = False,
+    ):
+        """Provides algorithms to perform tumor segmentation on pediatric MRI data
+
+        Args:
+            algorithm (AdultGliomaAlgorithms, optional): Select an algorithm. Defaults to PediatricAlgorithms.BraTS23_1.
+            cuda_devices (Optional[str], optional): Which cuda devices to use. Defaults to "0".
+            force_cpu (bool, optional): Execution will default to GPU, this flag allows forced CPU execution if the algorithm is compatible. Defaults to False.
+        """
+        super().__init__(
+            algorithm=algorithm,
+            algorithms_file_path=PEDIATRIC_SEGMENTATION_ALGORITHMS,
+            cuda_devices=cuda_devices,
+            force_cpu=force_cpu,
+        )

brats-0.0.1/brats/constants.py

@@ -0,0 +1,48 @@
+from enum import Enum
+from pathlib import Path
+
+
+class Algorithms(str, Enum):
+    """Parent class for constants of the available algorithms."""
+
+    pass
+
+
+class AdultGliomaAlgorithms(Algorithms):
+    """Constants for the available adult glioma segmentation algorithms."""
+
+    BraTS23_1 = "BraTS23_1"
+    """BraTS23 Adult Glioma Segmentation 1st place (GPU only)"""
+    BraTS23_2 = "BraTS23_2"
+    """BraTS23 Adult Glioma Segmentation 2nd place (GPU only)"""
+    BraTS23_3 = "BraTS23_3"
+    """BraTS23 Adult Glioma Segmentation 3rd place (GPU only)"""
+
+
+class MeningiomaAlgorithms(Algorithms):
+    """Constants for the available meningioma segmentation algorithms."""
+
+    BraTS23_1 = "BraTS23_1"
+    """BraTS23 Meningioma Segmentation 1st place (GPU only)"""
+    BraTS23_2 = "BraTS23_2"
+    """BraTS23 Meningioma Segmentation 2nd place (GPU and CPU)"""
+    BraTS23_3 = "BraTS23_3"
+    """BraTS23 Meningioma Segmentation 3rd place (GPU only)"""
+
+
+class PediatricAlgorithms(Algorithms):
+    """Constants for the available pediatric segmentation algorithms."""
+
+    BraTS23_1 = "BraTS23_1"
+    """BraTS23 Pediatric Segmentation 1st place (GPU only)"""
+    BraTS23_2 = "BraTS23_2"
+    """BraTS23 Pediatric Segmentation 2nd place (GPU only)"""
+    BraTS23_3 = "BraTS23_3"
+    """BraTS23 Pediatric Segmentation 3rd place (GPU only)"""
+
+
+# meta data file paths
+ALGORITHM_DIR = Path(__file__).parent / "algorithms"
+ADULT_GLIOMA_SEGMENTATION_ALGORITHMS = ALGORITHM_DIR / "adult_glioma.yml"
+MENINGIOMA_SEGMENTATION_ALGORITHMS = ALGORITHM_DIR / "meningioma.yml"
+PEDIATRIC_SEGMENTATION_ALGORITHMS = ALGORITHM_DIR / "pediatric.yml"

brats-0.0.1/brats/docker.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import docker
+from halo import Halo
+from loguru import logger
+from rich.progress import Progress
+
+from brats.algorithm_config import AlgorithmData
+from brats.exceptions import AlgorithmNotCPUCompatibleException
+from brats.weights import check_model_weights, get_dummy_weights_path
+
+client = docker.from_env()
+
+
+def _show_docker_pull_progress(tasks: Dict, progress: Progress, line: Dict):
+    """Show the progress of a docker pull operation.
+
+    Args:
+        tasks (Dict): The tasks to update
+        progress (Progress): The progress bar to update
+        line (Dict): the next line from docker.client.api.pull stream
+    """
+    if line["status"] == "Downloading":
+        task_key = f'[Download {line["id"]}]'
+    elif line["status"] == "Extracting":
+        task_key = f'[Extract  {line["id"]}]'
+    else:
+        return
+
+    if task_key not in tasks.keys():
+        tasks[task_key] = progress.add_task(
+            f"{task_key}", total=line["progressDetail"]["total"]
+        )
+    else:
+        progress.update(tasks[task_key], completed=line["progressDetail"]["current"])
+
+
+def _ensure_image(image: str):
+    """Ensure the docker image is present on the system. If not, pull it.
+
+    Args:
+        image (str): The docker image to pull
+    """
+    if not client.images.list(name=image):
+        logger.info(f"Pulling docker image {image}")
+        tasks = {}
+        with Progress() as progress:
+            resp = client.api.pull(image, stream=True, decode=True)
+            for line in resp:
+                _show_docker_pull_progress(tasks=tasks, progress=progress, line=line)
+
+
+def _is_cuda_available() -> bool:
+    """Check if CUDA is available on the system by trying to run nvidia-smi."""
+    try:
+        # Attempt to run `nvidia-smi` to check for CUDA.
+        # This command should run successfully if NVIDIA drivers are installed and GPUs are present.
+        subprocess.run(
+            ["nvidia-smi"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+        return True
+    except:
+        return False
+
+
+def _handle_device_requests(
+    algorithm: AlgorithmData, cuda_devices: str, force_cpu: bool
+) -> List[docker.types.DeviceRequest]:
+    """Handle the device requests for the docker container (request cuda or cpu).
+
+    Args:
+        algorithm (AlgorithmData): Algorithm data
+        cuda_devices (str): The CUDA devices to use
+        force_cpu (bool): Whether to force CPU execution
+    """
+    cuda_available = _is_cuda_available()
+    if not cuda_available or force_cpu:
+        if not algorithm.run_args.cpu_compatible:
+            cause = (
+                "User tried to force CPU execution but"
+                if cuda_available
+                else "No Cuda installation/ GPU was found and"
+            )
+            raise AlgorithmNotCPUCompatibleException(
+                f"{cause} the chosen algorithm is not CPU-compatible. Aborting..."
+            )
+        # empty device requests => run on CPU
+        return []
+    # request gpu with chosen devices
+    return [
+        docker.types.DeviceRequest(device_ids=[cuda_devices], capabilities=[["gpu"]])
+    ]
+
+
+def _get_additional_files_path(algorithm: AlgorithmData) -> Path:
+    """Get the path to the additional files for @algorithm.
+
+    Args:
+        algorithm (AlgorithmData): The algorithm data
+
+    Returns:
+        Path to the additional files
+    """
+    # ensure weights are present and get path
+    if algorithm.weights is not None:
+        return check_model_weights(record_id=algorithm.weights.record_id)
+    else:
+        # if no weights are directly specified a dummy weights folder will be mounted that is potentially used for parameter files etc.
+        return get_dummy_weights_path()
+
+
+def _get_volume_mappings(
+    data_path: Path, additional_files_path: Path, output_path: Path
+) -> Dict:
+    """Get the volume mappings for the docker container.
+
+    Args:
+        data_path (Path): The path to the input data
+        additional_files_path (Path): The path to the additional files
+        output_path (Path): The path to save the output
+
+    Returns:
+        Dict: The volume mappings
+    """
+    # TODO: add support for recommended "ro" mount mode for input data
+    # data = mlcube_io0, additional files = mlcube_io1, output = mlcube_io2
+    return {
+        volume.absolute(): {
+            "bind": f"/mlcube_io{i}",
+            "mode": "rw",
+        }
+        for i, volume in enumerate([data_path, additional_files_path, output_path])
+    }
+
+
+def _build_args(
+    algorithm: AlgorithmData, additional_files_path: Path
+) -> Tuple[str, str]:
+    """Build the command and extra arguments for the docker container.
+
+    Args:
+        algorithm (AlgorithmData): The algorithm data
+        additional_files_path (Path): The path to the additional files
+
+    Returns:
+        command_args, extra_args (Tuple): The command arguments and extra arguments
+    """
+    # Build command that will be run in the docker container
+    command_args = (
+        f"--data_path=/mlcube_io0 --{algorithm.weights.param_name}=/mlcube_io1 --output_path=/mlcube_io2"
+        if algorithm.weights is not None
+        else f"--data_path=/mlcube_io0 --output_path=/mlcube_io2"
+    )
+
+    if algorithm.run_args.parameters_file:
+        # The algorithms that need a parameters file do not seem to actually use it but just need it to exist
+        # As a workaround we simply create an empty file
+        parameters_file = additional_files_path / "parameters.yaml"
+        parameters_file.touch()
+        command_args += f" --parameters_file=/mlcube_io1/parameters.yaml"
+
+    extra_args = {}
+    if not algorithm.run_args.requires_root:
+        # run the container as the current user to ensure written files are always owned by the user
+        # also overall better security-wise
+        extra_args["user"] = f"{os.getuid()}:{os.getgid()}"
+
+    return command_args, extra_args
+
+
+def _observe_docker_output(container: docker.models.containers.Container):
+    """Observe the output of a running docker container and display a spinner. On Errors log container output.
+
+    Args:
+        container (docker.models.containers.Container): The container to observe
+    """
+    # capture the output
+    container_output = container.attach(
+        stdout=True, stderr=True, stream=True, logs=True
+    )
+
+    # Display spinner while the container is running
+    with Halo(text="Running inference...", spinner="dots"):
+        # Wait for the container to finish
+        exit_code = container.wait()
+        # Check if the container exited with an error
+        if exit_code["StatusCode"] != 0:
+            for line in container_output:
+                logger.error(f">> {line.decode('utf-8')}")
+            raise Exception(
+                "Container finished with an error. See logs above for details."
+            )
+
+        # TODO add option to print/ save container output
+
+
+def run_docker(
+    algorithm: AlgorithmData,
+    data_path: Path,
+    output_path: Path,
+    cuda_devices: str,
+    force_cpu: bool,
+):
+    """Run a docker container for the provided algorithm.
+
+    Args:
+        algorithm (AlgorithmData): The data of the algorithm to run
+        data_path (Path | str): The path to the input data
+        output_path (Path | str): The path to save the output
+        cuda_devices (str): The CUDA devices to use
+        force_cpu (bool): Whether to force CPU execution
+    """
+    # ensure image is present, if not pull it
+    _ensure_image(image=algorithm.run_args.docker_image)
+
+    # Log the message
+    additional_files_path = _get_additional_files_path(algorithm)
+
+    # ensure output folder exists
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    volume_mappings = _get_volume_mappings(
+        data_path=data_path,
+        additional_files_path=additional_files_path,
+        output_path=output_path,
+    )
+
+    logger.info(f"{'Starting inference'}")
+
+    command_args, extra_args = _build_args(
+        algorithm=algorithm, additional_files_path=additional_files_path
+    )
+
+    # device setup
+    device_requests = _handle_device_requests(
+        algorithm=algorithm, cuda_devices=cuda_devices, force_cpu=force_cpu
+    )
+
+    # Run the container
+    container = client.containers.run(
+        image=algorithm.run_args.docker_image,
+        volumes=volume_mappings,
+        device_requests=device_requests,
+        command=f"infer {command_args}",
+        network_mode="none",
+        detach=True,
+        remove=True,
+        shm_size=algorithm.run_args.shm_size,
+        **extra_args,
+    )
+    _observe_docker_output(container=container)
+
+    logger.info(f"{'Finished inference'}")

brats-0.0.1/brats/exceptions.py

@@ -0,0 +1,15 @@
+from dacite import DaciteError
+
+
+class AlgorithmNotCPUCompatibleException(Exception):
+    """Exception raised when an CPU-incompatible algorithm tries to run on CPU."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class AlgorithmConfigException(DaciteError):
+    """Exception raised when the algorithm config file has issues."""
+
+    def __init__(self, message: str):
+        super().__init__(message)

brats-0.0.1/brats/utils.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+from loguru import logger
+
+
+def standardize_subject_inputs(
+    data_folder: Path,
+    subject_id: str,
+    t1c: Path | str,
+    t1n: Path | str,
+    t2f: Path | str,
+    t2w: Path | str,
+):
+    """Standardize the input images for a single subject to match requirements of all algorithms and save them in @data_folder/@internal_name.
+        Meaning, e.g. for adult glioma:
+            BraTS-GLI-00000-000 \n
+            ┣ BraTS-GLI-00000-000-t1c.nii.gz \n
+            ┣ BraTS-GLI-00000-000-t1n.nii.gz \n
+            ┣ BraTS-GLI-00000-000-t2f.nii.gz \n
+            ┗ BraTS-GLI-00000-000-t2w.nii.gz \n
+
+    Args:
+        data_folder (Path): Parent folder where the subject folder will be created
+        subject_id (str): Subject ID to be used for the folder and filenames
+        t1c (Path | str): T1c image path
+        t1n (Path | str): T1n image path
+        t2f (Path | str): T2f image path
+        t2w (Path | str): T2w image path
+    """
+    subject_folder = data_folder / subject_id
+    subject_folder.mkdir(parents=True, exist_ok=True)
+    # TODO: investigate usage of symlinks (might cause issues on windows and would probably require different volume handling)
+    try:
+        shutil.copy(t1c, subject_folder / f"{subject_id}-t1c.nii.gz")
+        shutil.copy(t1n, subject_folder / f"{subject_id}-t1n.nii.gz")
+        shutil.copy(t2f, subject_folder / f"{subject_id}-t2f.nii.gz")
+        shutil.copy(t2w, subject_folder / f"{subject_id}-t2w.nii.gz")
+    except FileNotFoundError as e:
+        logger.error(f"Error while standardizing files: {e}")
+        logger.error(
+            "Please make sure the input files are in the correct format, i.e.:\n A/A-t1c.nii.gz, A/A-t1n.nii.gz, A/A-t2f.nii.gz, A/A-t2w.nii.gz"
+        )
+        sys.exit(1)
+
+
+def standardize_subjects_inputs_list(
+    subjects: List[Path], temp_data_folder: Path, input_name_schema: str
+) -> Dict[str, str]:
+    """Standardize the input images for a list of subjects to match requirements of all algorithms and save them in @temp_data_folder/@subject_id.
+
+    Args:
+        subjects (List[Path]): List of subject folders, each with a t1c, t1n, t2f, t2w image in standard format
+        temp_data_folder (Path): Parent folder where the subject folders will be created
+        input_name_schema (str): Schema to be used for the subject folder and filenames depending on the BraTS Challenge
+
+    Returns:
+        Dict[str, str]: Dictionary mapping internal name (in standardized format) to external subject name provided by user
+    """
+    internal_external_name_map = {}
+    for i, subject in enumerate(subjects):
+        internal_name = input_name_schema.format(id=i)
+        internal_external_name_map[internal_name] = subject.name
+        # TODO Add support for .nii files
+
+        standardize_subject_inputs(
+            data_folder=temp_data_folder,
+            subject_id=internal_name,
+            t1c=subject / f"{subject.name}-t1c.nii.gz",
+            t1n=subject / f"{subject.name}-t1n.nii.gz",
+            t2f=subject / f"{subject.name}-t2f.nii.gz",
+            t2w=subject / f"{subject.name}-t2w.nii.gz",
+        )
+    return internal_external_name_map

brats-0.0.1/brats/weights.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import shutil
+import sys
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import Dict, List
+
+import requests
+from loguru import logger
+from tqdm import tqdm
+
+ZENODO_RECORD_BASE_URL = "https://zenodo.org/api/records"
+WEIGHTS_FOLDER = Path(__file__).parent / "weights"
+
+
+def get_dummy_weights_path() -> Path:
+    dummy = WEIGHTS_FOLDER / "dummy"
+    dummy.mkdir(exist_ok=True, parents=True)
+    return dummy
+
+
+def check_model_weights(record_id: str) -> Path:
+    """Check if latest model weights are present and download them otherwise.
+
+    Returns:
+        Path: Path to the model weights folder.
+    """
+
+    zenodo_metadata, archive_url = _get_zenodo_metadata_and_archive_url(
+        record_id=record_id
+    )
+
+    record_weights_pattern = f"{record_id}_v*.*.*"
+    matching_folders = list(WEIGHTS_FOLDER.glob(record_weights_pattern))
+    # Get the latest downloaded weights
+    latest_downloaded_weights = _get_latest_version_folder_name(matching_folders)
+
+    if not latest_downloaded_weights:
+        if not zenodo_metadata:
+            logger.error(
+                "Model weights not found locally and Zenodo could not be reached. Exiting..."
+            )
+            sys.exit()
+        logger.info(f"Model weights not found locally")
+
+        return _download_model_weights(
+            zenodo_metadata=zenodo_metadata,
+            record_id=record_id,
+            archive_url=archive_url,
+        )
+
+    logger.info(f"Found downloaded local weights: {latest_downloaded_weights}")
+
+    if not zenodo_metadata:
+        logger.warning(
+            "Zenodo server could not be reached. Using the latest downloaded weights."
+        )
+        return WEIGHTS_FOLDER / latest_downloaded_weights
+
+    # Compare the latest downloaded weights with the latest Zenodo version
+    if zenodo_metadata["version"] == latest_downloaded_weights.split("_v")[1]:
+        logger.info(
+            f"Latest model weights ({latest_downloaded_weights}) are already present."
+        )
+        return WEIGHTS_FOLDER / latest_downloaded_weights
+
+    logger.info(
+        f"New model weights available on Zenodo ({zenodo_metadata['version']}). Deleting old and fetching new weights..."
+    )
+    # delete old weights
+    shutil.rmtree(
+        WEIGHTS_FOLDER / latest_downloaded_weights,
+        onerror=lambda func, path, excinfo: logger.warning(
+            f"Failed to delete {path}: {excinfo}"
+        ),
+    )
+    return _download_model_weights(
+        zenodo_metadata=zenodo_metadata, record_id=record_id, archive_url=archive_url
+    )
+
+
+def _get_latest_version_folder_name(folders: List[Path]) -> str | None:
+    """Get the latest (non empty) version folder name from the list of folders.
+
+    Args:
+        folders (List[Path]): List of folders matching the pattern.
+
+    Returns:
+        str | None: Latest version folder name if one exists, else None.
+    """
+    if not folders:
+        return None
+    latest_downloaded_folder = sorted(
+        folders,
+        reverse=True,
+        key=lambda x: tuple(map(int, str(x).split("_v")[1].split("."))),
+    )[0]
+    # check folder is not empty
+    if not list(latest_downloaded_folder.glob("*")):
+        return None
+    return latest_downloaded_folder.name
+
+
+def _get_zenodo_metadata_and_archive_url(record_id: str) -> Dict | None:
+    """Get the metadata for the Zenodo record and the files archive url.
+
+    Returns:
+        Tuple: (dict: Metadata for the Zenodo record, str: URL to the archive file)
+    """
+    try:
+        response = requests.get(f"{ZENODO_RECORD_BASE_URL}/{record_id}")
+        if response.status_code != 200:
+            logger.error(
+                f"Cant find model weights for record_id '{record_id}' on Zenodo. Exiting..."
+            )
+        data = response.json()
+        return data["metadata"], data["links"]["archive"]
+
+    except requests.exceptions.RequestException as e:
+        logger.warning(f"Failed to fetch Zenodo metadata: {e}")
+        return None
+
+
+def _download_model_weights(
+    zenodo_metadata: Dict, record_id: str, archive_url: str
+) -> Path:
+    """Download the latest model weights from Zenodo for the requested record and extract them to the target folder.
+
+    Args:
+        weights_folder (Path): General weights folder path in which the requested model weights will be stored.
+        zenodo_metadata (Dict): Metadata for the Zenodo record.
+        record_id (str): Zenodo record ID.
+
+    Returns:
+        Path: Path to the model weights folder for the requested record.
+    """
+    record_weights_folder = (
+        WEIGHTS_FOLDER / f"{record_id}_v{zenodo_metadata['version']}"
+    )
+    # ensure folder exists
+    record_weights_folder.mkdir(parents=True, exist_ok=True)
+
+    logger.info(f"Downloading model weights from Zenodo. This might take a while...")
+    # Make a GET request to the URL
+    response = requests.get(archive_url, stream=True)
+    # Ensure the request was successful
+    if response.status_code != 200:
+        logger.error(
+            f"Failed to download model weights. Status code: {response.status_code}"
+        )
+        return
+
+    # Download with progress bar
+    chunk_size = 1024  # 1KB
+    bytes_io = BytesIO()
+    with tqdm(
+        total=0,  # unknown size since content length not given
+        unit="B",
+        unit_scale=True,
+    ) as pbar:
+        for data in response.iter_content(chunk_size=chunk_size):
+            bytes_io.write(data)
+            pbar.update(len(data))
+
+    # Extract the downloaded zip file to the target folder
+    with zipfile.ZipFile(bytes_io) as zip_ref:
+        zip_ref.extractall(record_weights_folder)
+
+    # check if the extracted file is still a zip
+    for f in record_weights_folder.iterdir():
+        if f.is_file() and f.suffix == ".zip":
+            with zipfile.ZipFile(f) as zip_ref:
+                zip_ref.extractall(record_weights_folder)
+            f.unlink()  # remove zip after extraction
+
+    logger.info(f"Zip file extracted successfully to {record_weights_folder}")
+    return record_weights_folder

brats-0.0.1/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "BraTS"
+version = "0.0.1"
+authors = [
+  { name="Example Author", email="author@example.com" },
+]
+description = "A small example package"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/pypa/sampleproject"
+Issues = "https://github.com/pypa/sampleproject/issues"

brats-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brats-0.0.1/tests/test_algorithm_config.py

@@ -0,0 +1,20 @@
+import unittest
+from pathlib import Path
+
+from brats.algorithm_config import load_algorithms
+
+PACKAGE_DIR = Path(__file__).parent.parent
+
+
+class TestAlgorithmConfig(unittest.TestCase):
+
+    def test_configs_valid(self):
+        algorithms_folder = PACKAGE_DIR / "brats" / "algorithms"
+
+        configs = algorithms_folder.iterdir()
+
+        for config in configs:
+            try:
+                load_algorithms(file_path=config)
+            except Exception as e:
+                self.fail(f"Failed to load config {config}: {e}")

brats-0.0.1/tests/test_utils.py

@@ -0,0 +1,84 @@
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from loguru import logger
+
+from brats.utils import standardize_subject_inputs, standardize_subjects_inputs_list
+
+
+class TestStandardizeInputs(unittest.TestCase):
+    def setUp(self):
+        # Create a temporary directory
+        self.test_dir = Path(tempfile.mkdtemp())
+        self.data_folder = self.test_dir / "data"
+        self.data_folder.mkdir(parents=True, exist_ok=True)
+        self.temp_data_folder = self.test_dir / "tmp_std_data"
+        self.temp_data_folder.mkdir(parents=True, exist_ok=True)
+
+        # Create mock paths for input images
+        self.subject_folder = self.data_folder / "subject"
+        self.subject_folder.mkdir(parents=True, exist_ok=True)
+        self.t1c = self.data_folder / "subject-t1c.nii.gz"
+        self.t1n = self.data_folder / "subject-t1n.nii.gz"
+        self.t2f = self.data_folder / "subject-t2f.nii.gz"
+        self.t2w = self.data_folder / "subject-t2w.nii.gz"
+        # Create dummy files
+        for img in [self.t1c, self.t1n, self.t2f, self.t2w]:
+            img.touch(exist_ok=True)
+
+    def tearDown(self):
+        # Remove the temporary directory after the test
+        shutil.rmtree(self.test_dir)
+
+    def test_successful_standardization(self):
+        subject_id = "test_subject"
+        standardize_subject_inputs(
+            data_folder=self.temp_data_folder,
+            subject_id=subject_id,
+            t1c=self.t1c,
+            t1n=self.t1n,
+            t2f=self.t2f,
+            t2w=self.t2w,
+        )
+        subject_folder = self.temp_data_folder / subject_id
+        self.assertTrue(subject_folder.exists())
+        for img_type in ["t1c", "t1n", "t2f", "t2w"]:
+            self.assertTrue(
+                (subject_folder / f"{subject_id}-{img_type}.nii.gz").exists()
+            )
+
+    @patch("sys.exit")
+    @patch.object(logger, "error")
+    def test_handle_file_not_found_error(self, mock_logger, mock_exit):
+        subject_id = "test_subject"
+        # Provide a non-existent file path for t1c
+        t1c = "non_existent_file.nii.gz"
+        standardize_subject_inputs(
+            data_folder=self.data_folder,
+            subject_id=subject_id,
+            t1c=t1c,
+            t1n=self.t1n,
+            t2f=self.t2f,
+            t2w=self.t2w,
+        )
+        mock_logger.assert_called()
+        mock_exit.assert_called_with(1)
+
+    @patch("brats.utils.standardize_subject_inputs")
+    def test_standardize_subjects_inputs_list(self, mock_standardize_subject_inputs):
+        subjects = [f for f in self.data_folder.iterdir() if f.is_dir()]
+        mapping = standardize_subjects_inputs_list(
+            subjects=subjects,
+            temp_data_folder=self.temp_data_folder,
+            input_name_schema="BraTS-PED-{id:05d}-000",
+        )
+        self.assertDictEqual(
+            mapping,
+            {
+                "BraTS-PED-00000-000": "subject",
+            },
+        )
+        mock_standardize_subject_inputs.assert_called_once()