Open-source python package for the extraction of Radiomics features from 2D and 3D images and binary masks.

Artificial Intelligence in Medicine (AIM) Program

Last update: Dec 28, 2022

Related tags

Deep Learning python docker medical-imaging feature-extraction cancer-imaging-research computational-imaging radiomics nci-itcr tcia-dac nci-qin radiomics-features ibsi radiomics-feature-extraction

Overview

pyradiomics v3.0.1

Build Status

Linux	macOS	Windows

Radiomics feature extraction in Python

This is an open-source python package for the extraction of Radiomics features from medical imaging.

With this package we aim to establish a reference standard for Radiomic Analysis, and provide a tested and maintained open-source platform for easy and reproducible Radiomic Feature extraction. By doing so, we hope to increase awareness of radiomic capabilities and expand the community.

The platform supports both the feature extraction in 2D and 3D and can be used to calculate single values per feature for a region of interest ("segment-based") or to generate feature maps ("voxel-based").

Not intended for clinical use.

If you publish any work which uses this package, please cite the following publication: van Griethuysen, J. J. M., Fedorov, A., Parmar, C., Hosny, A., Aucoin, N., Narayan, V., Beets-Tan, R. G. H., Fillion-Robin, J. C., Pieper, S., Aerts, H. J. W. L. (2017). Computational Radiomics System to Decode the Radiographic Phenotype. Cancer Research, 77(21), e104–e107. https://doi.org/10.1158/0008-5472.CAN-17-0339

Join the Community!

Please join the Radiomics community section of the 3D Slicer Discourse.

Feature Classes

Currently supports the following feature classes:

First Order Statistics
Shape-based (2D and 3D)
Gray Level Cooccurence Matrix (GLCM)
Gray Level Run Length Matrix (GLRLM)
Gray Level Size Zone Matrix (GLSZM)
Gray Level Dependece Matrix (GLDM)
Neighboring Gray Tone Difference Matrix (NGTDM)

Filter Classes

Aside from the feature classes, there are also some built-in optional filters:

Laplacian of Gaussian (LoG, based on SimpleITK functionality)
Wavelet (using the PyWavelets package)
Square
Square Root
Logarithm
Exponential
Gradient (Magnitude)
Local Binary Pattern (LBP) 2D / 3D

Supporting reproducible extraction

Aside from calculating features, the pyradiomics package includes provenance information in the output. This information contains information on used image and mask, as well as applied settings and filters, thereby enabling fully reproducible feature extraction.

Documentation

For more information, see the sphinx generated documentation available here.

Alternatively, you can generate the documentation by checking out the master branch and running from the root directory:

python setup.py build_sphinx

The documentation can then be viewed in a browser by opening PACKAGE_ROOT\build\sphinx\html\index.html.

Furthermore, an instruction video is available here.

Installation

PyRadiomics is OS independent and compatible with Python >= 3.5. Pre-built binaries are available on PyPi and Conda. To install PyRadiomics, ensure you have python installed and run:

`python -m pip install pyradiomics`

Detailed installation instructions, as well as instructions for building PyRadiomics from source, are available in the documentation.

Docker

PyRadiomics also supports Dockers. Currently, 2 dockers are available:

The first one is a Jupyter notebook with PyRadiomics pre-installed with example Notebooks.

To get the Docker:

docker pull radiomics/pyradiomics:latest

The radiomics/notebook Docker has an exposed volume (/data) that can be mapped to the host system directory. For example, to mount the current directory:

docker run --rm -it --publish 8888:8888 -v `pwd`:/data radiomics/notebook

or for a less secure notebook, skip the randomly generated token

docker run --rm -it --publish 8888:8888 -v `pwd`:/data radiomics/notebook start-notebook.sh --NotebookApp.token=''

and open the local webpage at http://localhost:8888/ with the current directory at http://localhost:8888/tree/data.

The second is a docker which exposes the PyRadiomics CLI interface. To get the CLI-Docker:

docker pull radiomics/pyradiomics:CLI

You can then use the PyRadiomics CLI as follows:

docker run radiomics/pyradiomics:CLI --help

For more information on using docker, see here

Usage

PyRadiomics can be easily used in a Python script through the featureextractor module. Furthermore, PyRadiomics provides a commandline script, pyradiomics, for both single image extraction and batchprocessing. Finally, a convenient front-end interface is provided as the 'Radiomics' extension for 3D Slicer, available here.

3rd-party packages used in pyradiomics:

SimpleITK (Image loading and preprocessing)
numpy (Feature calculation)
PyWavelets (Wavelet filter)
pykwalify (Enabling yaml parameters file checking)
six (Python 3 Compatibility)
scipy (Only for LBP filter, install separately to enable this filter)
scikit-image (Only for LBP filter, install separately to enable this filter)
trimesh (Only for LBP filter, install separately to enable this filter)

3D Slicer

PyRadiomics is also available as an extension to 3D Slicer. Download and install the 3D slicer nightly build, the extension is then available in the extension manager under "SlicerRadiomics".

License

This package is covered by the open source 3-clause BSD License.

Developers

¹Department of Radiation Oncology, Dana-Farber Cancer Institute, Brigham and Women's Hospital, Harvard Medical School, Boston, MA, ²Department of Radiology, Brigham and Women's Hospital, Harvard Medical School, Boston, MA, ³Department of Radiology, Netherlands Cancer Institute, Amsterdam, The Netherlands, ⁴GROW-School for Oncology and Developmental Biology, Maastricht University Medical Center, Maastricht, The Netherlands, ⁵Kitware, ⁶Isomics

Contact

We are happy to help you with any questions. Please contact us on the Radiomics community section of the 3D Slicer Discourse.

We welcome contributions to PyRadiomics. Please read the contributing guidelines on how to contribute to PyRadiomics.

This work was supported in part by the US National Cancer Institute grants: U24CA194354 - QUANTITATIVE RADIOMICS SYSTEM DECODING THE TUMOR PHENOTYPE and U01CA190234 - TUMOR GENOTYPE AND RADIOMIC PHENOTYPE IN LUNG CANCER

Comments

C matrices
Implement C for calculation of matrices Currently supports:

GLCM

GLSZM

This greatly improves processing speed, while still keeping an all-python option available (currently enabled by setting radiomics.debugging to True.

Also included automatic linking and compiling to setup script. Needs additional package (cython) to work, but is now also included in setup script (if not installed, setup script installs it without error).

Lastly, added a new test, where the python generated matrices are compared to the C generated matrices for all test cases. No features are calculated here, but matrices are assessed element wise (maximum difference for any element is 1e-3, this is due to small machine precision errors possible in NGTDM).
enhancement
opened by JoostJM 79
Add interpolation

resolves #62 add interpolation of the image in radiomics.base change the function imageoperations.interpolateimage, this failed due to missing parameters in rif

The additional thresholding done on resampling of the mask is needed to handle interpolated intensity values between .5 and 1
bug Pre-Processing

opened by JoostJM 66
Image extraction, segmentation, resampling, 2D, MRI cardiac images
Hi everyone! Since I am about to begin a radiomic study ex novo, I just wanted to ask some questions so as to avoid annoying future problems. We will extract images and masks of interest next week from cardiac MRI with the intent of performing a future binary classification.

Should I necessarily extract images in .nrrd format or the .dcm (DICOM) format is fine and easy to convert into .nrrd?

Should the mask simply be an image with ones in the ROI and zeros outside of it?

Since we will probably work with single slices (we will select the most significant 2D slice for each patient), how should I set my third dimension since pyradiomics wants volumes as input? Moreover, which are the features that I will be able to extract? (meaning...are there some features that are only applicable in 3D?)

This is a strange question: one of the two ground truths of the final binary classification is myocarditis and this has the problem that it often doesn't appear as a single concentrated region in the image. As a matter of fact, since it is an inflammatory phenomenon, it often appears as sparse sub regions on the image. How should we deal with masks in this case? Should we just select the biggest region of inflammation? Should we somehow average the inflamed regions?

Thank you very much in advance, Tommaso
opened by tommydino93 57
How should I set /examples/exampleSettings/Params.yaml to use all filters？

Hi everyone! Since I am about to begin a radiomic study ex novo, I just wanted to extract images with all filters.
Now How should I set /examples/exampleSettings/Params.yaml？

Settings to use, possible settings are listed in the documentation (section "Customizing the extraction").

setting: binWidth: 25 label: 1 interpolator: 'sitkBSpline' # This is an enumerated value, here None is not allowed resampledPixelSpacing: # This disables resampling, as it is interpreted as None, to enable it, specify spacing in x, y, z as [x, y , z] weightingNorm: # If no value is specified, it is interpreted as None

Image types to use: "Original" for unfiltered image, for possible filters, see documentation.

imageType: Original: {} # for dictionaries / mappings, None values are not allowed, '{}' is interpreted as an empty dictionary LoG: {'sigma' : [1.0,2.0,3.0,4.0,5.0]} Wavelet: Square: SquareRoot: Logarithm: Exponential:

Thank you very much in advance, Guangzhaohui
question

opened by guangzhaohui 27
Divison by zero?

I get a strange message, when enabling all features and image types:

File "/usr/local/lib/python3.6/dist-packages/radiomics/base.py", line 162, in calculateFeatures self.featureValues[feature] = getattr(self, 'get%sFeatureValue' % feature)() File "/usr/local/lib/python3.6/dist-packages/radiomics/ngtdm.py", line 238, in getContrastFeatureValue contrast = (numpy.sum(p_i[:, None] * p_i[None, :] * (i[:, None] - i[None, :]) ** 2) / (Ngp * (Ngp - 1))) *
File "/usr/lib/python3.6/warnings.py", line 101, in _showwarnmsg _showwarnmsg_impl(msg) File "/usr/lib/python3.6/warnings.py", line 28, in _showwarnmsg_impl text = _formatwarnmsg(msg) File "/usr/lib/python3.6/warnings.py", line 116, in _formatwarnmsg msg.filename, msg.lineno, line=msg.line) TypeError: itkFormatWarning() got an unexpected keyword argument 'line'

Inspecting the line, it seems that the error occurs if the divisor, D = (numpy.sum(s_i)) / Nvp, is zero. There is no check for this there, and probably one should be added.

(Again thanks for the great package :D)
question

opened by aydindemircioglu 27
Convert LIDC-IDRI analysis results to DICOM representation

Given the dataset analyzed and presented in the supplement to the Cancer Research paper (still under review?), develop scripts and generate a DICOM representation of nodule segmentations as DICOM Segmentation image object, and extracted radiomics features, as a DICOM TID1500 Structured Report. The actual conversion will be done using dcmqi.
enhancement documentation testing

opened by fedorov 25
making it python 3 compatible

without breaking the python 2 compatibility (https://github.com/Radiomics/pyradiomics/issues/178), adding the future imports to keep others clean and behavior particularly division consistent.

The current changes should change or break nothing with python 2 execution and only make the code itself runnable on 3.

opened by kmader 25
[BUG] pyradiomics breaking CI when installed as a dependency
Describe the bug As of recently I am getting an error when installing pyradiomics as a dependency of my package during CI

CI log file $ source ~/virtualenv/python3.7/bin/activate $ python --version Python 3.7.1 $ pip --version pip 20.1.1 from /home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/pip (python 3.7) install.1 2.45s$ python -m pip install -U pip install.2 1.42s$ pip install tox 33.59s$ tox GLOB sdist-make: /home/travis/build/mluerig/phenopype/setup.py py37 create: /home/travis/build/mluerig/phenopype/.tox/py37 py37 installdeps: .[test] py37 inst: /home/travis/build/mluerig/phenopype/.tox/.tmp/package/1/phenopype-1.0.7.zip py37 installed: attrs==20.2.0,certifi==2020.6.20,chardet==3.0.4,coverage==5.3,coveralls==2.1.2,docopt==0.6.2,EasyProcess==0.3,idna==2.10,importlib-metadata==2.0.0,iniconfig==1.0.1,mock==4.0.2,numpy==1.18.5,opencv-contrib-python==3.4.9.33,packaging==20.4,pandas==1.1.2,pathtools==0.1.2,phenopype==1.0.7,Pillow==7.2.0,pluggy==0.13.1,py==1.9.0,pykwalify==1.7.0,pyparsing==2.4.7,pyradiomics==3.0,pytest==6.1.0,pytest-cov==2.10.1,pytest-xvfb==2.0.0,python-dateutil==2.8.1,pytz==2020.1,PyVirtualDisplay==1.3.2,PyWavelets==1.0.0,PyYAML==5.3.1,requests==2.24.0,ruamel.yaml==0.16.12,ruamel.yaml.clib==0.2.2,SimpleITK==2.0.0,six==1.15.0,toml==0.10.1,tqdm==4.50.0,urllib3==1.25.10,watchdog==0.10.3,zipp==3.2.0 py37 run-test-pre: PYTHONHASHSEED='2973730562' py37 run-test: commands[0] | pytest -s --cov=phenopype --cov-report=html ImportError while loading conftest '/home/travis/build/mluerig/phenopype/tests/conftest.py'. tests/conftest.py:5: in import phenopype as pp phenopype/init.py:3: in from .main import project, pype phenopype/main.py:23: in from phenopype.core import preprocessing, segmentation, measurement, export, visualization phenopype/core/measurement.py:9: in from radiomics import featureextractor .tox/py37/lib/python3.7/site-packages/radiomics/init.py:15: in from . import imageoperations .tox/py37/lib/python3.7/site-packages/radiomics/imageoperations.py:6: in import pywt .tox/py37/lib/python3.7/site-packages/pywt/init.py:16: in from ._extensions._pywt import * pywt/_extensions/_pywt.pyx:1: in init pywt._extensions._pywt ??? pywt/_extensions/_dwt.pyx:7: in init pywt._extensions._dwt ??? E ImportWarning: can't resolve package from spec or package, falling back on name and path ERROR: InvocationError for command /home/travis/build/mluerig/phenopype/.tox/py37/bin/pytest -s --cov=phenopype --cov-report=html (exited with code 4) ___________________________________ summary ____________________________________ ERROR: py37: commands failed The command "tox" exited with 1.

To Reproduce https://ci.appveyor.com/project/mluerig/phenopype https://travis-ci.org/github/mluerig/phenopype

Version (please complete the following information):

OS: windows, linux

Python version: 3.7

PyRadiomics version: 3.0

Additional context looks like pywt is breaking here - any ideas? thanks!
bug
opened by mluerig 24
Voxel based extraction memory error [FEAT EXTRACTION]

Hi I am trying to used the Pyradiomics voxel-based feature extractor and I am getting a memory error. Any ideas on how to fix this?

Here are my computer specs:

Here is the error I am getting:

When I run it using the original image and no mask, it works fine (I type 'pyradiomics original.nrrd original.nrrd --mode voxel' in the command line), however, when I use the mask, it does not work ('pyradiomics original.nrrd mask.nrrd --mode voxel'
question

opened by AT3432984 22
Generalize binning using binEdges

This pull request standardizes binning in imageoperations and firstorder. Branched from PR #64

In imageoperations, the binedges are defined using numpy.arange, from low edge to high edge This PR calculates the low edge as the minimum value,not as min value - binwidth, which caused the formation of an empty first bin. second, in the case where the upper edge was equal to max, numpy.digitize assigned bincount + 1 to voxels with max value, where numpy.histogram assigned bincount as value. To prevent this, this PR adds + 1 to the upper binedge.

In firstorder a bincount was directly calculated, but this throws an error when min and max intensity values are equal (in this case, the bincount would be 0, which throws the error in numpy.histogram). This PR changes the binning in firstorder so it matches binning as described above.

PR #59 CC @Radiomics/developers
bug enhancement feedback featureChange Pre-Processing

opened by JoostJM 22
2D-feature extraction

In FAQs/"What modalities does PyRadiomics support?", 2D-feature extraction was explained as follows: 3D or slice: Although PyRadiomics supports single slice (2D) feature extraction, the input is still required to have 3 dimensions (where in case of 2D, a dimension may be of size 1). http://pyradiomics.readthedocs.io/en/latest/faq.html

Could someone describe more clearly what needs to be done? I plan to extract texture features from a single ultrasound image and its mask (directly from jpg or tiff format).
question

opened by HIN0209 21
[FEAT EXTRACTION] The Unit of Measurements
Hi, about Shape, Texture, First Order features (like mean, autocorrelation , flatness , ....) what is their unit of measurements?

thanks.

OS: win 10

Python version: 3.9.12

PyRadiomics version 3.0.1

question
opened by nimayousefi75 0
Add PEP-517 compliant build requirement specification

cc: @Radiomics/developers

Hello pyradiomics team! Thanks for the great open source software you are building here.

I am working on a project using pyradiomics that is transitioning to using poetry for dependency management. During the migration, I ran into issues installing pyradiomics due to the build-time dependency of numpy not being present. After doing some research, I realized this is because poetry expects a PEP-517 style build dependency specification, which is basically just a stub pyproject.toml file with the build-time requirements specified.

It looks like this new format for build-time dependencies is now the standard in the Python ecosystem, and setuptools (the packaging solution used in this project) also recommends the use of the toml file approach now (see https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#build-system-requirement). This is in contrast to the current use of the setup_requirements kwarg in setup.py.

I have confirmed that with the addition of this stub pyproject.toml file, installation with poetry works as expected. Since this is now an accepted PEP and tools are moving towards expectation of this format, I wanted to propose the addition of this file to enable using pyradiomics in poetry-based python projects. This should have no other side effects in the build system and require no changes to any existing build tools.

In addition to merging this in to master, I am hoping it would be possible to cut a v3.0.2 patch release that will add support for PEP-517 builds to the version of pyradiomics available on pypi.

I'm happy to answer any questions you have and discuss further! Thanks!

opened by ReeceStevens 2
[BUG]How to avoid Valueerror:mask only contains 1 segmented voxel! Cannot extract features for a single voxel
Describe the bug A clear and concise description of what the bug is. Please check FAQ section, PyRadiomics issues and PyRadiomics Slicer Discourse to check if your bug has been encountered before. If so, but you still require additional help, please reference related issues.

PyRadiomics configuration Add any customization you applied here (i.e. the content of the parameter file used)

PyRadiomics log file If available, add section of the PyRadiomics log showing your error. For help on setting up logging, see the online documentation

To Reproduce Steps to reproduce the behavior:

Expected behavior A clear and concise description of what you expected to happen.

Version (please complete the following information):

OS: [e.g. iOS]

Python version: [e.g. 3.6]

PyRadiomics version [e.g. 2.2.0]

Additional context Add any other context about the problem here.
bug
opened by Sharath-Kumar-Reddy-M-B19CSE082 0
[FEAT EXTRACTION]how to avoid valueerror:mask only contains 1 segmented voxel! Cannot extract features for a single voxel
Describe the bug A clear and concise question regarding your extraction. Please check FAQ section, PyRadiomics issues and PyRadiomics Slicer Discourse to check if your question has been encountered before. If so, but you still require additional help, please reference related issues.

PyRadiomics configuration Add any customization you applied here (i.e. the content of the parameter file used)

PyRadiomics log file If available, add section of the PyRadiomics log related to your question. For help on setting up logging, see the online documentation

To Reproduce Steps to reproduce the behavior:

Version (please complete the following information):

OS: [e.g. iOS]

Python version: [e.g. 3.6]

PyRadiomics version [e.g. 2.2.0]

Additional context Add any other context about your question here.
question
opened by Sharath-Kumar-Reddy-M-B19CSE082 0
How to select the ROI from multiple ROIs in one segmentation file?

Hi, For each study I have one 3D CT file and one segmentation file with multiple ROIs. I have two questions: 1- How can I know how many ROIs are in the segmenation file. 2- How can I extract radiomics for the ROIs one by one? I know that to select the desired ROI in which I am interested to extract the radiomics I should identify 'label', and each time I can only extract the radiomics for one ROI, right? But how can I know about the value of the labels? Imagine that I have 5 ROIs in one segmentation file and I only need to extract the features for the 2nd ROI or for the one which is labelled as 'Tumor' in the SEG dicom file. How can I specify it with 'label' in the execute function of pyradiomics?
question

opened by Leylaastro 0

Releases(v3.0.1)

v3.0.1(Oct 11, 2020)
Bug Fixes

Fix bug causing IndexError when no gray levels are 'empty'. (#592)

Fail initialization of feature extractor when the passed parameter file path does not point to existing file. (#587)

Fix out-of-range check in GLSZM C calculation. (#635)

Fix bug in Travis CI testing (MacOS platform). (#643, #646)

Fix cmake URL and remove python2 support from DockerFiles. (#645)

Examples

Add example settings for forced-2D extraction in MR. (#613, #644)

Documentation

Fix typos in documentation. (9d26a6b8, 896682d7, e100f1d0, #639)

Further clarify resampling. (#599)

Internal API

Fail gracefully when grayvalues < 1 are encountered in the discretized image. (#602)

Add optional progress reporting for voxel-based extraction. (#636)

Source code(tar.gz)
Source code(zip)
v3.0(Oct 11, 2020)
Note!

In this release, the main interface class, RadiomicsFeaturesExtractor(), was renamed to RadiomicsFeatureExtractor() (no 's' between 'Feature' and 'Extractor'). This was done to avoid confusion between the module and class name. (#481 )

Bug Fixes

Fix broken Conda deployment (51c5849)

Fix error in IBSI mapping (labs/pyradiomics-dcm) (54d6689)

Fix resampling error when spacing is correct, but sizes are different (ac7458e)

Fix label channel selection (54a3782)

Use local scope of settings, preventing race conditions in parallel extraction (43578f7)

Fix resampling for 2D input (#545)

Internal API

Update C API to use large datatype for index pointers (#500, #501)

Update docker CLI to use python 3.6.9 and fix bugs to allow integration with pyradiomics-dcm lab (#527)

Add option to force path to UNIX style paths, even on windows (3c0708a)

Removed deprecated code (fedaa5e)

Testing

Remove testing and deployment for python 2.7 (a5a7e61)

Documentation

Refactor documentation (#536)

Fix various typos/wording

Clarify use of force2D, and add example settings file (#558)

Source code(tar.gz)
Source code(zip)
2.2.0(May 16, 2019)
In this release, the main interface class, RadiomicsFeaturesExtractor, was renamed to RadiomicsFeatureExtractor (no 's' between 'Feature' and 'Extractor'). This was done to avoid confusion between the module and class name. (#481)

New Features

Add 2D shape features (#442)

Expose voxel-based feature extraction on the PyRadiomics command line interface. (#457)

Labs

Add notebook investigating reproducibility between PyRadiomics and USF tool (ITK-based; #458)

Bug Fixes

Flatten array when applying gray value discretization of the entire image (voxel-based, full kernel; f87abcf)

Fix incorrect removal of 'empty gray levels' in GLDM and GLRLM (voxel-based; 4b18ce2)

Fix incorrect instantiation of firstorder voxel-based extraction. (81e713a)

Force cast coefficients to float. Prevents overflow and type errors in feature calculation. (e9d60c7)

Tests

Removed support and continuous integration for Python 3.4 (not maintained since March 2019). Added support and CI for Python 3.7. (#486)

Internal API

Update C-extensions:

Rewrite C code to work with N-Dimensional input. (#463)

Add batch-calculation of kernels and vectorized feature calculation to improve voxel-based extraction duration. (#466)

Add support for segmentation objects (multi-layer labelmaps; #445)

Refactor the commandline interface (#481)

Extractor instantiated once (resulting in only 1 validation of the parameter file, outside of paralellization loop)

Simplify construction of the python generator of the cases that are to be extracted

Remove now unnecessary functions

Documentation

Update documentation (#446, 690891d)

Fix some rendering errors (723d868, e3eb427)

Source code(tar.gz)
Source code(zip)
2.1.2(Dec 5, 2018)
Labs

Include algorithm details in dcm output. (f03145b)

Source code(tar.gz)
Source code(zip)
2.1.1(Nov 16, 2018)
New Features

Implement validation of commandline input. (#433)

Implement thread-safe logging for python >= 3.2. (#441, d8db675)

Labs

Add script to support extraction of radiomics features directly from DICOM (segmentation should be defined as a DICOM Segmentation object), and saving the result directly as a DICOM Structured Reporting object conforming to TID 1500. The script utilizes external tools for conversion of DICOM image series into volumes (plastimatch and dcm2niix), conversion of DICOM Segmentation segments into volumes (dcmqi), and conversion of pyradiomics output features into DICOM SR (dcmqi). (#434)

Bug Fixes

Fix memory error in calculation of GLCM-MCC. (167888b)

Fix error in serialization for JSON output. (9d992fe)

Tests

Expand testing to include more parts of PyRadiomics. (#410)

Internal API

Force cast the mask to an integer datatype on load. (#431)

Dependencies

Fix PyWavelets version to > 0.4.0, <= 1.0.0, due to compilation issue in SlicerRadiomics. (c828b99, SlicerRadiomics#50)

Source code(tar.gz)
Source code(zip)
2.1.0(Nov 16, 2018)
Feature Calculation Changes

Switch Shape - Volume calculation to a mesh-based instead of a voxel-based one. This also affects all features derived from Volume. Original Volume calculation is retained as VoxelVolume. Also switch calculation of maximum diameter to mesh based. Only PCA-derived are not affected. (#427)

New Features

Add GLCM - Maximal Correlation Coefficient. (#411)

New Parameters

Update resegmentation function, add support for single (lower) threshold and new modes relative and sigma, customizable in parameter resegmentMode. (#420)

Add resegmentShape. Default False, if set to True, the resegmented mask (intensity mask) will also be used for shape calculation. Otherwise, the non-resegmented mask (morphological mask) is used for shape. (#428)

Bug fixes

Fix bug in dimension checking in checkMask. (623b836)

Fix some errors in the testUtils and baseline generation script. (c285c15)

Prevent division by 0 in NGTDM - Coarseness. Return 0 instead. (a59861e)

Remove duplicate key in settings file example. (828a7ac)

Prevent duplicate log entries in parallel batch extraction. (8cedd8f)

Build PyWavelets from source for AppVeyor (Windows) python 3.4 testing. Requires pre-installation of numpy and cython. (6223d35)

Tests

Integrate automatic distribution to conda upon release. (#422)

Documentation

Update README and Setup.py with additional classifiers, urls. Update section in README on Docker usage. (0fe737e)

Internal API

Use ValueError exceptions when feature extraction pipeline fails (exceptions of individual features). (#420)

Update generation and names of general info features (provenance information). (#420, #426)

Rewrite signatures of pre-processing functions to accept all customization arguments in 1 **kwargs dict. Necessary parameters are obtained using kwargs.get inside the function. Full settings are passed to the function. (#425)

Source code(tar.gz)
Source code(zip)
2.0.1(Nov 16, 2018)
New Features

Add Center of Mass to general info output. (#416)

Bug fixes

Fix invocation of numpy.histogram when using a fixed bin count. (2a9fd79)

Fix assignment of x and y pixelspacing in shape (no changes in results). (#404)

Fix generation of approximation name (LLL or LL) in wavelet. (#405)

Add missing requirements for new filters in Docker CLI file. (#409)

Fix memory leak in C extensions. (#419)

Fix Label column parsing in batch processing. (217a840)

Documentation

Fix math rendering in GLCM. (c6a1f21)

Add reference to GLDM feature class. (9f9361a)

Correct typo in IMC1 and 2 formulas. (4ba909a)

Update warning message in ROI check. (1f16b9e)

Update usage section in documentation on command line usage. (fe0e2c3)

Internal API

Simplify calculation of various GLCM features (no changes in results). (#407)

Source code(tar.gz)
Source code(zip)
2.0.0(Nov 16, 2018)
Feature Calculation Changes

Change calculation of filter coefficients to reflect absolute maximum (take into account negative values). (#319)

Mark duplicate features as 'deprecated' and document mathematical proof of the equality. (#321)

Fix error in calculation of NGTDM's Complexity and Contrast features. (#351)

New Features

Add preCrop, which crops the image onto the bounding box with an additional padding specified in padDistance. This is similar to cropping as performed during resampling and serves to decrease memory consumption and computation time. N.B. To ensure calculated values are not changed, a sufficient padding is required when using filters which include values outside of ROI (e.g. Wavelet, LoG). (#317)

Add skip-nans as a commandline argument. If specified, features that compute NaN are removed from the output. In batch mode, NaN is replaced by an empty string. (#318)

Add support to configure the feature extractor using a JSON structured string. (#334)

Add Gradient Magnitude Filter. (#356)

Add Local Binary Pattern Filter (2D/3D). (#357)

Add support for Gray Value discretization using a fixed bin count. (#386)

Bug fixes

Ensure PyKwalify has a log handler, which is needed when parameter file validation fails. (#309)

Fix bug in error handling in :py:func:~radiomics.imageoperations.checkMask (compatibility issue between python 2 and 3).

Fix bug in GLCM (incorrect use of self.maskArray). (#322)

Fix bug in error handling during geometry checks of image and mask. (0257217)

Fix broken continuous testing integration due to unavailability of pip script. (#333)

Fix incorrect path separator in example scripts. (c7c5d2e)

Fix bug in the calculation of Wavelet. (#346)

Fix machine-precision errors in Eigenvalue calculation (Shape). (#355)

Update validation rule for image filters (remove hardcoded filters by package-detected filters). (#364)

Add missing requirements for LBP filters in the dockerfile. (#389)

Fix deprecation error in feature extractor. (da1fc16)

Fix axis definition in wavelet. (4027a52)

Fix erroneous double return of wavelet approximation. (c8ceee2)

Tests

Improve testing badge layout. (#312)

Remove unused testing configuration files. (#313)

Add testing for wavelet output. (#387)

Integrate publication to PyPi into the Continuous Integration, revise the CI workflow to test python 2.7, 3.4, 3.5 and 3.6 for all 3 platforms (Windows, Mac and Linux). N.B. This makes PyRadiomics installable via pip. (#394)

Documentation

Update documentation of base.py. (#306)

Update notebooks to reflect most recent version of PyRadiomics. (ac66e6c)

Add documentation detailing rationale of enforcing a fixed bin width. (#320)

Update reference to official publication. (b395904)

Update installation instructions for docker. (#329)

Add version of NumPy, SimpleITK and PyWavelet to the additional information in the output. (#342)

Add documentation for the calculation of Laplacian of Gaussian. (#345)

Add refrences for the newly implemented filters. (4464d1c)

Fix an error in the firstorder-Uniformity documentation. (da7321d)

Examples

Add example for batchprocessing using a multithreaded approach. (#305)

Internal API

Update batch script for the commandline interface. Ensures all required input is available and relative filepaths are relative to the input file, not the current working directory. (#307)

Remove support for 32-bits python, as memory errors can arise when extracting from many or large images in 32-bits python. (#310)

Simplify Calculation of Wavelet Filter. Does not change output. (#323)

Refactor commandline interface to work with only 1 entry point (pyradiomics). Also add parallel-processing option for batch-processing (argument -j, which specifies number of CPU cores to use). (#347)

Reconfigure testing to allow the removal of testcases from the repository itself (still available as binary data attached to release 1.0.0) and store the baseline in a different format (allowing for easier change-tracking). (#353)

Add a check for number of bins generated (preventing construction of too large matrices in C) (#391)

Source code(tar.gz)
Source code(zip)
1.3.0(Oct 6, 2017)
Feature Calculation Changes

Remove feature Sum Variance, as this is mathematically equal to Cluster Tendency. (#300)

New Features

Add a row by row customization of the extraction label in the batch processing command line script, as well as both batchprocessing examples. (#262)

Allow value 0 for a resampled pixel spacing (per dimension). Values of 0 are replaced by the spacing for that dimension as it is in the original (non-resampled) mask. This allows resampling over a subset of dimension (e.g. only in-plane resampling when out-of-plane spacing is set to 0). (#299)

Add optional resegmentation of mask based on customizable threshold. (#302)

Add Neighbouring Gray Tone Difference Matrix (NGTDM) (#296)

Add Add Gray Level Dependence Matrix (GLDM) (#295)

Add a docker file that exposes the PyRadiomics commandline tools. (#297, #301)

Bug fixes

In GLCM, the matrix is made symmetrical by adding the transposed matrix. However, numpy.transpose returns a view and not a copy of the array, causing erroneous results when adding it to the original array. use numpy.ndarray.copy to prevent this bug. N.B. This affects the feature values calculated by GLCM when symmetrical matrix is enabled (as is the default setting). (#261)

Use a python implementation to compute eigenvalues for shape.py instead of SimpleITK. The implementation in SimpleITK assumes segmented voxels to be consecutive on the x-axis lines. Furthermore, it also assumes that all voxels on a given line of x have the same values for y and z (which is not necessarily the case). (#264)

Removal of outliers was not applied to returned object in normalizeImage. (#277)

Fix python 3 incompatibility when using urllib. (#285)

Fix broken URL link in feature visualization notebooks.

Update docker manually install python2 support (since recently not supported by default in jupyter/datascience-notebook). (#287)

For GLRLM and GLSZM, force2D keyword is passed manually, but was incorrectly named and therefore ignored. Fix name to enable forced 2D extraction for GLRLM and GLSZM. (26b9ef3)

Tests

Update the C Matrices test, so that the C and python calculated matrices will have the same dimensions when compared (In the previous implementation, the _calculateCoefficients function was applied to the C calculated matrix, but not in the python calculated matrix, for some texture matrices, this function can change the dimension of the matrix). This update ensures that _calculateCoefficients is applied to neither matrix. (#265)

Add a test to check validity of parameter files included in examples/exampleSettings. (#294)

Documentation

version 1.3.0 docs

Update reference. (#271)

Move section "Customizing the Extraction" to the top level, to make it more visible. (#271)

Change License to 3-clause BSD (#272)

Document the extend of compliance between PyRadiomics and the IBSI feature definitions (#289)

Fix typos in documentation.

Expand documentation on customizing the extraction. (#291)

Include contributing guidelines in sphinx-generated documentation and add a section on sharing parameter files. (#294)

Insert missing line to enable all features in documentation on using the feature classes directly. (5ce9f48)

Examples

Add example settings for CT, MR (3 scenarios). (#273)

Internal API

Remove unnecessary rows and columns from texture matrices prior to feature calculation. This does not affect the value of the calculated features, as the i and j vectors are updated accordingly, but it does reduce both computation time and memory requirements. This is especially the case when calculating GLSZM on large segmentations, where there may be many 'empty' zone sizes (i.e. no zones of that size are present in the ROI). This reduces the size of the matrix, which therefore reduces the memory needed and the number of calculations performed in the vectorized operations. (#265)

Remove circular import statement in __init__.py (circular with radiomics.base). (#270)

Revise initialization of the feature class. (#274)

Rename parts of the customization variables and functions to better reflect their definition (#291)

License

Switch to 3-clause BSD license. (#272)

Source code(tar.gz)
Source code(zip)
1.2.0(May 30, 2017)
Feature Calculation Changes

Remove feature SumVariance, rename SumVariance2 to SumVariance. SumVariance reflected the formula as is defined in the paper by Haralick et al [1]_. However, the variance is calculated by subtracting the entropy as opposed to subtracting the average, most likely due to a typo('f8' instead of 'f6'). SumVariance2 reflected the formula where the average is subtracted and is retrained as the only SumVariance. (#233)

Redefine features Elongation and Flatness as the inverse of the original definition. This prevents a returned value of NaN when the shape is completely flat. (#234)

In certain edge cases, the calculated maximum diameters may be too small when calculating using the python implementation. This is corrected by the C extension and a warning is now logged when calculating these features in python. N.B. As of this change, maximum diameter is not available for calculation in full-python mode (#257)

For certain formulas, a NaN value is returned in some edge cases. Catch this and return a predefined value instead. Document this behaviour in the docstrings of the features affected. (#248)

New Features

Add Region of Interest checks. (#223, #227)

Add variable column support for batch input file (#228)

Add Docker support (#236)

Bug fixes

Instantiate output with input in commandlinebatch

Correct Np when weighting is applied in GLRLM (#229)

Update CSV generators to reflect variable number of columns for input CSV in batch processing (#246)

Return corrected mask when it had to be resampled due to geometry mismatch errors (#260)

Requirements

Remove tqdm requirement (#232)

Reorganize requirements, with requirements only needed during development moved to requirements-dev.txt (#231)

Documentation

version 1.2.0 docs

Update feature docstrings, making them more easily adaptable for article supplements (#233)

Add FAQ concerning the cmatrices lib path (#233)

Add developer install step to documentation (#245)

Remove use of sudo (#233)

Fix subclass name in feature class signature (section "Developers")

Add subsection on customizing the extraction to the "Usage" section (#252)

Remove SimpleITK installation workaround, this is no longer needed (#249)

Add a changelog to keep track of changes and integrate this into the auto generated documentation (#255)

Examples

Add pandas example, showing how to process PyRadiomics output/input using the pandas library (#228)

Internal API

Add function to get or download test case (#235)

Rewrite C Extension algorithm for GSLZM. Instead of searching over the image for the next voxel when growing a region, store all unprocessed voxels in a stack. This yields a significant increase in performance, especially in large ROIs. Requires slightly more memory (1 array, type integer, size equal to number of voxels in the ROI) (#257)

Implement C extension for calculation of maximum diameters. (#257)

Cleanups

Restructure repository (#254)

Move jupyter notebooks to separate root folder (root/notebooks)

Move example script to separate root folder (root/examples), with example settings in separate subfolder (root/examples/exampleSettings)

bin folder now only contains support scripts for the core code (i.e. generators for input files for batch processing and scripts to generate new baselines or to resample a mask to the image geometry)

Source code(tar.gz)
Source code(zip)
1.1.1(Mar 22, 2017)
Feature changes

Correct error in formula for Compactness1. N.B. Baseline updated! #218

Remove feature Roundness, as this feature is identical to feature sphericity, but uses different implementation for surface area calculation (all implemented in SimpleITK) #218

Documentation

Restructure documentation #216

Split package documentation into "Pipeline Modules" (all non-feature-class modules) and "Feature Definitions" (feature class modules)

Add developers section with documentation on how to implement new filters, feature and feature classes.

Add FAQ section with some trouble shooting tips

Rename some GLSZM features, this is to make them more consistent with GLRLM features, which are similar, but calculated on a different matrix

Add documentation for Elongation and Flatness

Document mathematical correlation between various Shape features.

The version specific documentation is available here.

Bugfixes

Add some missing python 3 compatibility lines to the supporting script addClassToBaseline and command line script pyradiomicsbatch #210 #214

Fix bug when loading image as file path and mask as SimpleITK object. #211

Add sphinx_rtd_theme to requirements (needed to build documentation). #222

Change location of parameter schema files. These files are otherwise not included in the wheel distribution. #221

Enhancements

Update logging with more extensive debug logging and more informative info log messages. #220

Replace parameter verbose with output printing implemented in logging. Control verbosity level to output (stderr) by calling radiomics.setVerbosity(level), where level determines the verbosity level (as defined in python logging). This prints out the requested levels of the log messaging, where process reports with parameter verbose are now classified as INFO-level messages (i.e. specify INFO or DEBUG to enable these). N.B. parameter verbose is not longer supported and will throw an error if passed in the parameter file #220

Add feature class and input image type checks in featureextractor when changing these settings. #213

Remove usage of eval (replaced by implementations of getattr), this is a more secure approach. #216

Change handling of cases where max(X) mod binwidth = 0 during image discretization. These used to be assigned to topmost bin, but this produces unexpected behaviour (i.e. in range 1, 2, 3, 4, 5 with binwidth 1, value 5 would be discretized to 4 in stead of 5). Value now assigned is topmost bin + 1 (in concordance with default behavior of numpy.digitize) #219

Add forced 2D extraction (as alternative to resampling for handling anisotropy in voxels spacing) #215

Enable specification of distances between neighbors for texture matrices. #215

Change default value for voxelArrayShift (from 2000 to 0), this is to prevent unknowingly using a too large shift when not necessary. Document effect of this parameter in the first order formulas affected. #219

Style

Remove unused variable (self.provenance_on in featureextractor, this value is now replaced by a customizable setting)

Define default settings in featureextractor in a separate function. This is to ensure consistency in applied default settings, as well as make them easily available outside of featureextractor #224 216

Update reference in documentation. #224

Source code(tar.gz)
Source code(zip)
1.1.0(Feb 22, 2017)
Implementation of C Extensions

Stats:

Profiling 5 testcases using python 2.7

GLCM 6913 ms -> 3 ms

GLSZM 12064 ms -> 58 ms

GLRLM 1850 ms -> 10 ms

Surface Area 3241 -> 1 ms

Code:

_cmatrices: C implementation for matrix computation associated with GLCM, GLSZM and GLRLM features.

_cshape: C implementation for Shape surface computation.

tests/test_cmatrices: testing for matrix equality: Tests whether the python generated matrix is equal to the matrix generated by the C implementations (allows for machine precision errors). Also compares the python and C generated surface computations similarly.

Details

Standardize function names for calculating matrices in python and with C extensions to _calculateMatrix and _calculateCMatrix, respectively.

Add docstring to C modules.

Use of C implementation optional. At initialization, the package tries to use C, but if loading has failed, or calculation is forced to python, python is used. Note that the import of _cmatrices is done after initialization of logger. This ensures error will be logged if import fails. This can be controlled through the enableCExtensions setting, which can be provided in a parameter file or as part of the kwargs dictionary in featureextractor.

GLSZM: Use "char" datatype for mask. (It is signed char in GLSZM).

C code is consistent with C89 convention. All variables (pointers for python objects) are initialized at top of each block.

GLSZM: Use calloc and free for the temporary array holding the calculated zones.

Optimizations

GLSZM:

Define temporary array for holding the calculated zones. During calculation, the matrix must be able to store all possible zones, ranging from zone size 1 to total number of voxels (Ns), for each gray level (Ng). In this case, the GLSZM would be initialized with size Ng * Ns, which is very memory intensive. Instead, use a temporary array of size (Ns * 2) + 1, which stores all calculated zones in pairs of 2 elements: the first element holds the gray level, the second the size of the calculated zone. The first element after the last zone is set to -1 to serve as a stop sign for the second function, which translates the temporary array into the final GLSZM, which can be directly initialized at optimum size.

Uses "while" loops. This allows to reduce the memory usage. We observed that with recursive functions it was 'unexpectedly' failing.

Optimized search that finds a new index to process in the region growing.

Associated issues: #106

Associated PRs: #158, #200, #202

Python 3 Compatibility:

As of this version, PyRadiomics is compatible with python 2.7 and python >= 3.4. This is acchieved through use of third-party package six (added to requirements.txt). The changes to ensure this compatibility do not change the user interface.

Associated issues: #178, #204

Associated PRs: #188, #194, #196, #205

Normalization

Add functionality to imageoperations for normalizing image intensity values. If enabled, the image is normalized by centering it at the mean with standard deviation. Normalization is based on all gray values in the image, not just those inside the segementation. It is enabled or disabled by setting the parameter normalize.

Values can be scaled using parameter normalizeScale, which multiplies the normalized intensity values by the value of this paramter.

Outliers can be removed by setting the removeOutliers parameter. If set, all values differing more than n * (standard deviation) from the mean are set to n * (standard deviation), where n is equal to the value of this parameter. This is done after normalizing and before applying the scale. If this last parameter is omitted, no outliers are removed.

If enabled, normalization is applied after loading the image, before any resampling or application of filters.

Associated PRs: #209

Parameterization:

Add parameter for controlling the additional output (enable/disable by setting additionalInfo parameter)

Add parameter for controlling whether or not to calculate in full-python mode (enable/disable by setting enableCExtensions parameter).

Associated PRs: #190, #202

Documentation:

Documentation on installation and usage is upgraded, with the addition of an embedded instruction video (in section "Usage", cued at the section on usage examples).

Updated contact information to point to the google groups.

Updated the classifiers in the setup script to reflect the more advanced status of Pyradiomics.

The version specific documentation is available here.

Associated PRs: #187, #193

Continuous Testing:

Upgrade to include other python versions and platforms

Tests are passed for Linux, Windows and Mac, using python 2.7, 3.4 and 3.5, in 32- and 64-bit builds.

Associated PRs: #183, #191, #199

Style:

Testing output is upgraded to ensure unique feature names.

getFeatureClasses() and getInputImageTypes() functions are moved from featureextractor to global radiomics namespace. This enumerates the possible feature classes and filters at initialization of the toolbox, and ensures feature classes are imported at initialization.

Associated PRs: #190, #195, #197, #198
Source code(tar.gz)
Source code(zip)
v1.0.1(Feb 6, 2017)
Additional Functionality:

Added 2 commandline scripts: pyradiomics and pyradiomicsbatch, which enable feature extraction directly from the commandline. For help on usage, run script with “-h” argument.

Changed Functionality:

Different implementation of the various filters. No changes to calculation, but has a changed signature.

N.B. This results in inputImages to be differently defined (different capitalization, e.g. "orginal" should now be "Original"). See documentation for definition of inputImages (featureextractor section).

Bugfixes:

Bugfix of a numpy slicing error in application of wavelet filters. This error caused the derived image to be erroneously rotated and flipped, with misaligned mask as a result.

Documentation:

Update on the documentation, reflecting recent changes in the code.

Added additional references and updated installation and usage section.

Source code(tar.gz)
Source code(zip)
v1.0(Jan 23, 2017)
Initial release of PyRadiomics

Full python calculation (C matrices branch not stable and reserved for later release)

Published documentation at readthedocs

Source code(tar.gz)
Source code(zip)
brain1_image.nrrd(1.93 MB)
brain1_label.nrrd(7.34 KB)
brain1_label_2D.nrrd(829 bytes)
brain2_image.nrrd(1.65 MB)
brain2_label.nrrd(6.24 KB)
brain2_label_2D.nrrd(737 bytes)
breast1_image.nrrd(76.88 KB)
breast1_label.nrrd(710 bytes)
breast1_label_2D.nrrd(461 bytes)
lung1_image.nrrd(11.96 MB)
lung1_label.nrrd(24.41 KB)
lung1_label_2D.nrrd(953 bytes)
lung2_image.nrrd(16.99 MB)
lung2_label.nrrd(32.64 KB)
lung2_label_2D.nrrd(1.11 KB)
test_wavelet_37x37x37_image.nrrd(38.97 KB)
test_wavelet_37x37x37_label.nrrd(612 bytes)
test_wavelet_37x37x37_label_2D.nrrd(369 bytes)
test_wavelet_64x64x64_image.nrrd(205.50 KB)
test_wavelet_64x64x64_label.nrrd(853 bytes)
test_wavelet_64x64x64_label_2D.nrrd(374 bytes)