A package for standardised processing of medical imaging and computation of quantitative features.
Project description
Medical Image Radiomics Processor
MIRP is a python package for quantitative analysis of medical images. It focuses on processing images for integration with radiomics workflows. These workflows either use quantitative features computed using MIRP, or directly use MIRP to process images as input for neural networks and other deep learning models.
MIRP offers the following main functionality:
- Extract and collect metadata from medical images.
- Find and collect labels or names of regions of interest from image segmentations.
- Compute quantitative features from regions of interest in medical images.
- Process images for deep learning.
Tutorials
We currently offer the following tutorials:
Documentation
Documentation can be found here: https://oncoray.github.io/mirp/
Supported Python and OS
MIRP currently supports the following Python versions and operating systems:
Python | Linux | Win | OSX |
---|---|---|---|
3.10 | Supported | Supported | Supported |
3.11 | Supported | Supported | Supported |
3.12 | Supported | Supported | Supported |
Supported imaging and mask modalities
MIRP currently supports the following image modalities:
File format | File type | Supported modality |
---|---|---|
DICOM | image | CT, MR (incl. ADC, DCE), PT, RTDOSE, CR, DX, MG |
DICOM | mask | RTSTRUCT, SEG |
NIfTI | any | any |
NRRD | any | any |
numpy | any | any |
NIfTI, NRRD, and numpy files support any kind of (single-channel) image. MIRP cannot process RGB or 4D images.
Installing MIRP
MIRP is available from PyPI and can be installed using pip
, or other installer tools:
pip install mirp
Examples - Computing Radiomics Features
MIRP can be used to compute quantitative features from regions of interest in images in an IBSI-compliant manner using a standardized workflow This requires both images and masks. MIRP can process DICOM, NIfTI, NRRD and numpy images. Masks are DICOM radiotherapy structure sets (RTSTRUCT), DICOM segmentation (SEG) or volumetric data with integer labels (e.g. 1, 2, etc.).
Below is a minimal working example for extracting features from a single image file and its mask.
from mirp import extract_features
feature_data = extract_features(
image="path to image",
mask="path to mask",
base_discretisation_method="fixed_bin_number",
base_discretisation_n_bins=32
)
Instead of providing the path to the image ("path_to_image"
), a numpy image can be provided, and the same goes for
"path to mask"
. The disadvantage of doing so is that voxel spacing cannot be determined.
MIRP also supports processing images and masks for multiple samples (e.g., patients). The syntax is much the same,
but depending on the file type and directory structure, additional arguments need to be specified. For example,
assume that files are organised in subfolders for each sample, i.e. main_folder / sample_name / subfolder
. The
minimal working example is then:
from mirp import extract_features
feature_data = extract_features(
image="path to main image directory",
mask="path to main mask directory",
image_sub_folder="image subdirectory structure relative to main image directory",
mask_sub_folder="mask subdirectory structure relative to main mask directory",
base_discretisation_method="fixed_bin_number",
base_discretisation_n_bins=32
)
The above example will compute features sequentially. MIRP supports parallel processing using the ray
package.
Feature computation can be parallelized by specifying the num_cpus
argument, e.g. num_cpus=2
for two CPU threads.
Examples - Image Preprocessing for Deep Learning
Deep learning-based radiomics is an alternative to using predefined quantitative features. MIRP supports preprocessing of images and masks using the same standardized workflow that is used for computing features.
Below is a minimal working example for preprocessing deep learning images. Note that MIRP uses the numpy notation for indexing, i.e. indices are ordered [z, y, x].
from mirp import deep_learning_preprocessing
processed_images = deep_learning_preprocessing(
image="path to image",
mask="path to mask",
crop_size=[50, 224, 224]
)
Examples - Summarising Image Metadata
MIRP can also summarise image metadata. This is particularly relevant for DICOM files that have considerable metadata. Other files, e.g. NIfTI, only have metadata related to position and spacing of the image.
Below is a minimal working example for extracting metadata from a single image file.
from mirp import extract_image_parameters
image_parameters = extract_image_parameters(
image="path to image"
)
MIRP also supports extracting metadata from multiple files. For example, assume that files are organised in
subfolders for each sample, i.e. main_folder / sample_name / subfolder
. The minimal working example is then:
from mirp import extract_image_parameters
image_parameters = extract_image_parameters(
image="path to main image directory",
image_sub_folder="image subdirectory structure relative to main image directory"
)
Examples - Finding labels
MIRP can identify which labels are present in masks. For a single mask file, labels can be retrieved as follows:
from mirp import extract_mask_labels
mask_labels = extract_mask_labels(
mask="path to mask"
)
MIRP supports extracting labels from multiple masks. For example, assume that files are organised in subfolders for
each sample, i.e. main_folder / sample_name / subfolder
. The minimal working example is then:
from mirp import extract_mask_labels
mask_labels = extract_mask_labels(
mask="path to main mask directory",
mask_sub_folder="mask subdirectory structure relative to main mask directory"
)
Transitioning to version 2
Version 2 is a major refactoring of the previous code base. For users this brings the following noticeable changes:
- MIRP was previously configured using two
xml
files:config_data.xml
for configuring directories, data to be read, etc., andconfig_settings.xml
for configuring experiments. While these two files can still be used, MIRP can now be configured directly, without using these files. - The main functions of MIRP (
mainFunctions.py
) have all been re-implemented.mainFunctions.extract_features
is nowextract_features
(functional form) orextract_features_generator
(generator). The replacements allow for both writing feature values to a directory and returning them as function output.mainFunctions.extract_images_to_nifti
is nowextract_images
(functional form) orextract_images_generator
(generator). The replacements allow for both writing images to a directory (e.g., in NIfTI or numpy format) and returning them as function output.mainFunctions.extract_images_for_deep_learning
has been replaced bydeep_learning_preprocessing
(functional form) anddeep_learning_preprocessing_generator
(generator).mainFunctions.get_file_structure_parameters
andmainFunctions.parse_file_structure
are deprecated, as the the file import system used in version 2 no longer requires a rigid directory structure.mainFunctions.get_roi_labels
is nowextract_mask_labels
.mainFunctions.get_image_acquisition_parameters
is nowextract_image_parameters
.
For advanced users and developers, the following changes are relevant:
- MIRP previously relied on
ImageClass
andRoiClass
objects. These have been completely replaced byGenericImage
(and its subclasses, e.g.CTImage
) andBaseMask
objects, respectively. New image modalities can be added as subclass ofGenericImage
in themirp.images
submodule. - File import, e.g. from DICOM or NIfTI files, in version 1 was implemented in an ad-hoc manner, and required a rigid
directory structure. Since version 2, file import is implemented using an object-oriented approach, and directory
structures are more flexible. File import of new modalities can be implemented as a relevant subclass of
ImageFile
. - MIRP now uses the
ray
package for parallel processing.
Citation info
A publication for MIRP is forthcoming. For now, please cite the following work:
Zwanenburg A, Leger S, Agolli L, Pilz K, Troost EG, Richter C, Löck S. Assessing robustness of radiomic features by image perturbation. Scientific reports. 2019 Jan 24;9(1):614.
Contributing
If you have ideas for improving MIRP, please read the short contribution guide.
Developers and contributors
MIRP is developed by:
- Alex Zwanenburg
We would like thank the following contributors:
- Stefan Leger
- Sebastian Starke
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mirp-2.3.0.tar.gz
.
File metadata
- Download URL: mirp-2.3.0.tar.gz
- Upload date:
- Size: 222.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 19c31280c82c796cb7e69978f9e59a1a743a45011228e984709ae687a8caa678 |
|
MD5 | 1bd8433c90d741786838c9933992175b |
|
BLAKE2b-256 | 670c777ee7bb24859f9954f49f7ff0f764161644fe9def343b6c7f2d80e28de9 |
File details
Details for the file mirp-2.3.0-py3-none-any.whl
.
File metadata
- Download URL: mirp-2.3.0-py3-none-any.whl
- Upload date:
- Size: 277.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 60fe3b7ccdffb71d5bfbd7ee2500df444d8883dd3c896dcfdc4f50ca1e3e46fd |
|
MD5 | 59f5394a55b870d85b2f5a3ed6bdcb65 |
|
BLAKE2b-256 | ca02c233e65f5801dbc3aaaf3c9d3936ceca234cfecfa13fb10aab94794cf35f |