AURORA

Deep learning models for brain cancer metastasis segmentation based on the manuscripts:

• Identifying core MRI sequences for reliable automatic brain metastasis segmentation
• Development and external validation of an MRI-based neural network for brain metastasis segmentation in the AURORA multicenter study

Installation

With a Python 3.8+ environment, you can install brainles_aurora directly from pypi.org:

pip install brainles-aurora

Recommended Environment

• CUDA 11.4+ (https://developer.nvidia.com/cuda-toolkit)
• Python 3.8+
• GPU with CUDA support and at least 6GB of VRAM

Usage

BrainLes features Jupyter Notebook tutorials with usage instructions.

A minimal example could look like this:

    from brainles_aurora.inferer import AuroraInferer, AuroraInfererConfig

    config = AuroraInfererConfig(
        tta=False, cuda_devices="4"
    )  # disable tta for faster inference in this showcase
    inferer = AuroraInferer(config=config)

    inferer.infer(
        t1="t1.nii.gz",
        t1c="t1c.nii.gz",
        t2="t2.nii.gz",
        fla="fla.nii.gz",
        segmentation_file="segmentation.nii.gz",
        whole_tumor_unbinarized_floats_file="whole_network.nii.gz",
        metastasis_unbinarized_floats_file="metastasis_network.nii.gz",
        log_file="aurora.log",
    )

Note

If you're interested in the AURORA package, the Brain Metastases Segmentation may also be of interest.

Citation

Please support our development by citing the following manuscripts:

Identifying core MRI sequences for reliable automatic brain metastasis segmentation

@article{buchner2023identifying,
  title={Identifying core MRI sequences for reliable automatic brain metastasis segmentation},
  author={Buchner, Josef A and Peeken, Jan C and Etzel, Lucas and Ezhov, Ivan and Mayinger, Michael and Christ, Sebastian M and Brunner, Thomas B and Wittig, Andrea and Menze, Bjoern H and Zimmer, Claus and others},
  journal={Radiotherapy and Oncology},
  volume={188},
  pages={109901},
  year={2023},
  publisher={Elsevier}
}

also consider citing the original AURORA manuscript, especially when using the vanilla model (all 4 modalities as input):

Development and external validation of an MRI-based neural network for brain metastasis segmentation in the AURORA multicenter study

@article{buchner2022development,
  title={Development and external validation of an MRI-based neural network for brain metastasis segmentation in the AURORA multicenter study},
  author={Buchner, Josef A and Kofler, Florian and Etzel, Lucas and Mayinger, Michael and Christ, Sebastian M and Brunner, Thomas B and Wittig, Andrea and Menze, Bj{\"o}rn and Zimmer, Claus and Meyer, Bernhard and others},
  journal={Radiotherapy and Oncology},
  year={2022},
  publisher={Elsevier}
}

Contact / Feedback / Questions

If possible please open a GitHub issue here.

For inquiries not suitable for GitHub issues:

Florian Kofler florian.kofler [at] tum.de

Josef Buchner j.buchner [at] tum.de

---

Using AURORA in Docker (local workflow)

This repository also includes a Docker workflow for reproducible inference runs.

1) Build the Docker image

From the brain_metastasesModels_benchmark/AURORA directory:

docker build -f Dockerfile.aurora -t brainmet-aurora:latest .

2) Run the container

Mount both this benchmark repository and your dataset root. Example:

docker run --gpus all --rm -it \
  -v /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/brain_metastasesModels_benchmark:/workspace \
  -v /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/Medical_Images_Public:/data \
  brainmet-aurora:latest

3) Run inference script inside the container

Run the batch script with default output root: /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/brain_metastasesModels_benchmark/aurora_outputs.

python /workspace/AURORA/run_inference_test.py \
  --dataset-dir /data/Brain-Mets-Lung-MRI-Path-Segs_Preprocessed356_new

Optional examples:

# Run first 5 patients only
python /workspace/AURORA/run_inference_test.py \
  --dataset-dir /data/Brain-Mets-Lung-MRI-Path-Segs_Preprocessed356_new \
  --max-patients 5

# Run specific patients only
python /workspace/AURORA/run_inference_test.py \
  --dataset-dir /data/Brain-Mets-Lung-MRI-Path-Segs_Preprocessed356_new \
  --patient YG_0AXGKD8AFJGS \
  --patient YG_0IBUXTBINCD9

4) Output layout

Predictions are written to:

/mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/brain_metastasesModels_benchmark/aurora_outputs/
  <dataset_name>/
    <patient_id>/
      <patient_id>_segmentation.nii.gz
      <patient_id>_whole_tumor.nii.gz
      <patient_id>_metastasis.nii.gz
      <patient_id>_aurora.log

This preserves dataset and patient directory structure in the output tree.

5) Start container, then docker exec into bash

If you prefer to keep one container running and enter/exit a shell multiple times:

# Start container in background
docker run --gpus all -d \
  -v /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/brain_metastasesModels_benchmark:/workspace \
  -v /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/Medical_Images_Public:/data \
  --name aurora-dev \
  brainmet-aurora:latest \
  sleep infinity

# Enter bash in the running container
docker exec -it aurora-dev /bin/bash

# Run inference inside the container
python /workspace/AURORA/run_inference_test.py \
  --dataset-dir /data/Brain-Mets-Lung-MRI-Path-Segs_Preprocessed356_new

When finished:

docker stop aurora-dev
docker rm aurora-dev

6) Important note about output visibility on host

When running inside Docker, use an output path under a mounted volume (for example /workspace/aurora_outputs). Otherwise, outputs may be saved only inside the container filesystem and not immediately visible on the host.

Recommended command:

python /workspace/AURORA/run_inference_test.py \
  --dataset-dir /data/Brain-Mets-Lung-MRI-Path-Segs_Preprocessed356_new \
  --output-root /workspace/aurora_outputs

With this setup, outputs are visible on the host at: /mnt/d/A1_RainSun_20240916/1-UWMadison/IDiA-Lab/brain_metastasesModels_benchmark/aurora_outputs.