+
+ 
+
+
A Python package for radiomics and dosiomics feature extraction.
-
MEDiml: MEDical Image analysis with Machine Learning | The package
-
-
+
+
+
+
A Python package for radiomics and dosiomics feature extraction.
-
+ 
- 📖 Documentation
+ 
Table of Contents
+ * [Introduction](#introduction)
+ * [Installation](#installation)
+ * [Using MEDiml](#using-mediml)
+ * [Tutorials](#tutorials)
+ * [IBSI Standardization](#ibsi-standardization)
+ * [Getting help](#getting-help)
+ * [Contributing](#contributing)
+ * [Acknowledgement](#acknowledgement)
+ * [Citation](#citation)
+ * [License](#license)
-
+## 
Introduction
+MEDiml-pkg is an open-source Python package that can be used for processing multi-modal medical images (MRI, CT or PET) and for extracting their radiomic features. It is also the computational engine behind [MEDiml-app](https://www.mediml.app/), the desktop application for conducting radiomics workflows without writing code. This package is meant to facilitate the processing of medical images and the subsequent computation of all types of radiomic features whilst maintaining the reproducibility of analyses. This package has been standardised with the [IBSI](https://theibsi.github.io/) norms.
-## 2. Installation
+See the [workflow figure at the top](#package-workflow) for a step-by-step overview of the package, from medical image datasets and preprocessing to radiomic feature extraction and machine learning.
+
+## 
Installation
### Python installation
+
The MEDiml package requires *Python 3.8*, *3.9* or *3.10*. If you don't have it installed on your machine, follow the instructions [here](https://github.com/MEDomicsLab/MEDiml-pkg/blob/main/python.md) to install it.
### Package installation
+
You can easily install the ``MEDiml`` package from PyPI using:
```
pip install MEDiml
@@ -62,10 +70,12 @@ If your uv project uses Python 3.11 or newer, create one for Python 3.10 instead
For more installation options (Conda, Poetry...) check out the [installation documentation](https://mediml.readthedocs.io/en/latest/Installation.html).
-## 3. Using MEDiml
+## 
Using MEDiml
+
MEDiml can be used either as a command line tool for batch radiomics extraction, or as a Python package that you import directly into your own scripts and notebooks for finer-grained control over the processing and feature extraction pipeline.
-### 3.1 Using MEDiml through the command line
+### Using MEDiml through the command line
+
After installation, you can launch radiomics extraction directly from the terminal:
```bash
@@ -94,7 +104,8 @@ The command wraps the existing `BatchExtractor` workflow and selects the appropr
| `--n-batch` | No | Number of CPU cores to use for extraction. Defaults to `4`. |
| `--skip-existing` | No | Skip scans whose features already exist in the output folder. |
-### 3.2 Using MEDiml through code
+### Using MEDiml through code
+
```python
import os
import pickle
@@ -133,35 +144,34 @@ med_obj.save_radiomics(
)
```
-## 4. Tutorials
+## 
Tutorials
We have created many [tutorial notebooks](https://github.com/MEDomicsLab/MEDiml-pkg/tree/main/notebooks) to assist you in learning how to use the different parts of the package. More details can be found in the [documentation](https://mediml.readthedocs.io/en/latest/tutorials.html).
-## 5. IBSI Standardization
+## 
IBSI Standardization
+
The image biomarker standardization initiative ([IBSI](https://theibsi.github.io)) is an independent international collaboration that aims to standardize the extraction of image biomarkers from acquired imaging. The IBSI therefore seeks to provide image biomarker nomenclature and definitions, benchmark datasets, and benchmark values to verify image processing and image biomarker calculations, as well as reporting guidelines, for high-throughput image analysis. We participate in this collaboration with our package to make sure it respects international nomenclatures and definitions. The participation was separated into two chapters:
- - ### IBSI Chapter 1
- [The IBSI chapter 1](https://theibsi.github.io/ibsi1/) is dedicated to the standardization of commonly used radiomic features. It was initiated in September 2016 and reached completion in March 2020. We have created two [jupyter notebooks](https://github.com/MEDomicsLab/MEDiml-pkg/tree/main/notebooks/ibsi) for each phase of the chapter and made them available for the users to run the IBSI tests for themselves. The tests can also be explored in interactive Colab notebooks that are directly accessible here:
-
- - **Phase 1**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi1p1.ipynb)
- - **Phase 2**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi1p2.ipynb)
+### IBSI Chapter 1
- - ### IBSI Chapter 2
- [The IBSI chapter 2](https://theibsi.github.io/ibsi2/) was launched in June 2020 and reached completion in February 2024. It is dedicated to the standardization of commonly used imaging filters in radiomic studies. We have created two [jupyter notebooks](https://github.com/MEDomicsLab/MEDiml-pkg/tree/main/notebooks/ibsi) for each phase of the chapter and made them available for the users to run the IBSI tests for themselves and validate image filtering and image biomarker calculations from filter response maps. The tests can also be explored in interactive Colab notebooks that are directly accessible here:
-
- - **Phase 1**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi2p1.ipynb)
- - **Phase 2**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi2p2.ipynb)
+[The IBSI chapter 1](https://theibsi.github.io/ibsi1/) is dedicated to the standardization of commonly used radiomic features. It was initiated in September 2016 and reached completion in March 2020. We have created two [jupyter notebooks](https://github.com/MEDomicsLab/MEDiml-pkg/tree/main/notebooks/ibsi) for each phase of the chapter and made them available for the users to run the IBSI tests for themselves. The tests can also be explored in interactive Colab notebooks that are directly accessible here:
- Our team named *UdeS* (a.k.a. Université de Sherbrooke) has already submitted the benchmarked values to the [IBSI uploading website](https://ibsi.radiomics.hevs.ch/).
+- **Phase 1**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi1p1.ipynb)
+- **Phase 2**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi1p2.ipynb)
----
-**Miscellaneous**
+### IBSI Chapter 2
-You can avoid the next steps (Jupyter installation) if you already have a Jupyter Notebook setup available.
+[The IBSI chapter 2](https://theibsi.github.io/ibsi2/) was launched in June 2020 and reached completion in February 2024. It is dedicated to the standardization of commonly used imaging filters in radiomic studies. We have created two [jupyter notebooks](https://github.com/MEDomicsLab/MEDiml-pkg/tree/main/notebooks/ibsi) for each phase of the chapter and made them available for the users to run the IBSI tests for themselves and validate image filtering and image biomarker calculations from filter response maps. The tests can also be explored in interactive Colab notebooks that are directly accessible here:
----
+- **Phase 1**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi2p1.ipynb)
+- **Phase 2**: [](https://colab.research.google.com/github/MEDomicsLab/MEDiml-pkg/blob/main/notebooks/ibsi/ibsi2p2.ipynb)
-You can view and run the tests locally by installing the [Jupyter Notebook](https://jupyter.org/) application on your machine:
+Our team named *UdeS* (a.k.a. Université de Sherbrooke) has already submitted the benchmarked values to the [IBSI uploading website](https://ibsi.radiomics.hevs.ch/).
+
+
Getting help
+
+- **Bugs and feature requests**: open an issue on [GitHub Issues](https://github.com/MEDomicsLab/MEDiml-pkg/issues).
+- **Questions and discussion**: join the [MEDomics Discord](https://discord.gg/ZbaGj8E6mP).
-- **Report a bug or request a feature**: open an issue on the [issue tracker](https://github.com/MEDomicsLab/MEDiml-pkg/issues).
-- **Seek support**: check the [documentation](https://mediml.readthedocs.io/) and its [FAQs](https://mediml.readthedocs.io/en/latest/FAQs.html), then open an [issue](https://github.com/MEDomicsLab/MEDiml-pkg/issues) or contact the team at medomics.info@gmail.com.
+## 
Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## 
Acknowledgement
+
+MEDiml is an open-source package developed at the [MEDomicsLab](https://www.medomicslab.com/en/) laboratory with the collaboration of the international consortium [MEDomics](https://www.medomics.ai/). We welcome any contribution and feedback. Furthermore, we wish that this package could serve the growing radiomics research community by providing a flexible as well as [IBSI](https://theibsi.github.io/) standardized tool to reimplement existing methods and develop new ones.
+
+## 
Citation
-## 7. Citation
If you use MEDiml in your research, please cite it using:
```bibtex
@@ -204,17 +224,8 @@ If you use MEDiml in your research, please cite it using:
}
```
-The full reference manual of MEDiml is available on [arXiv](https://arxiv.org/abs/2610.29666).
-
-## 8. Acknowledgement
-MEDiml is an open-source package developed at the [MEDomicsLab](https://www.medomicslab.com/en/) laboratory with the collaboration of the international consortium [MEDomics](https://www.medomics.ai/). We welcome any contribution and feedback. Furthermore, we wish that this package could serve the growing radiomics research community by providing a flexible as well as [IBSI](https://theibsi.github.io/) standardized tool to reimplement existing methods and develop new ones.
-
-## 9. Authors
-
-MEDiml is developed by:
-* [MEDomicsLab](https://www.medomicslab.com/): Research laboratory at Université de Sherbrooke & McGill University.
-* [MEDomics](https://github.com/medomics/): MEDomics consortium.
+The [MEDiml reference manual](https://arxiv.org/abs/2610.29666) explains the radiomics concepts and workflow shared by the Python package and desktop application, including image preprocessing, feature extraction, predictive modelling and interpretation. It also covers the software architecture and installation, compares MEDiml with other tools, and illustrates its use on five oncological imaging cohorts.
-## 10. License
+## 
License
-MEDiml-app is released under the [GNU General Public License v3.0](LICENSE).
+MEDiml-pkg is released under the [GNU General Public License v3.0](LICENSE.md).