Skip to content

Commit 8b847f7

Browse files
MarcelRosierMarcelRosier
committed
Add basic tutorial for BraTS
1 parent 4279eb2 commit 8b847f7

2 files changed

Lines changed: 133 additions & 90 deletions

File tree

‎BraTS/tutorial.ipynb‎

Lines changed: 124 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
"outputs": [],
3232
"source": [
3333
"# Installations\n",
34-
"!pip install brats matplotlib > /dev/null\n",
34+
"!pip install brats matplotlib ipywidgets > /dev/null\n",
3535
"\n",
3636
"%load_ext autoreload\n",
3737
"%autoreload 2"
@@ -47,7 +47,7 @@
4747
"Otherwise you can follow and execute the tutorial on your browser.\n",
4848
"In order to start working on the notebook, click on the following button, this will open this page in the Colab environment and you will be able to execute the code on your own (*Google account required*).\n",
4949
"\n",
50-
"<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/AURORA/tutorial.ipynb\">\n",
50+
"<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/BraTS/tutorial.ipynb\">\n",
5151
" <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
5252
"</a>\n",
5353
"\n",
@@ -105,7 +105,7 @@
105105
"cell_type": "markdown",
106106
"metadata": {},
107107
"source": [
108-
"### Imports"
108+
"## Imports"
109109
]
110110
},
111111
{
@@ -114,6 +114,7 @@
114114
"metadata": {},
115115
"outputs": [],
116116
"source": [
117+
"from pathlib import Path\n",
117118
"from brats import AdultGliomaSegmenter\n",
118119
"from brats.constants import AdultGliomaAlgorithms\n",
119120
"import utils # local file"
@@ -146,21 +147,24 @@
146147
"metadata": {},
147148
"outputs": [],
148149
"source": [
149-
"utils.visualize_data(f\"{BASE_PATH}/data\")"
150+
"subject = \"BraTS-GLI-00001-000\"\n",
151+
"data_path = Path(BASE_PATH) / \"data\"\n",
152+
"subject_path = data_path / subject\n",
153+
"utils.visualize_data(data_path, subject_id=subject)"
150154
]
151155
},
152156
{
153157
"cell_type": "markdown",
154158
"metadata": {},
155159
"source": [
156-
"## Using AURORA"
160+
"## Using BraTS"
157161
]
158162
},
159163
{
160164
"cell_type": "markdown",
161165
"metadata": {},
162166
"source": [
163-
"### Minimal example using default settings and only T1c as input"
167+
"### Minimal example using default settings"
164168
]
165169
},
166170
{
@@ -169,55 +173,24 @@
169173
"metadata": {},
170174
"outputs": [],
171175
"source": [
172-
"# We first need to create an instance of the AuroraInfererConfig class,\n",
173-
"# which will hold the configuration for the inferer.\n",
174-
"# We can then create an instance of the AuroraInferer class, which will be used to perform the inference.\n",
175-
"\n",
176-
"config = AuroraInfererConfig(\n",
177-
" tta=False,\n",
178-
" # we disable test time augmentations for a quick demo\n",
179-
" # should be set to True for better results\n",
180-
" sliding_window_batch_size=4,\n",
181-
" # The batch size used for the sliding window inference\n",
182-
" # decrease if you run out of memory\n",
183-
" # warning: too small batches might lead to unstable results\n",
184-
" cuda_devices=\"0\", # optional, if you have multiple GPUs you can specify which one to use\n",
185-
" device=\"cpu\", # uncomment this line to force-use CPU\n",
186-
")\n",
187-
"\n",
188-
"\n",
189-
"# Now that we have the configuration we can create an instance of the AuroraInferer class.\n",
190-
"# This class will be used to perform the inference. We can then call the infer method to perform the inference.\n",
191-
"inferer = AuroraInferer(config=config)\n",
192-
"\n",
193-
"if torch.cuda.is_available() == False and colabFlag == True:\n",
194-
" raise RuntimeWarning(\n",
195-
" \"You are not using any GPU in Colab! Go to 'Runtime'->'Change Runtime type' to select GPU usage!\"\n",
196-
" )\n",
197-
"\n",
198-
"# The infer method takes the path to the T1c MRI file and the path to the output segmentation file as arguments.\n",
199-
"# The output segmentation file will be created by the infer method and\n",
200-
"# will contain the segmentation of the input T1c MRI.\n",
201-
"\n",
202-
"# The example below shows how to perform the inference using a T1c MRI file:\n",
203-
"_ = inferer.infer(\n",
204-
" t1c=f\"{BASE_PATH}/data/t1c.nii.gz\",\n",
205-
" segmentation_file=f\"{BASE_PATH}/output/t1c_segmentation.nii.gz\",\n",
206-
")\n",
207-
"\n",
208-
"# IMPORTANT: If this cell produces an OutOfMemoryError, you might not have enough VRAM (minimum 8GB).\n",
209-
"# Try using the CPU instead by setting \"useGPU\" to False above"
176+
"segmenter = AdultGliomaSegmenter()\n",
177+
"segmenter.infer_single(\n",
178+
" t1c=subject_path / f\"{subject}-t1c.nii.gz\",\n",
179+
" t1n=subject_path / f\"{subject}-t1n.nii.gz\",\n",
180+
" t2f=subject_path / f\"{subject}-t2f.nii.gz\",\n",
181+
" t2w=subject_path / f\"{subject}-t2w.nii.gz\",\n",
182+
" output_file=\"segmentation.nii.gz\",\n",
183+
")"
210184
]
211185
},
212186
{
213187
"cell_type": "markdown",
214188
"metadata": {},
215189
"source": [
216-
"## Visualize results\n",
190+
"### Visualize results\n",
217191
"\n",
218192
"The segementation comprise of the\n",
219-
"- **metastasis label** (in blue), consiting of contrast-enhancing metastasis and necrosis\n",
220-
"- T2-FLAIR hyperintense **edema label** (in red) \n"
193+
"TODO\n"
221194
]
222195
},
223196
{
@@ -227,74 +200,139 @@
227200
"outputs": [],
228201
"source": [
229202
"utils.visualize_segmentation(\n",
230-
" modality_file=f\"{BASE_PATH}/data/t1c.nii.gz\",\n",
231-
" segmentation_file=f\"{BASE_PATH}/output/t1c_segmentation.nii.gz\",\n",
203+
" modality_file=subject_path / f\"{subject}-t1c.nii.gz\",\n",
204+
" segmentation_file=\"segmentation.nii.gz\"\n",
232205
")"
233206
]
234207
},
235208
{
236209
"cell_type": "markdown",
237210
"metadata": {},
238211
"source": [
239-
"### Multiple input modalities and other available outputs"
212+
"## Batch processing\n",
213+
"\n",
214+
"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.\n",
215+
"Each of the available classes provides methods for both: \n",
216+
"- `.infer_single(...)` that takes in the paths to the required input modalities and a path to store the result\n",
217+
"- `.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"
240218
]
241219
},
242220
{
243221
"cell_type": "markdown",
244222
"metadata": {},
245223
"source": [
246-
"AURORA also supports different combinations of multi-modal MRI files [(see manuscript)](https://www.sciencedirect.com/science/article/pii/S016781402389795X). It will automatically select a suitable model depending on the inputs supplied.\n",
247-
"\n",
248-
"- Any of the following combination of sequences can be supplied: \n",
249-
" - T1-CE only\n",
250-
" - T1 only\n",
251-
" - T2-FLAIR only\n",
252-
" - T1-CE + T2-FLAIR\n",
253-
" - T1-CE + T1\n",
254-
" - T1-CE + T1 + T2-FLAIR\n",
255-
" - T1-CE + T1 + T2 + T2-FLAIR \n",
256-
" \n",
257-
"- For the last combination (with all 4 sequences), the [(vanilla model)](https://www.sciencedirect.com/science/article/pii/S0167814022045625) can also be used.\n",
224+
"#### The example below shows how to perform a batch inference\n",
225+
"The sets of subject inputs need to be stored in a specific structure to be recognized by the package:\n",
226+
"```\n",
227+
"data_folder\n",
228+
"┣ A\n",
229+
"┃ ┣ A-t1c.nii.gz\n",
230+
"┃ ┣ A-t1n.nii.gz\n",
231+
"┃ ┣ A-t2f.nii.gz\n",
232+
"┃ ┗ A-t2w.nii.gz\n",
233+
"┣ B\n",
234+
"┃ ┣ B-t1c.nii.gz\n",
235+
"┃ ┣ ...\n",
236+
"```"
237+
]
238+
},
239+
{
240+
"cell_type": "code",
241+
"execution_count": null,
242+
"metadata": {
243+
"scrolled": true
244+
},
245+
"outputs": [],
246+
"source": [
247+
"output_path = Path(\"outputs\")\n",
258248
"\n",
259-
"- Instead of only saving the final output consisting of one file with 2 labels, additional files with labels for the whole lesion (metastasis + edema) or the metastasis only can also be saved.\n",
249+
"segmenter = AdultGliomaSegmenter(cuda_devices=\"4\")\n",
250+
"segmenter.infer_batch(\n",
251+
" data_folder=data_path,\n",
252+
" output_folder=output_path,\n",
253+
")\n",
260254
"\n",
261-
"- Test-time augmentation can be enabled (tta parameter in config, default = True). Segmentation with TTA will take around 10 times longer than without TTA.\n",
262-
"\n"
255+
"print([path.name for path in output_path.iterdir()])"
256+
]
257+
},
258+
{
259+
"cell_type": "markdown",
260+
"metadata": {},
261+
"source": [
262+
"## Advanced Usage"
263263
]
264264
},
265265
{
266266
"cell_type": "markdown",
267267
"metadata": {},
268268
"source": [
269-
"#### The example below shows how to perform the inference using multi-modal inputs.\n",
270-
"*(This may take a while)*"
269+
"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.:\n",
270+
"- Select a different algorithm from the available constants (Enum classes for each challenge) with the `algorithm` parameter\n",
271+
"- Select a specific GPU if multiple are available with the `cuda_decives` parameter\n",
272+
"- Force CPU execution with the `force_cpu`flag (will cause an exception for many algorithms since many do not support CPU execution)\n",
273+
"- Save the generated logs in a log file with the `log_file` parameter"
271274
]
272275
},
273276
{
274277
"cell_type": "code",
275278
"execution_count": null,
276-
"metadata": {
277-
"scrolled": true
278-
},
279+
"metadata": {},
279280
"outputs": [],
280281
"source": [
281-
"# Instantiate the AuroraInferer\n",
282-
"inferer = AuroraInferer()\n",
282+
"segmenter = AdultGliomaSegmenter(\n",
283+
" algorithm=AdultGliomaAlgorithms.BraTS23_3, # Use the 3rd placed algorithm of the Adult Glioma BraTS 2023 challenge\n",
284+
" cuda_devices=\"4\", # Select GPU device with ID 4\n",
285+
" force_cpu=False, # default, could be set to True to force CPU\n",
286+
")\n",
283287
"\n",
284-
"inferer = AuroraInferer(config=config)\n",
288+
"segmenter.infer_single(\n",
289+
" t1c=subject_path / f\"{subject}-t1c.nii.gz\",\n",
290+
" t1n=subject_path / f\"{subject}-t1n.nii.gz\",\n",
291+
" t2f=subject_path / f\"{subject}-t2f.nii.gz\",\n",
292+
" t2w=subject_path / f\"{subject}-t2w.nii.gz\",\n",
293+
" output_file=\"segmentation.nii.gz\",\n",
294+
" log_file=\"segmentation.log\", # Save the logs in a new filed called `segmentation.log`\n",
295+
")"
296+
]
297+
},
298+
{
299+
"cell_type": "markdown",
300+
"metadata": {},
301+
"source": [
302+
"## Algorithms from other Challenges\n",
303+
"\n",
304+
"BraTS provides the algorithms from all available recent BraTS Challenges, i.e.:\n",
305+
"- Adult Glioma Segmentation\n",
306+
"- BraTS-Africa Segmentation\n",
307+
"- Meningioma Segmentation\n",
308+
"- Brain Metastases Segmentation\n",
309+
"- Pediatric Tumors Segmentation\n",
310+
"- Inpainting\n",
311+
"\n",
312+
"The package provides a separate class and algorithm constants for each of the challenges.<br>\n",
313+
"The examples above were demonstrated using the class and constants of the Adult Glioma Segmentation challenge.\n",
314+
"\n",
315+
"In an identical way you can use:\n",
316+
"- `MeningiomaSegmenter` class with `MeningiomaAlgorithms`\n",
317+
"- `PediatricSegmenter` class with `PediatricAlgorithms`\n",
318+
"- etc."
319+
]
320+
},
321+
{
322+
"cell_type": "code",
323+
"execution_count": null,
324+
"metadata": {},
325+
"outputs": [],
326+
"source": [
327+
"# e.g. for the Meningioma Algorithms\n",
328+
"from brats import MeningiomaSegmenter\n",
329+
"from brats.constants import MeningiomaAlgorithms\n",
285330
"\n",
286-
"# Use all four input modalities,we also create other outputs and a custom log file\n",
287-
"_ = inferer.infer(\n",
288-
" t1=f\"{BASE_PATH}/data/t1.nii.gz\",\n",
289-
" t1c=f\"{BASE_PATH}/data/t1c.nii.gz\",\n",
290-
" t2=f\"{BASE_PATH}/data/t2.nii.gz\",\n",
291-
" fla=f\"{BASE_PATH}/data/flair.nii.gz\",\n",
292-
" segmentation_file=f\"{BASE_PATH}/output/multi-modal_segmentation.nii.gz\",\n",
293-
" # The unbinarized network outputs for the whole tumor channel (edema + enhancing tumor core + necrosis) channel\n",
294-
" whole_tumor_unbinarized_floats_file=f\"{BASE_PATH}/output/whole_tumor_unbinarized_floats.nii.gz\",\n",
295-
" # The unbinarized network outputs for the metastasis (tumor core) channel\n",
296-
" metastasis_unbinarized_floats_file=f\"{BASE_PATH}/output/metastasis_unbinarized_floats.nii.gz\",\n",
297-
" log_file=f\"{BASE_PATH}/output/custom_logfile.log\",\n",
331+
"segmenter = MeningiomaSegmenter(\n",
332+
" algorithm=MeningiomaAlgorithms.BraTS23_2, cuda_devices=\"4\"\n",
333+
")\n",
334+
"segmenter.infer_batch(\n",
335+
" data_folder=data_path, output_folder=output_path, log_file=\"test.log\"\n",
298336
")"
299337
]
300338
}
@@ -315,7 +353,7 @@
315353
"name": "python",
316354
"nbconvert_exporter": "python",
317355
"pygments_lexer": "ipython3",
318-
"version": "3.10.13"
356+
"version": "3.8.10"
319357
}
320358
},
321359
"nbformat": 4,

‎BraTS/utils.py‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
import os
1+
from pathlib import Path
22
import matplotlib.pyplot as plt
33
import nibabel as nib
44

55
DATA_FOLDER = "data"
66

77

8-
def visualize_data(data_folder: str = DATA_FOLDER, slice_index: int = 75):
8+
def visualize_data(
9+
data_folder: str = DATA_FOLDER,
10+
subject_id: str = "BraTS-GLI-00001-000",
11+
slice_index: int = 75,
12+
):
913
"""Visualize the MRI modalities for a given slice index
1014
1115
Args:
@@ -14,9 +18,10 @@ def visualize_data(data_folder: str = DATA_FOLDER, slice_index: int = 75):
1418
"""
1519
_, axes = plt.subplots(1, 4, figsize=(12, 10))
1620

17-
modalities = ["t1", "t1c", "t2", "flair"]
21+
subject_path = Path(data_folder) / subject_id
22+
modalities = ["t1n", "t1c", "t2f", "t2w"]
1823
for i, mod in enumerate(modalities):
19-
modality_file = os.path.join(data_folder, f"{mod}.nii.gz")
24+
modality_file = subject_path / f"{subject_id}-{mod}.nii.gz"
2025
modality_np = nib.load(modality_file).get_fdata().transpose(2, 1, 0)
2126
axes[i].set_title(mod)
2227
axes[i].imshow(modality_np[slice_index, :, :], cmap="gray")

0 commit comments

Comments
 (0)