Package: mirp
Medical Image Radiomics ProcessorMedical Image Radiomics Processor (MIRP) is an IBSI-compliant python package for medical image analysis.
MIRP focuses on radiomics applications and supports computation of features for conventional radiomics
and image processing for deep-learning applications.DocumentationDocumentation can be found here:https://oncoray.github.io/mirp/Installing MIRPMIRP is available from PyPI and can be installed usingpip, or other installer tools:pip install mirpTransitioning to version 2Version 2 is a major refactoring of the previous code base. For users this brings the following noticeable changes:MIRP was previously configured using twoxmlfiles:config_data.xmlfor configuring
directories, data to be read, etc., andconfig_settings.xmlfor 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_featuresis 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_niftiis 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_learninghas been replaced bydeep_learning_preprocessing(functional form) anddeep_learning_preprocessing_generator(generator).mainFunctions.get_file_structure_parametersandmainFunctions.parse_file_structureare deprecated, as the
the file import system used in version 2 no longer requires a rigid directory structure.mainFunctions.get_roi_labelsis nowextract_mask_labels.mainFunctions.get_image_acquisition_parametersis nowextract_image_parameters.For advanced users and developers, the following changes are relevant:MIRP previously relied onImageClassandRoiClassobjects. These have been completely replaced byGenericImage(and its subclasses, e.g.CTImage) andBaseMaskobjects, respectively. New image modalities can be added as
subclass ofGenericImagein themirp.imagessubmodule.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 ofImageFile.MIRP uses type hinting, and makes use of theSelftype hint introduced in Python 3.11. MIRP
therefore requires Python 3.11 or later.MIRP now uses theraypackage for parallel processing.Examples - Computing Radiomics FeaturesMIRP 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 segmentations (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.frommirpimportextract_featuresfeature_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:frommirpimportextract_featuresfeature_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 theraypackage.
Feature computation can be parallelized by specifying thenum_cpusargument, e.g.num_cpus=2for two CPU threads.Examples - Image Preprocessing for Deep LearningDeep 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].frommirpimportdeep_learning_preprocessingprocessed_images=deep_learning_preprocessing(image="path to image",mask="path to mask",crop_size=[50,224,224])Examples - Summarising Image MetadataMIRP 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.frommirpimportextract_image_parametersimage_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:frommirpimportextract_image_parametersimage_parameters=extract_image_parameters(image="path to main image directory",image_sub_folder="image subdirectory structure relative to main image directory")Examples - Finding labelsMIRP can identify which labels are present in masks. For a single mask file, labels can be retrieved as follows:frommirpimportextract_mask_labelsmask_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:frommirpimportextract_mask_labelsmask_labels=extract_mask_labels(mask="path to main mask directory",mask_sub_folder="mask subdirectory structure relative to main mask directory")Citation infoA 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.Developers and contributorsMIRP is developed by:Alex ZwanenburgWe would like thank the following contributors:Stefan LegerSebastian Starke