CHANGES.rst

Release Notes

Next Release

PyRadiomics 2.1.0

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)

PyRadiomics 2.0.1

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)

PyRadiomics 2.0.0

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)
• Reconfigur 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, #393)

PyRadiomics 1.3.0

Feature Calculation Changes

• Remove feature Sum Variance, as this is mathematically equal to Cluster Tendency. (#300)
• Fix feature formula error in NGTDM (incorrect use of square in Complexity and Contrast). (#351)

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)
• Fix bug in the calculation of eigen values due to machine precision errors. (#355)

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)
• Fix typo in NGTDM documentation. (ea9a6ce)
• Fix some typos in documentation of firstorder - std and gldm - GLN (#369)
• Add additional comments to the code of the Wavelet filter (_swt3). (#375)
• Add references to the new filter functions. (4464d1c)

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)
• Update C extensions: Make python wrapping more similar for different feature classes, simplify calculation of surface area, remove deprecated Numpy C-API references and implement angle-generation in C. (#360)
• Remove Python equivalents of C extensions: Some, but not all C extensions had python equivalents, which calculated equal values but, by using a python-only implementation, are much slower than the C extension. Only advantage is that it would also work when compiling the code fails. Also update the tests to check consistency of the calculated matrices against a baseline file (binary numpy array file) instead of python calculated matrices. (#373)

License

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

PyRadiomics 1.2.0

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 retained 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)

PyRadiomics 1.1.1

Feature Calculation 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)
• 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)
• 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)

New features

• Add forced 2D extraction (as alternative to resampling for handling anisotropy in voxels spacing)
• Enable specification of distances between neighbors for GLCM matrix calculation

(#215)

New Parameters

• force2D, Boolean default False. Set to True to force a by slice texture calculation. Dimension that identifies the 'slice' can be defined in force2Ddimension. If input ROI is already a 2D ROI, features are automatically extracted in 2D.
• force2Ddimension, int, range 0-2, default 0. Specifies the 'slice' dimension for a by-slice feature extraction. Value 0 identifies the 'z' dimension (axial plane feature extraction), and features will be extracted from the xy plane. Similarly, 1 identifies the y dimension (coronal plane) and 2 the x dimension (saggital plane).
• distances, List of integers, default [1]. This specifies the distances between the center voxel and the neighbor, for which angles should be generated.

(#215)

Bug fixes

• 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)
• Change location of parameter schema files. These files are otherwise not included in the wheel distribution. (#221)

Requirements

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

Documentation

version 1.1.1 docs

• 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.

(#216)

Internal API

• 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 :py:func:`~radiomics.setVerbosity`, 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)
• 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 (#216)
• Update reference for citing PyRadiomics (#224)

Cleanups

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

PyRadiomics 1.1.0

New features

• Image normalization. This feature enables the normalization of image intensity values prior to feeding them to the extraction pipeline (i.e. before any other preprocessing steps are performed). Normalization is based on the all gray values contained within the image, not just those defined by the ROI in the mask.
• C Extensions for texture matrix and surface area calculation. These extensions enhance performance of texture matrix calculation associated GLCM, GLRLM and GLSZM features and of surface area calculation. Below shows the decrease in computation time for the 5 test cases included in PyRadiomics. (#158, #200, #202)
  • GLCM 6913 ms -> 3 ms
  • GLRLM 1850 ms -> 10 ms
  • GLSZM 12064 ms -> 58 ms
  • Surface Area 3241 ms -> 1 ms

New Parameters

• additionalInfo Boolean, default True. Enables additional information in the output if set to True. (#190)
• enableCExtensions Boolean, defailt True. Enables enhanced performance for texture matrix calculation using C extensions if set to True. (#202)
• normalize Boolean, default `` False``. If set to true, normalizes image before feeding it into the extraction pipeline. (#209)
• normalizeScale Float, > 0, default 1. Enables scaling of normalized intensities by specified value. (#209)
• removeOutliers Float, > 0, default None. If set, outliers (defined by the value specified) are removed by setting them to the outlier value. Outlier value is defined on the non-scaled values. (#209)

Bug fixes

• Unlink venv only when needed in Circle CI testing (#199)
• Fix datatype error when calling SimpleITK.ResampleImageFilter.SetSize() (only causes error in python 3, #205)

Requirements

• Add requirement for six>=1.10.0, needed to make PyRadiomics compatible with both python 2 and 3.

Documentation

version 1.1.0 docs

• 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). (#187)
• Updated contact information to point to the google groups.
• Updated the classifiers in the setup script to reflect the more advanced status of Pyradiomics. (#193)

Tests

• Add support for multiple python versions and platforms, now including python 2.7, 3.4, 3.5 (32/64bits) for Linux, Windows and Mac. (#183, #191, #199)
• Testing output is upgraded to ensure unique feature names (#195, #197)
• Add test_cmatrices to assert conformity between output from Python and C based texture matrix calculation.

Internal API

• :py:func:`~radiomics.getFeatureClasses` and :py:func:`~radiomics.getInputImageTypes` are moved from Feature Extractor <radiomics-featureextractor-label> to the global radiomics namespace. This enumerates the possible feature classes and filters at initialization of the toolbox, and ensures feature classes are imported at initialization. (#190, #198)
• Python 3 Compatibility. Add support for compatibility with python 2.7 and python >= 3.4. This is achieved using package six.
• Standardize function names for calculating matrices in python and with C extensions to _calculateMatrix and _calculateCMatrix, respectively.
• Make C code consistent with C89 convention. All variables (pointers for python objects) are initialized at top of each block.
• Optimize GLSZM calculation (C extension)
  • 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.
  • Use calloc and free for the temporary array holding the calculated zones.
  • Use char datatype for mask. (signed char in GLSZM).
  • Uses while loops. This allows to reduce the memory usage. Additionally, we observed that with recursive functions it was 'unexpectedly' failing.
  • Optimized search that finds a new index to process in the region growing.

PyRadiomics 1.0.1

New features

• Added 2 commandline scripts ( pyradiomics and pyradiomicsbatch), which enable feature extraction directly from the commandline. For help on usage, run script with “-h” argument. (#188, #194, #196, #205)

Bug fixes

• Fix hardcoded label in shape (#175)
• Fix incorrect axis when deleting empty angles in GLCM (#176)
• 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.(#182)

Requirements

• Revert numpy minimum requirement to 1.9.2. All operations in PyRadiomics are supported by this version, and it is the version used by Slicer. By reverting the minimum required version, installing PyRadiomics in the slicer extension does not cause an update of the numpy package distributed by slicer. (#180)

Documentation

version 1.0.1 docs

• Update on the documentation, reflecting recent changes in the code.
• Add developers and affiliations to ReadMe and documentation (#177)
• Added additional references and updated installation and usage section.

Internal API

• 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).

PyRadiomics 1.0

New features

• Initial Release of PyRadiomics

Work in progress

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

Documentation

• Documentation published at readthedocs

[1]	Haralick R, Shanmugan K, Dinstein I: Textural features for image classification. IEEE Trans Syst Man Cybern 1973:610–621.