Notebook Tutorial¶

In this Notebook we demonstrate how to utilize the BraTS package to use top performing algorithms from recent BraTS challenges.

---

Getting Started¶

This tutorial requires:¶

• Python 3.8+
• Docker: Installation instructions on the official website

Optional but recommended:¶

• GPU with CUDA support (otherwise CPU can be used for a some algorithms)
• NVIDIA Container Toolkit: Refer to the NVIDIA install guide and the official GitHub page

In [1]:

# Installations
!pip install brats matplotlib ipywidgets > /dev/null

%load_ext autoreload
%autoreload 2

BASE_PATH = "./"

# Installations !pip install brats matplotlib ipywidgets > /dev/null %load_ext autoreload %autoreload 2 BASE_PATH = "./"

Imports¶

In [2]:

from pathlib import Path

import utils  # local file

from brats import AdultGliomaPreTreatmentSegmenter
from brats.constants import AdultGliomaPreTreatmentAlgorithms

from pathlib import Path import utils # local file from brats import AdultGliomaPreTreatmentSegmenter from brats.constants import AdultGliomaPreTreatmentAlgorithms

---

Data¶

Example data¶

brats expects preprocessed input data as NIfTI files (preprocessed meaning the files should be co-registerend, skullstripped and in SRI-24 space).

In this example we provide:

• two set of preprocessed inputs for segmentation in BraTS/data/segmentation (data from RSNA-ASNR-MICCAI BraTS Continuous Evaluation Challenge)
• one set of inputs for inpainting in BraTS/data/inpainting (data from ASNR-MICCAI BraTS Local Synthesis of Tissue via Inpainting)

To get an intuition of the data, one example slice of the 3D scans is visualized below for a set of segementation (t1n, t1c, t2f, t2w) and inpainting (t1n, mask) inputs. We do not separately plot data for the Missing MRI algorithms since they are equivalent to segmentation data (except that on modality can be missing)

In [3]:

subject = "BraTS-GLI-00001-000"
segmentation_data_path = Path(BASE_PATH) / "data" / "segmentation"
inpainting_data_path = Path(BASE_PATH) / "data" / "inpainting"
missing_mri_path = segmentation_data_path

segmentation_subject_path = segmentation_data_path / subject
inpainting_subject_path = inpainting_data_path / subject

utils.visualize_segmentation_data(segmentation_data_path, subject_id=subject)
utils.visualize_inpainting_data(inpainting_data_path, subject_id=subject)

subject = "BraTS-GLI-00001-000" segmentation_data_path = Path(BASE_PATH) / "data" / "segmentation" inpainting_data_path = Path(BASE_PATH) / "data" / "inpainting" missing_mri_path = segmentation_data_path segmentation_subject_path = segmentation_data_path / subject inpainting_subject_path = inpainting_data_path / subject utils.visualize_segmentation_data(segmentation_data_path, subject_id=subject) utils.visualize_inpainting_data(inpainting_data_path, subject_id=subject)

Using your data¶

If your data is not preprocessed yet, consider using our BrainLes preprocessing package (or its predecessor BraTS-Toolkit).

Using BraTS¶

Segmentation Tasks¶

Minimal example using default settings¶

In [4]:

segmenter = AdultGliomaPreTreatmentSegmenter()
segmenter.infer_single(
    t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz",
    t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz",
    t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz",
    t2w=segmentation_subject_path / f"{subject}-t2w.nii.gz",
    output_file="segmentation.nii.gz",
)

segmenter = AdultGliomaPreTreatmentSegmenter() segmenter.infer_single( t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz", t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz", t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz", t2w=segmentation_subject_path / f"{subject}-t2w.nii.gz", output_file="segmentation.nii.gz", )

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                                              BraTS Package | https://arxiv.org/abs/2506.13807            
------------------------------------------------------------+---------------------------------------------
 Challenge (Adult Glioma Segmentation (Pre Treatment) 2023) | https://arxiv.org/abs/2107.02314            
------------------------------------------------------------+---------------------------------------------
                         Algorithm (André Ferreira, et al.) | https://doi.org/10.1007/978-3-031-76163-8_8 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

Visualize results¶

In [7]:

utils.visualize_segmentation(
    modality_file=segmentation_subject_path / f"{subject}-t1c.nii.gz",
    segmentation_file="segmentation.nii.gz",
)

utils.visualize_segmentation( modality_file=segmentation_subject_path / f"{subject}-t1c.nii.gz", segmentation_file="segmentation.nii.gz", )

Batch processing¶

BraTS allows to run an algorithm for a single set of input images (t1n, t1c, t2f, t2w of the same patient) or for multiple subjects. Each of the available classes provides methods for both:

• .infer_single(...) that takes in the paths to the required input modalities and a path to store the result
• .infer_batch(...) that takes in a path to a data folder containing multiple sets of subjects and a path to an output folder to store the results

The sets of subject inputs need to be stored in a specific structure to be recognized by the package:

data_folder
┣ A
┃ ┣ A-t1c.nii.gz
┃ ┣ A-t1n.nii.gz
┃ ┣ A-t2f.nii.gz
┃ ┗ A-t2w.nii.gz
┣ B
┃ ┣ B-t1c.nii.gz
┃ ┣ ...

In [8]:

output_path = Path("batch_out")

segmenter = AdultGliomaPreTreatmentSegmenter()
segmenter.infer_batch(
    data_folder=segmentation_data_path,
    output_folder=output_path,
)

print(f"Inferred segmentations: {[path.name for path in output_path.iterdir()]}")

output_path = Path("batch_out") segmenter = AdultGliomaPreTreatmentSegmenter() segmenter.infer_batch( data_folder=segmentation_data_path, output_folder=output_path, ) print(f"Inferred segmentations: {[path.name for path in output_path.iterdir()]}")

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                                              BraTS Package | https://arxiv.org/abs/2506.13807            
------------------------------------------------------------+---------------------------------------------
 Challenge (Adult Glioma Segmentation (Pre Treatment) 2023) | https://arxiv.org/abs/2107.02314            
------------------------------------------------------------+---------------------------------------------
                         Algorithm (André Ferreira, et al.) | https://doi.org/10.1007/978-3-031-76163-8_8 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

Inferred segmentations: ['BraTS-GLI-00001-000.nii.gz', 'BraTS-GLI-00001-001.nii.gz']

Advanced Usage¶

By default the algorithm that won the most recent challenge will be run on the first available GPU. This behavior and other options can be adapted, e.g.:

• Select a different algorithm from the available constants (Enum classes for each challenge) with the algorithm parameter
• Select a specific GPU if multiple are available with the cuda_decives parameter
• Force CPU execution with the force_cpuflag (will cause an exception for many algorithms since many do not support CPU execution, check our overview tables to find CPU capable algorithms)
• Add console logging with a desired log level
• Save the generated logs in a log file with the log_file parameter

In [4]:

from brats.utils.logging import add_console_handler, remove_console_handler

add_console_handler(level="INFO")  # Set the desired log level
segmenter = AdultGliomaPreTreatmentSegmenter(
    algorithm=AdultGliomaPreTreatmentAlgorithms.BraTS23_3,  # Use the 3rd placed algorithm of the Adult Glioma BraTS 2023 challenge
    cuda_devices="1",  # Select GPU device with ID 1
    force_cpu=False,  # default, could be set to True to force CPU
)

segmenter.infer_single(
    t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz",
    t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz",
    t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz",
    t2w=segmentation_subject_path / f"{subject}-t2w.nii.gz",
    output_file="segmentation.nii.gz",
    log_file="segmentation.log",  # Save the logs in a new filed called `segmentation.log`
)
remove_console_handler()  # Remove the console handler for subsequent runs

from brats.utils.logging import add_console_handler, remove_console_handler add_console_handler(level="INFO") # Set the desired log level segmenter = AdultGliomaPreTreatmentSegmenter( algorithm=AdultGliomaPreTreatmentAlgorithms.BraTS23_3, # Use the 3rd placed algorithm of the Adult Glioma BraTS 2023 challenge cuda_devices="1", # Select GPU device with ID 1 force_cpu=False, # default, could be set to True to force CPU ) segmenter.infer_single( t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz", t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz", t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz", t2w=segmentation_subject_path / f"{subject}-t2w.nii.gz", output_file="segmentation.nii.gz", log_file="segmentation.log", # Save the logs in a new filed called `segmentation.log` ) remove_console_handler() # Remove the console handler for subsequent runs

2025-07-25 16:11:44.728 | INFO     | brats.core.brats_algorithm:__init__:40 - Instantiated AdultGliomaPreTreatmentSegmenter with algorithm: BraTS23_3 by Fadillah Adamsyah Maani, et al.
2025-07-25 16:11:44.738 | INFO     | brats.utils.data_handling:add_log_file_handler:41 - Logging console logs and further debug information to: /home/marcelrosier/tutorials/BraTS/segmentation.log
2025-07-25 16:11:44.742 | INFO     | brats.core.brats_algorithm:_infer_single:147 - Performing single inference

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                                              BraTS Package | https://arxiv.org/abs/2506.13807             
------------------------------------------------------------+----------------------------------------------
 Challenge (Adult Glioma Segmentation (Pre Treatment) 2023) | https://arxiv.org/abs/2107.02314             
------------------------------------------------------------+----------------------------------------------
                Algorithm (Fadillah Adamsyah Maani, et al.) | https://doi.org/10.1007/978-3-031-76163-8_24 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

2025-07-25 16:11:44.791 | INFO     | brats.core.docker:_log_algorithm_info:342 - Running algorithm:  BraTS 2023 Adult Glioma Segmentation (Pre Treatment) [3rd place]
2025-07-25 16:11:45.058 | INFO     | brats.utils.zenodo:check_additional_files_path:62 - Found downloaded local additional_files: 11573315_v1.0.1
2025-07-25 16:11:45.060 | INFO     | brats.utils.zenodo:check_additional_files_path:75 - Latest additional files (11573315_v1.0.1) are already present.
2025-07-25 16:11:45.616 | INFO     | brats.core.docker:run_container:394 - Starting inference

Output()

2025-07-25 16:14:51.743 | INFO     | brats.core.docker:run_container:417 - Finished inference in 186.12 seconds
2025-07-25 16:14:51.745 | INFO     | brats.core.brats_algorithm:_infer_single:171 - Saved output to: /home/marcelrosier/tutorials/BraTS/segmentation.nii.gz

Algorithms from other Challenges¶

BraTS provides the algorithms from all available recent BraTS Challenges, i.e.:

• Adult Glioma Pre Treatment Segmentation
• Adult Glioma Post Treatment Segmentation
• BraTS-Africa Segmentation
• Meningioma Segmentation
• Brain Metastases Segmentation
• Pediatric Tumors Segmentation

The package provides a separate class and algorithm constants for each of the challenges.
The examples above were demonstrated using the class and constants of the Adult Glioma Pre Treatment Segmentation challenge.

In an identical way you can use:

• MeningiomaSegmenter class with MeningiomaAlgorithms
• PediatricSegmenter class with PediatricAlgorithms
• etc.

A full overview of all available algorithms can be found in the projects Readme here.

In [5]:

# e.g. for the Meningioma Algorithms
from brats import MeningiomaSegmenter
from brats.constants import MeningiomaAlgorithms

segmenter = MeningiomaSegmenter(
    algorithm=MeningiomaAlgorithms.BraTS23_2, cuda_devices="1"
)
segmenter.infer_batch(
    data_folder=segmentation_data_path, output_folder="men_output", log_file="test.log"
)

# e.g. for the Meningioma Algorithms from brats import MeningiomaSegmenter from brats.constants import MeningiomaAlgorithms segmenter = MeningiomaSegmenter( algorithm=MeningiomaAlgorithms.BraTS23_2, cuda_devices="1" ) segmenter.infer_batch( data_folder=segmentation_data_path, output_folder="men_output", log_file="test.log" )

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                            BraTS Package | https://arxiv.org/abs/2506.13807                   
------------------------------------------+----------------------------------------------------
 Challenge (Meningioma Segmentation 2023) | https://arxiv.org/abs/2305.07642                   
------------------------------------------+----------------------------------------------------
          Algorithm (Ziyan Huang, et al.) | https://doi.org/10.1007/978-3-031-76163-8_13       
------------------------------------------+----------------------------------------------------
                                  Dataset | https://www.nature.com/articles/s41597-024-03350-9 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

Inpainting¶

The Inpainting algorithms have a mostly identical interface except for the obvious change of input files.
Everything else remains the same.

In [6]:

from brats import Inpainter

inpainter = Inpainter()
inpainter.infer_single(
    t1n=inpainting_subject_path / f"{subject}-t1n-voided.nii.gz",
    mask=inpainting_subject_path / f"{subject}-mask.nii.gz",
    output_file="inpainting.nii.gz",
)

from brats import Inpainter inpainter = Inpainter() inpainter.infer_single( t1n=inpainting_subject_path / f"{subject}-t1n-voided.nii.gz", mask=inpainting_subject_path / f"{subject}-mask.nii.gz", output_file="inpainting.nii.gz", )

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                    BraTS Package | https://arxiv.org/abs/2506.13807             
----------------------------------+----------------------------------------------
      Challenge (Inpainting 2023) | https://arxiv.org/abs/2305.08992             
----------------------------------+----------------------------------------------
 Algorithm (Juexin Zhang, et al.) | https://doi.org/10.1007/978-3-031-76163-8_21 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

Visualize Results¶

In [7]:

utils.visualize_inpainting(
    t1n_voided=inpainting_subject_path / f"{subject}-t1n-voided.nii.gz",
    prediction="inpainting.nii.gz",
)

utils.visualize_inpainting( t1n_voided=inpainting_subject_path / f"{subject}-t1n-voided.nii.gz", prediction="inpainting.nii.gz", )

Batch inference¶

Batch inference can be used in the same way, but expects an adapted structure of the data folder:

data_folder
┣ A
┃ ┣ A-t1n-voided.nii.gz
┃ ┣ A-mask.nii.gz
┣ B
┃ ┣ B-t1n-voided.nii.gz
┃ ┣ ...

In [8]:

output_path = Path("inpainting_batch_out")

inpainter = Inpainter()
inpainter.infer_batch(
    data_folder=inpainting_data_path,
    output_folder=output_path,
)

print([path.name for path in output_path.iterdir()])

output_path = Path("inpainting_batch_out") inpainter = Inpainter() inpainter.infer_batch( data_folder=inpainting_data_path, output_folder=output_path, ) print([path.name for path in output_path.iterdir()])

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                    BraTS Package | https://arxiv.org/abs/2506.13807             
----------------------------------+----------------------------------------------
      Challenge (Inpainting 2023) | https://arxiv.org/abs/2305.08992             
----------------------------------+----------------------------------------------
 Algorithm (Juexin Zhang, et al.) | https://doi.org/10.1007/978-3-031-76163-8_21 

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

['BraTS-GLI-00001-000.nii.gz']

Missing MRI Synthesis (BraSyn)¶

MissingMRI algorithms allow to synthesize a missing modality image from the three others (any combination is possible).
Below we demonstrate how to generate a t2w image from t1c, t1n and t2f.

In [9]:

from brats import MissingMRI

missing_mri = MissingMRI()
missing_mri.infer_single(
    t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz",
    t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz",
    t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz",
    output_file="synthesized_t2w.nii.gz",
)
# .infer_batch() works identical to the segmentation/ inpainting batch infer methods

from brats import MissingMRI missing_mri = MissingMRI() missing_mri.infer_single( t1c=segmentation_subject_path / f"{subject}-t1c.nii.gz", t1n=segmentation_subject_path / f"{subject}-t1n.nii.gz", t2f=segmentation_subject_path / f"{subject}-t2f.nii.gz", output_file="synthesized_t2w.nii.gz", ) # .infer_batch() works identical to the segmentation/ inpainting batch infer methods

──────────────────────────────────────────────── Citation Reminder ────────────────────────────────────────────────

Please support our development by citing the relevant manuscripts for the used algorithm:

                                           BraTS Package | https://arxiv.org/abs/2506.13807 
---------------------------------------------------------+----------------------------------
 Challenge (BraTS MRI Synthesis Challenge (BraSyn) 2024) | https://arxiv.org/abs/2305.09011 
---------------------------------------------------------+----------------------------------
     Algorithm (Jihoon Cho, Seunghyuck Park, Jinah Park) | N/A                              

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Output()

In [10]:

utils.visualize_missing_mri_t2w(
    synthesized_t2w="synthesized_t2w.nii.gz", data_folder=missing_mri_path
)

utils.visualize_missing_mri_t2w( synthesized_t2w="synthesized_t2w.nii.gz", data_folder=missing_mri_path )