BraTS 0.0.0.dev0__py3-none-any.whl

brats/core/singularity.py

@@ -0,0 +1,268 @@
+from brats.utils.algorithm_config import AlgorithmData
+from pathlib import Path
+
+import subprocess
+from typing import Dict, List, Optional, Union
+from brats.core.docker import (
+    _log_algorithm_info,
+    _sanity_check_output,
+    _get_additional_files_path,
+    _get_volume_mappings_mlcube,
+    _get_parameters_arg,
+    _handle_device_requests,
+    _get_volume_mappings_docker_only,
+    _ensure_image as _ensure_docker_image,
+)
+from brats.constants import PARAMETERS_DIR
+from loguru import logger
+import time
+from spython.main import Client
+import docker
+import tempfile
+import os
+
+try:
+    docker_client = docker.from_env()
+except docker.errors.DockerException as e:
+    logger.debug(
+        "Could not connect to the Docker daemon. Docker functionality is disabled, so the Singularity container's working directory may not be set correctly."
+    )
+    docker_client = None
+
+
+def _build_command_args(
+    algorithm: AlgorithmData,
+) -> List[str]:
+    """Build the command arguments for the singularity container.
+
+    Args:
+        algorithm (AlgorithmData): The algorithm data
+
+    Returns:
+        List[str]: The command arguments
+    """
+
+    command_args = ["--data_path=/mlcube_io0", "--output_path=/mlcube_io2"]
+    if algorithm.additional_files is not None:
+        for i, param in enumerate(algorithm.additional_files.param_name):
+            additional_files_arg = f"--{param}=/mlcube_io1"
+            if algorithm.additional_files.param_path:
+                additional_files_arg += f"/{algorithm.additional_files.param_path[i]}"
+            command_args.append(additional_files_arg)
+
+    # Add parameters file arg if required
+    params_arg = _get_parameters_arg(algorithm=algorithm)
+    if params_arg:
+        command_args.append(params_arg.strip())
+
+    return command_args
+
+
+def _ensure_image(image: str) -> str:
+    """
+    Ensure the Singularity image is present on the system. If not, pull it as a Sandbox.
+    This function checks if the specified Singularity image exists locally in the temporary directory.
+    If the image is not found, it pulls the image from Docker Hub, creates a Singularity Sandbox at the target location.
+
+    Args:
+        image (str): The Docker image to pull and convert into a Singularity Sandbox.
+
+    Returns:
+        str: The path to the Singularity image Sandbox.
+    """
+    persistent_dir = os.path.join(tempfile.gettempdir(), "brats_singularity_images")
+    os.makedirs(persistent_dir, exist_ok=True)
+    logger.debug(f"Persistent folder: {persistent_dir}")
+    temp_folder = Path(persistent_dir)
+    image_path = temp_folder.joinpath(image.replace(":", "_"))
+    if not image_path.exists():
+        image_path.parent.mkdir(parents=True, exist_ok=True)
+        logger.debug(
+            f"Pulling Singularity image {image} and creating a Sandbox at {image_path}"
+        )
+        subprocess.run(
+            [
+                "singularity",
+                "build",
+                "--sandbox",
+                "--fakeroot",
+                str(image_path),
+                f"docker://{image}",
+            ],
+            check=True,
+        )
+
+    return str(image_path)
+
+
+def _convert_volume_mappings_to_singularity_format(
+    volume_mappings: Dict[Union[Path, str], Dict[str, str]],
+) -> List[str]:
+    """Convert volume mappings from Docker format to Singularity format.
+
+    Args:
+        volume_mappings (Dict[Path | str, Dict[str, str]]): The volume mappings in Docker format
+
+    Returns:
+        List[str]: The volume mappings in Singularity format
+    """
+    singularity_bindings = []
+    for host_path, val in volume_mappings.items():
+        container_path = val["bind"]
+        singularity_bindings.append(f"{str(host_path)}:{container_path}")
+    return singularity_bindings
+
+
+def _get_docker_working_dir(image: str) -> Optional[Path]:
+    """
+    Retrieve the working directory configured in the Docker image.
+
+    This is required to properly initialize the working directory for the Singularity container,
+    ensuring that the container starts in the correct location as defined by the Docker image.
+
+    Args:
+        image (str): The Docker image name or ID.
+
+    Returns:
+        Path | None: The working directory specified in the Docker image configuration. None if docker client is not available.
+    """
+    if docker_client is None:
+        return None
+    try:
+        logger.debug(f"Inspecting image {image}")
+        image_obj = docker_client.images.get(image)
+    except docker.errors.ImageNotFound:
+        logger.debug(f"Image {image} not found locally.")
+        _ensure_docker_image(image)
+        image_obj = docker_client.images.get(image)
+    workdir = image_obj.attrs["Config"].get("WorkingDir", None)
+    logger.debug(f"Working directory: {workdir}")
+    if workdir is None:
+        return None
+    else:
+        return Path(workdir)
+
+
+def run_container(
+    algorithm: AlgorithmData,
+    data_path: Path,
+    output_path: Path,
+    cuda_devices: str,
+    force_cpu: bool,
+    internal_external_name_map: Optional[Dict[str, str]] = None,
+    overlay_size: int = 1024,
+):
+    """Run a Singularity 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
+        internal_external_name_map (Dict[str, str]): Dictionary mapping internal name (in standardized format) to external subject name provided by user (only used for batch inference)
+        overlay_size (int): The size of the overlay image in MB. Defaults to 1024.
+    """
+    if overlay_size <= 0:
+        raise ValueError("Overlay size must be greater than 0.")
+    _log_algorithm_info(algorithm=algorithm)
+    # ensure image is present, if not pull it
+    image = _ensure_image(image=algorithm.run_args.docker_image)
+
+    additional_files_path = _get_additional_files_path(algorithm)
+    logger.debug(f"Additional files path: {additional_files_path}")
+    # ensure output folder exists
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    command_args = _build_command_args(algorithm=algorithm)
+    command_args_str = " ".join(command_args)
+    logger.debug(f"Command args: {command_args_str}")
+    if algorithm.meta.year <= 2024:
+        volume_mappings = _get_volume_mappings_mlcube(
+            data_path=data_path,
+            additional_files_path=additional_files_path,
+            output_path=output_path,
+            parameters_path=PARAMETERS_DIR,
+        )
+        args = ["infer", *command_args]
+    else:
+        volume_mappings = _get_volume_mappings_docker_only(
+            data_path=data_path,
+            output_path=output_path,
+        )
+        args = None
+
+    logger.debug(f"Volume mappings: {volume_mappings}")
+
+    # device setup
+    device_requests = _handle_device_requests(
+        algorithm=algorithm, cuda_devices=cuda_devices, force_cpu=force_cpu
+    )
+    logger.debug(f"GPU Device requests: {device_requests}")
+
+    # Run the container
+    logger.info("Starting inference")
+    start_time = time.time()
+
+    singularity_bindings = _convert_volume_mappings_to_singularity_format(
+        volume_mappings
+    )
+
+    options = []
+
+    if len(device_requests) > 0 and not force_cpu:
+        logger.info(f"Using CUDA devices: {cuda_devices}")
+        options.append("--nv")  # Singularity uses --nv to enable GPU support
+
+    # TODO: The --fakeroot option may be required for certain algorithms that need root privileges inside the Singularity container.
+    docker_working_dir = _get_docker_working_dir(algorithm.run_args.docker_image)
+    if docker_working_dir is not None:
+        options.append("--cwd")
+        options.append(str(docker_working_dir))
+    else:
+        logger.warning(
+            "Docker working directory not found. Using default working directory."
+        )
+    overlay_path = Path(image).parent / (Path(image).name + "_overlay.img")
+    options.append("--overlay")
+    options.append(str(overlay_path))
+
+    overlay_created = False
+    if not overlay_path.exists():
+        subprocess.run(
+            [
+                "singularity",
+                "overlay",
+                "create",
+                "--size",
+                str(overlay_size),
+                str(overlay_path),
+            ],
+            check=True,
+        )
+        overlay_created = True
+    try:
+        executor = Client.run(
+            image,
+            options=options,
+            args=args,
+            stream=True,
+            bind=singularity_bindings,
+        )
+        container_output = []
+        for line in executor:
+            container_output.append(line)
+
+        _sanity_check_output(
+            data_path=data_path,
+            output_path=output_path,
+            container_output="\n".join(container_output),
+            internal_external_name_map=internal_external_name_map,
+        )
+    finally:
+        try:
+            if overlay_created:
+                overlay_path.unlink()
+        except FileNotFoundError:
+            pass
+    logger.info(f"Finished inference in {time.time() - start_time:.2f} seconds")

brats/data/meta/adult_glioma_pre_and_post_treatment.yml

@@ -0,0 +1,123 @@
+constants:
+  input_name_schema: &input_name_schema "BraTS-GLI-{id:05d}-000"
+  challenge: &challenge "Adult Glioma Segmentation (Pre & Post Treatment)"
+  challenge_manuscript:
+    2025: &challenge_manuscript_2025 "https://arxiv.org/abs/2405.18368" # same as 2024
+    2024: &challenge_manuscript_2024 "https://arxiv.org/abs/2405.18368"
+  years:
+    2025: &year_2025 2025
+    2024: &year_2024 2024
+  ranks:
+    1st: &rank_1 1st
+    2nd: &rank_2 2nd
+    3rd: &rank_3 3rd
+
+
+algorithms:
+
+##### 2025 #####
+  BraTS25_1:
+    meta:
+      authors: Ishika Jain, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_1
+      year: *year_2025
+    run_args:
+      docker_image: brainles/brats25_gli_aia-bots:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+
+  BraTS25_2:
+    meta:
+      authors: Qu Lin, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_2
+      year: *year_2025
+    run_args:
+      docker_image: brainles/brats25_gli_ecnu:latest
+      input_name_schema: *input_name_schema
+      cpu_compatible: true # ~ 7 min/ subject
+      requires_root: true
+
+  BraTS25_3A:
+    meta:
+      authors: Liwei Jin, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_3
+      year: *year_2025
+    run_args:
+      docker_image: brainles/brats25_gli_jinlw:latest
+      input_name_schema: *input_name_schema
+      cpu_compatible: true # ~150min / subject
+
+  BraTS25_3B:
+    meta:
+      authors: Adrian Celaya, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_3
+      year: *year_2025
+    run_args:
+      docker_image: brainles/brats25_gli_mist:latest
+      input_name_schema: *input_name_schema
+
+##### 2024 #####
+  BraTS24_1:
+    meta:
+      authors: André Ferreira, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_1
+      year: *year_2024
+    run_args:
+      docker_image:  brainles/brats24_adult_glioma_faking_it:latest
+      input_name_schema: *input_name_schema
+      requires_root: false
+      parameters_file: false
+      shm_size: "4gb"
+
+  BraTS24_2:
+    meta:
+      authors: Heejong Kim, et al.
+      paper: https://arxiv.org/abs/2409.08143
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_2
+      year: *year_2024
+    run_args:
+      docker_image: brainles/brats24_adult_glioma_kimbab:latest
+      input_name_schema: *input_name_schema
+      requires_root: false
+      parameters_file: false
+      shm_size: "2gb"
+    additional_files:
+      record_id: "14413387"
+      param_name: ["nnunet_env_path"]
+
+  BraTS24_3:
+    meta:
+      authors: Adrian Celaya
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_3
+      year: *year_2024
+    run_args:
+      docker_image: brainles/brats24_adult_glioma_mist:latest
+      input_name_schema: *input_name_schema
+      requires_root: false
+      parameters_file: true
+      shm_size: "2gb"
+      cpu_compatible: true
+    additional_files:
+      record_id: "14411467"
+      param_name: ["mist_models", "mist_config", "mist_dataset"]
+      param_path: ["models", "config.json", "dataset.json"]

brats/data/meta/adult_glioma_pre_treatment.yml

@@ -0,0 +1,64 @@
+constants:
+  input_name_schema: &input_name_schema "BraTS-GLI-{id:05d}-000"
+  challenge: &challenge "Adult Glioma Segmentation (Pre Treatment)"
+  challenge_manuscript:
+    2023: &challenge_manuscript_2023 "https://arxiv.org/abs/2107.02314"
+  years:
+    2023: &year_2023 2023
+  ranks:
+    1st: &rank_1 1st
+    2nd: &rank_2 2nd
+    3rd: &rank_3 3rd
+
+
+algorithms:
+
+##### 2023 #####
+
+  BraTS23_1:
+    meta:
+      authors: André Ferreira, et al.
+      paper: https://doi.org/10.1007/978-3-031-76163-8_8
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      rank: *rank_1
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_faking_it:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+      parameters_file: false
+      shm_size: "2gb"
+
+  BraTS23_2:
+    meta:
+      authors: Andriy Myronenko, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      rank: *rank_2
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_nvauto:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+      parameters_file: true
+      shm_size: "32gb"
+
+  BraTS23_3:
+    meta:
+      authors: Fadillah Adamsyah Maani, et al.
+      paper: https://doi.org/10.1007/978-3-031-76163-8_24
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      rank: *rank_3
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_biomedmbz:latest
+      input_name_schema: *input_name_schema
+      requires_root: false
+      parameters_file: true
+      shm_size: "2gb"
+    additional_files:
+      record_id: "11573315"
+      param_name: ["checkpoint_dir"]

brats/data/meta/africa.yml

@@ -0,0 +1,185 @@
+constants:
+  input_name_schema: &input_name_schema "BraTS-SSA-{id:05d}-000"
+  challenge: &challenge "BraTS-Africa Segmentation"
+  dataset_manuscript: &dataset_manuscript "https://pubs.rsna.org/doi/full/10.1148/ryai.240528"
+  challenge_manuscript:
+    2025: &challenge_manuscript_2025 "https://arxiv.org/abs/2305.19369" # remained the same as 2023 & 2024
+    2024: &challenge_manuscript_2024 "https://arxiv.org/abs/2305.19369" # remained the same as 2023
+    2023: &challenge_manuscript_2023 "https://arxiv.org/abs/2305.19369"
+  years:
+    2025: &year_2025 2025
+    2024: &year_2024 2024
+    2023: &year_2023 2023
+  ranks:
+    1st: &rank_1 1st
+    2nd: &rank_2 2nd
+    3rd: &rank_3 3rd
+
+
+algorithms:
+
+##### 2025 #####
+
+  BraTS25_1:
+    meta:
+      authors: Claudia Takyi Ankomah, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_1
+      year: *year_2025
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats25_ssa_spark_neuro:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+      cpu_compatible: true # ~2 hours on CPU
+
+  BraTS25_2A:
+    meta:
+      authors: William Boonzaier, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_2
+      year: *year_2025
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats25_ssa_spark2025_team_sparkans:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+  
+  BraTS25_2B:
+    meta:
+      authors: Mohtady Barakat, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_2
+      year: *year_2025
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats25_ssa_spark2025_team_wakanda:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+
+  BraTS25_3:
+    meta:
+      authors: Ahmed Jaheen, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2025
+      rank: *rank_3
+      year: *year_2025
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats25_ssa_biomedia_mbzuai:latest
+      input_name_schema: *input_name_schema
+      requires_root: true
+
+##### 2024 #####
+
+  BraTS24_1:
+    meta:
+      authors: Abhijeet Parida, et al.
+      paper: https://arxiv.org/abs/2412.04111
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_1
+      year: *year_2024
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats24_africa_cnmc_pmi:latest
+      input_name_schema: *input_name_schema 
+      requires_root: false
+      parameters_file: false
+      shm_size: "2gb"
+  
+  BraTS24_2:
+    meta:
+      authors: Yanguang Zhao, et al.
+      paper: https://arxiv.org/abs/2410.18698
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_2
+      year: *year_2024
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats24_africa_cuhk_rpai
+      input_name_schema: *input_name_schema 
+      requires_root: false
+      parameters_file: true
+      shm_size: "2gb"
+      cpu_compatible: true
+  
+  BraTS24_3:
+    meta:
+      authors: Sarim Hashmi, et al.
+      paper: https://arxiv.org/abs/2411.15872
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2024
+      rank: *rank_3
+      year: *year_2024
+      dataset_manuscript: *dataset_manuscript
+    run_args:
+      docker_image: brainles/brats24_africa_biomedia-mbzu
+      input_name_schema: *input_name_schema 
+      requires_root: false
+      parameters_file: true
+      shm_size: "2gb"
+    additional_files:
+      record_id: "14414932"
+      param_name: ["checkpoint_dir"]
+
+##### 2023 #####
+
+  BraTS23_1:
+    meta:
+      authors: Andriy Myronenko, et al.
+      paper: N/A
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      dataset_manuscript: *dataset_manuscript
+      rank: *rank_1
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_africa_nvauto:latest
+      input_name_schema: *input_name_schema 
+      requires_root: true
+      parameters_file: true
+      shm_size: "32gb"
+
+  BraTS23_2:
+    meta:
+      authors: Alyssa R Amod, et al.
+      paper: https://doi.org/10.1007/978-3-031-76163-8_22
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      dataset_manuscript: *dataset_manuscript
+      rank: *rank_2
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_africa_sparkunn:latest
+      input_name_schema: *input_name_schema 
+      requires_root: false
+      parameters_file: true
+    additional_files:
+      record_id: "13373752"
+      param_name: ["ckpts_path"]
+
+  BraTS23_3:
+    meta:
+      authors: Ziyan Huang, et al.
+      paper: https://doi.org/10.1007/978-3-031-76163-8_13
+      challenge: *challenge
+      challenge_manuscript: *challenge_manuscript_2023
+      dataset_manuscript: *dataset_manuscript
+      rank: *rank_3
+      year: *year_2023
+    run_args:
+      docker_image: brainles/brats23_africa_blackbean:latest
+      input_name_schema: *input_name_schema 
+      requires_root: true
+      parameters_file: true
+      cpu_compatible: true
+