raidionicsrads 1.3.2
Raidionics reporting and data system backend (RADS)
License: BSD 2-Clause
Requires Python: >=3.9

# Raidionics processing backend for performing segmentation and computation of standardized report (RADS)

[![License](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause)
[![](https://img.shields.io/badge/python-3.9|3.10|3.11|3.12|3.13-blue.svg)](https://www.python.org/downloads/)
[![Paper](https://zenodo.org/badge/DOI/10.3389/fneur.2022.932219.svg)](https://www.frontiersin.org/articles/10.3389/fneur.2022.932219/full)
[![PyPI version](https://img.shields.io/pypi/v/raidionicsrads.svg)](https://pypi.org/project/raidionicsrads/)
[![codecov](https://codecov.io/gh/dbouget/raidionics_rads_lib/branch/master/graph/badge.svg?token=ZSPQVR7RKX)](https://codecov.io/gh/dbouget/raidionics_rads_lib)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/gist/dbouget/ae5f318af4826ef8bf5ff0f27e7c0817/01_run_simple_segmentation.ipynb)
<a target="_blank" href="https://huggingface.co/spaces/dbouget/raidionics"><img src="https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-yellow.svg"></a>

The code corresponds to the Raidionics backend for running processing pipelines over MRI/CT scans. The segmentation of
a few organs or tumor types, as well as the generation of standardized reports are included.  
The module can either be used as a Python library, as CLI, or as Docker container.

## [Installation](https://github.com/dbouget/raidionics_rads_lib#installation)

```
pip install raidionicsrads
or
pip install git+https://github.com/dbouget/raidionics_rads_lib.git
```

## [Getting started](https://github.com/dbouget/raidionics_rads_lib#getting-started)

### [Notebooks](https://github.com/dbouget/raidionics_rads_lib#notebooks)

Below are Jupyter Notebooks including different examples on how to get started with the segmentation and reporting tasks,
either over the brain or mediastinal area.

<div style="display: flex;">
  <div style="flex: 1; margin-right: 20px;">

| Notebook                       | Clinical target     | Colab                                                                                                                                                                                                                                            | GitHub                                                                                                                                                                                              |
|--------------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Preoperative Segmentation**  | :brain: Neuro       | <a href="https://colab.research.google.com/gist/dbouget/ae5f318af4826ef8bf5ff0f27e7c0817/01_run_simple_segmentation.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>        | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/notebooks/01_run_simple_segmentation.ipynb)        |
| **Preoperative Segmentation**  | :lungs: Mediastinum | <a href="https://colab.research.google.com/gist/dbouget/b88aa64b6a87f85a6b644ab4bcf65560/05_run_segmentation_mediastinum.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>   | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/notebooks/05_run_segmentation_mediastinum.ipynb)   |
| **Postoperative Segmentation** | :brain: Neuro       | <a href="https://colab.research.google.com/gist/dbouget/094c24f3e67deae6a1424a399cb7dcd7/03_run_postoperative_segmentation.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a> | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/notebooks/03_run_postoperative_segmentation.ipynb) |
| **Simple Reporting**           | :brain: Neuro       | <a href="https://colab.research.google.com/gist/dbouget/68a50c14b1805254b4eff6fb2e3b8fe5/02_run_simple_reporting.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>           | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/notebooks/02_run_simple_reporting.ipynb)           |
| **Surgical Reporting**         | :brain: Neuro       | <a href="https://colab.research.google.com/gist/dbouget/19800ffd443ed0f27724f28b100533ce/04_run_surgical_reporting.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>         | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/notebooks/04_run_surgical_reporting.ipynb)         |
| **Batch processing**           | :brain: Neuro       | -                                                                                                                                                                                                                                                | [![View on GitHub](https://img.shields.io/badge/View%20on%20GitHub-blue?logo=github)](https://github.com/dbouget/raidionics_rads_lib/blob/master/tests/batch_iterative_process_example.py)          |

  </div>
</div>

<details>
<summary>

### [CLI](https://github.com/dbouget/raidionics_rads_lib#cli)
</summary>

```
raidionicsrads -c CONFIG (-v debug)
```

CONFIG should point to a configuration file (*.ini), specifying all runtime parameters,
according to the pattern from [**blank_main_config.ini**](https://github.com/dbouget/raidionics-rads-lib/blob/master/blank_main_config.ini).
</details>

<details>
<summary>

### [Python module](https://github.com/dbouget/raidionics_rads_lib#python-module)
</summary>

```
from raidionicsrads.compute import run_rads
run_rads(config_filename="/path/to/main_config.ini")
```

</details>

<details>
<summary>

### [Docker](https://github.com/dbouget/raidionics_rads_lib#docker)
</summary>

When calling Docker images, the --user flag must be properly used in order for the folders and files created inside
the container to inherit the proper read/write permissions. The user ID is retrieved on-the-fly in the following
examples, but it can be given in a more hard-coded fashion if known by the user.

:warning: The Docker image can only perform inference using the CPU, there is no GPU support at this stage.
```
docker pull dbouget/raidionics-rads:v1.3-py39-cpu
```

For opening the Docker image and interacting with it, run:  
```
docker run --entrypoint /bin/bash -v /home/<username>/<resources_path>:/workspace/resources -t -i --runtime=nvidia --network=host --ipc=host --user $(id -u) dbouget/raidionics-rads:v1.3-py39-cpu
```

The `/home/<username>/<resources_path>` before the column sign has to be changed to match a directory on your local 
machine containing the data to expose to the docker image. Namely, it must contain folder(s) with images you want to 
run inference on, as long as a folder with the trained models to use, and a destination folder where the results will 
be placed.

For launching the Docker image as a CLI, run:  
```
docker run -v /home/<username>/<resources_path>:/workspace/resources -t -i --runtime=nvidia --network=host --ipc=host --user $(id -u) dbouget/raidionics-rads:v1.3-py39-cpu -c /workspace/resources/<path>/<to>/main_config.ini -v <verbose>
```

The `<path>/<to>/main_config.ini` must point to a valid configuration file on your machine, as a relative path to the `/home/<username>/<resources_path>` described above.
For example, if the file is located on my machine under `/home/myuser/Data/RADS/main_config.ini`, 
and that `/home/myuser/Data` is the mounted resources partition mounted on the Docker image, the new relative path will be `RADS/main_config.ini`.  
The `<verbose>` level can be selected from [debug, info, warning, error].

</details>

## [How to cite](https://github.com/dbouget/raidionics_rads_lib#how-to-cite)
If you are using Raidionics in your research, please cite the following references.

The final software including updated performance metrics for preoperative tumors and introducing postoperative tumor segmentation:
```
@article{bouget2023raidionics,
    author = {Bouget, David and Alsinan, Demah and Gaitan, Valeria and Holden Helland, Ragnhild and Pedersen, André and Solheim, Ole and Reinertsen, Ingerid},
    year = {2023},
    month = {09},
    pages = {},
    title = {Raidionics: an open software for pre-and postoperative central nervous system tumor segmentation and standardized reporting},
    volume = {13},
    journal = {Scientific Reports},
    doi = {10.1038/s41598-023-42048-7},
}
```

For the preliminary preoperative tumor segmentation validation and software features:
```
@article{bouget2022preoptumorseg,
    title={Preoperative Brain Tumor Imaging: Models and Software for Segmentation and Standardized Reporting},
    author={Bouget, David and Pedersen, André and Jakola, Asgeir S. and Kavouridis, Vasileios and Emblem, Kyrre E. and Eijgelaar, Roelant S. and Kommers, Ivar and Ardon, Hilko and Barkhof, Frederik and Bello, Lorenzo and Berger, Mitchel S. and Conti Nibali, Marco and Furtner, Julia and Hervey-Jumper, Shawn and Idema, Albert J. S. and Kiesel, Barbara and Kloet, Alfred and Mandonnet, Emmanuel and Müller, Domenique M. J. and Robe, Pierre A. and Rossi, Marco and Sciortino, Tommaso and Van den Brink, Wimar A. and Wagemakers, Michiel and Widhalm, Georg and Witte, Marnix G. and Zwinderman, Aeilko H. and De Witt Hamer, Philip C. and Solheim, Ole and Reinertsen, Ingerid},
    journal={Frontiers in Neurology},
    volume={13},
    year={2022},
    url={https://www.frontiersin.org/articles/10.3389/fneur.2022.932219},
    doi={10.3389/fneur.2022.932219},
    issn={1664-2295}
}
```

<details>
<summary>

## [Models](https://github.com/dbouget/raidionics_rads_lib#models)
</summary>

The trained models are automatically downloaded when running Raidionics or Raidionics-Slicer.
Alternatively, all existing Raidionics models can be browsed [here](https://github.com/raidionics/Raidionics-models/releases/tag/v1.3.0-rc) directly.
</details>