+
+ 
+
+
A Python package for radiomics analysis.
-
MEDiml: MEDical Image analysis with Machine Learning | The package
-
-
+
+
+
+
A Python package for radiomics analysis.
-
+ 
- 📖 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)
-## 1. Introduction
-MEDiml 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. This package is meant to facilitate the processing of medical images and the subsequent computation of all types of radiomic features while maintaining the reproducibility of analyses. This package has been standardized with the [IBSI](https://theibsi.github.io/) norms.
+## 
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.
+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.
-## 2. Installation
+## 
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
```
+Or, with [uv](https://docs.astral.sh/uv/) (the fastest Python package and project manager):
+```
+uv pip install mediml # into your current environment
+uv add mediml # into a uv project
+uv tool install --python 3.10 mediml # only the `radiomics` command, in its own environment
+```
+If your uv project uses Python 3.11 or newer, create one for Python 3.10 instead: `uv init --python 3.10`.
+
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
@@ -86,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
@@ -125,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
+
+[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 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)
+### IBSI Chapter 2
- 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/).
+[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:
----
-**Miscellaneous**
+- **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 avoid the next steps (Jupyter installation) if you already have a Jupyter Notebook setup available.
+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).
+
+## 
Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
-- **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.
+## 
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
@misc{loutfi2026mediml,
- title = {Medical Image Analysis with Machine Learning ({MEDiml}): Strategies for Simpler Radiomics},
+ title = {{MEDical Image analysis with Machine Learning (MEDiml)}: Strategies for Simpler Radiomics},
author = {Ait Lhaj Loutfi, Mahdi and others},
year = {2026},
eprint = {2610.37715},
@@ -196,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).
diff --git a/docs/Installation.rst b/docs/Installation.rst
index 2410dae..ce99411 100644
--- a/docs/Installation.rst
+++ b/docs/Installation.rst
@@ -15,6 +15,27 @@ Install via pip
pip install mediml
+Install via uv
+--------------
+``MEDiml`` can also be installed with `uv