Pipeline Modules

This section contains the documentation on the various modules used to define the PyRadiomics pipeline and pre-process the input data. Feature class modules, which contain the feature definitions are documented in the Radiomic Features section.

Additionally, this section contains the documentation for the radiomics.generalinfo module, which provides the additional information about the extraction in the output. This additional information is added to enhance reproducibility of the results.

Finally, this section contains documentation for the global functions, which are used throughout the toolbox (such as logging and the C extensions) and the radiomics.base module, which defines the common interface for the feature classes.

Feature Extractor

class radiomics.featureextractor.RadiomicsFeaturesExtractor(*args, **kwargs)[source]

Wrapper class for calculation of a radiomics signature. At and after initialisation various settings can be used to customize the resultant signature. This includes which classes and features to use, as well as what should be done in terms of preprocessing the image and what images (original and/or filtered) should be used as input.

Then a call to execute() generates the radiomics signature specified by these settings for the passed image and labelmap combination. This function can be called repeatedly in a batch process to calculate the radiomics signature for all image and labelmap combinations.

At initialization, a parameters file can be provided containing all necessary settings. This is done by passing the location of the file as the single argument in the initialization call, without specifying it as a keyword argument. If such a file location is provided, any additional kwargs are ignored. Alternatively, at initialisation, custom settings (NOT enabled image types and/or feature classes) can be provided as keyword arguments, with the setting name as key and its value as the argument value (e.g. binWidth=25). For more information on possible settings and customization, see Customizing the Extraction.

By default, all features in all feature classes are enabled. By default, only Original input image is enabled (No filter applied).

addProvenance(provenance_on=True)[source]

Enable or disable reporting of additional information on the extraction. This information includes toolbox version, enabled input images and applied settings. Furthermore, additional information on the image and region of interest (ROI) is also provided, including original image spacing, total number of voxels in the ROI and total number of fully connected volumes in the ROI.

To disable this, call addProvenance(False).

loadParams(paramsFile)[source]

Parse specified parameters file and use it to update settings, enabled feature(Classes) and image types. For more information on the structure of the parameter file, see Customizing the extraction.

If supplied file does not match the requirements (i.e. unrecognized names or invalid values for a setting), a pykwalify error is raised.

enableAllImageTypes()[source]

Enable all possible image types without any custom settings.

disableAllImageTypes()[source]

Disable all image types.

enableImageTypeByName(imageType, enabled=True, customArgs=None)[source]

Enable or disable specified image type. If enabling image type, optional custom settings can be specified in customArgs.

Current possible image types are:

  • Original: No filter applied
  • Wavelet: Wavelet filtering, yields 8 decompositions per level (all possible combinations of applying either a High or a Low pass filter in each of the three dimensions. See also getWaveletImage()
  • LoG: Laplacian of Gaussian filter, edge enhancement filter. Emphasizes areas of gray level change, where sigma defines how coarse the emphasised texture should be. A low sigma emphasis on fine textures (change over a short distance), where a high sigma value emphasises coarse textures (gray level change over a large distance). See also getLoGImage()
  • Square: Takes the square of the image intensities and linearly scales them back to the original range. Negative values in the original image will be made negative again after application of filter.
  • SquareRoot: Takes the square root of the absolute image intensities and scales them back to original range. Negative values in the original image will be made negative again after application of filter.
  • Logarithm: Takes the logarithm of the absolute intensity + 1. Values are scaled to original range and negative original values are made negative again after application of filter.
  • Exponential: Takes the the exponential, where filtered intensity is e^(absolute intensity). Values are scaled to original range and negative original values are made negative again after application of filter.

For the mathmetical formulas of square, squareroot, logarithm and exponential, see their respective functions in imageoperations (getSquareImage(), getSquareRootImage(), getLogarithmImage() and getExponentialImage(), respectively).

enableImageTypes(**enabledImagetypes)[source]

Enable input images, with optionally custom settings, which are applied to the respective input image. Settings specified here override those in kwargs. The following settings are not customizable:

  • interpolator
  • resampledPixelSpacing
  • padDistance

Updates current settings: If necessary, enables input image. Always overrides custom settings specified for input images passed in inputImages. To disable input images, use enableInputImageByName() or disableAllInputImages() instead.

Parameters:enabledImagetypes – dictionary, key is imagetype (original, wavelet or log) and value is custom settings (dictionary)
enableAllFeatures()[source]

Enable all classes and all features.

Note

Individual features that have been marked “deprecated” are not enabled by this function. They can still be enabled manually by a call to enableFeatureByName(), enableFeaturesByName() or in the parameter file (by specifying the feature by name, not when enabling all features). However, in most cases this will still result only in a deprecation warning.

disableAllFeatures()[source]

Disable all classes.

enableFeatureClassByName(featureClass, enabled=True)[source]

Enable or disable all features in given class.

Note

Individual features that have been marked “deprecated” are not enabled by this function. They can still be enabled manually by a call to enableFeatureByName(), enableFeaturesByName() or in the parameter file (by specifying the feature by name, not when enabling all features). However, in most cases this will still result only in a deprecation warning.

enableFeaturesByName(**enabledFeatures)[source]

Specify which features to enable. Key is feature class name, value is a list of enabled feature names.

To enable all features for a class, provide the class name with an empty list or None as value. Settings for feature classes specified in enabledFeatures.keys are updated, settings for feature classes not yet present in enabledFeatures.keys are added. To disable the entire class, use disableAllFeatures() or enableFeatureClassByName() instead.

execute(imageFilepath, maskFilepath, label=None)[source]

Compute radiomics signature for provide image and mask combination. It comprises of the following steps:

  1. Image and mask are loaded and normalized/resampled if necessary.
  2. Validity of ROI is checked using checkMask(), which also computes and returns the bounding box.
  3. If enabled, provenance information is calculated and stored as part of the result.
  4. Shape features are calculated on a cropped (no padding) version of the original image.
  5. If enabled, resegment the mask based upon the range specified in resegmentRange (default None: resegmentation disabled).
  6. Other enabled feature classes are calculated using all specified image types in _enabledImageTypes. Images are cropped to tumor mask (no padding) after application of any filter and before being passed to the feature class.
  7. The calculated features is returned as collections.OrderedDict.
Parameters:
  • imageFilepath – SimpleITK Image, or string pointing to image file location
  • maskFilepath – SimpleITK Image, or string pointing to labelmap file location
  • label – Integer, value of the label for which to extract features. If not specified, last specified label is used. Default label is 1.
Returns:

dictionary containing calculated signature (“<imageType>_<featureClass>_<featureName>”:value).

loadImage(ImageFilePath, MaskFilePath)[source]

Preprocess the image and labelmap. If ImageFilePath is a string, it is loaded as SimpleITK Image and assigned to image, if it already is a SimpleITK Image, it is just assigned to image. All other cases are ignored (nothing calculated). Equal approach is used for assignment of mask using MaskFilePath.

If normalizing is enabled image is first normalized before any resampling is applied.

If resampling is enabled, both image and mask are resampled and cropped to the tumor mask (with additional padding as specified in padDistance) after assignment of image and mask.

getProvenance(imageFilepath, maskFilepath, mask)[source]

Generates provenance information for reproducibility. Takes the original image & mask filepath, as well as the resampled mask which is passed to the feature classes. Returns a dictionary with keynames coded as “general_info_<item>”. For more information on generated items, see generalinfo

computeFeatures(image, mask, imageTypeName, **kwargs)[source]

Compute signature using image, mask, **kwargs settings.

This function computes the signature for just the passed image (original or derived), it does not preprocess or apply a filter to the passed image. Features / Classes to use for calculation of signature are defined in self._enabledFeatures. See also enableFeaturesByName().

Note

shape descriptors are independent of gray level and therefore calculated separately (handled in execute). In this function, no shape functions are calculated.

getFeatureClassNames()[source]

Returns a list of all possible feature classes.

getFeatureNames(featureClassName)[source]

Returns a list of all possible features in provided featureClass

Image Processing and Filters

radiomics.imageoperations.getBinEdges(binwidth, parameterValues)[source]

Calculate and return the histogram using parameterValues (1D array of all segmented voxels in the image). Parameter binWidth determines the fixed width of each bin. This ensures comparable voxels after binning, a fixed bin count would be dependent on the intensity range in the segmentation.

Returns the bin edges, a list of the edges of the calculated bins, length is N(bins) + 1. Bins are defined such, that the bin edges are equally spaced from zero, and that the leftmost edge \(\leq \min(X_{gl})\).

Example: for a ROI with values ranging from 54 to 166, and a bin width of 25, the bin edges will be [50, 75, 100, 125, 150, 175].

This value can be directly passed to numpy.histogram to generate a histogram or numpy.digitize to discretize the ROI gray values. See also binImage().

References

  • Leijenaar RTH, Nalbantov G, Carvalho S, et al. The effect of SUV discretization in quantitative FDG-PET Radiomics: the need for standardized methodology in tumor texture analysis. Sci Rep. 2015;5(August):11075.
radiomics.imageoperations.binImage(binwidth, parameterMatrix, parameterMatrixCoordinates)[source]

Discretizes the parameterMatrix (matrix representation of the gray levels in the ROI) using the binEdges calculated using getBinEdges(). Only voxels defined by parameterMatrixCoordinates (defining the segmentation) are used for calculation of histogram and subsequently discretized. Voxels outside segmentation are left unchanged.

\(X_{b, i} = \lfloor \frac{X_{gl, i}}{W} \rfloor - \lfloor \frac {\min(X_{gl})}{W} \rfloor + 1\)

Here, \(X_{gl, i}\) and \(X_{b, i}\) are gray level intensities before and after discretization, respectively. \({W}\) is the bin width value (specfied in binWidth parameter). The first part of the formula ensures that the bins are equally spaced from 0, whereas the second part ensures that the minimum gray level intensity inside the ROI after binning is always 1.

If the range of gray level intensities is equally dividable by the binWidth, i.e. \((\max(X_{gl})- \min(X_{gl})) \mod W = 0\), the maximum intensity will be encoded as numBins + 1, therefore the maximum number of gray level intensities in the ROI after binning is number of bins + 1.

Warning

This is different from the assignment of voxels to the bins by numpy.histogram , which has half-open bins, with the exception of the rightmost bin, which means this maximum values are assigned to the topmost bin. numpy.digitize uses half-open bins, including the rightmost bin.

Note

This method is slightly different from the fixed bin size discretization method described by IBSI. The two most notable differences are 1) that PyRadiomics uses a floor division (and adds 1), as opposed to a ceiling division and 2) that in PyRadiomics, bins are always equally spaced from 0, as opposed to equally spaced from the minimum gray level intensity.

radiomics.imageoperations.generateAngles(size, **kwargs)[source]

Generate all possible angles for specified distances in distances in 3D. E.g. for d = 1, 13 angles are generated and for d = 2, 49 angles are generated (representing the 26 connected region for distance 1, and the 98 connected region for distance 2). Angles are generated with the following steps:

  1. All angles for distance = 1 to the maximum distance specified in distances are generated.
  2. Only angles are retained, for which the maximum step size in any dimension (i.e. the infinity norm distance from the center voxel) is present in distances.
  3. “Impossible” angles (where ‘neighbouring’ voxels will always be outside delineation) are deleted.
  4. If force2Dextraction is enabled, all angles defining a step in the force2Ddimension are removed (e.g. if this dimension is 0, all angles that have a non-zero step size at index 0 (z dimension) are removed, resulting in angles that only move in the x and/or y dimension).
Parameters:
  • size – dimensions (z, x, y) of the bounding box of the tumor mask.
  • kwargs

    The following additional parameters can be specified here (default values in brackets):

    • distances [[1]]: List of integers. This specifies the distances between the center voxel and the neighbor, for which angles should be generated.
    • force2D [False]: Boolean, 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 [0]: int, range 0-2. 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). if force2Dextraction is set to False, this parameter has no effect.
Returns:

numpy array with shape (N, 3), where N is the number of unique angles

radiomics.imageoperations.checkMask(imageNode, maskNode, **kwargs)[source]

Checks whether the Region of Interest (ROI) defined in the mask size and dimensions match constraints, specified in settings. The following checks are performed.

  1. Check whether the mask corresponds to the image (i.e. has a similar size, spacing, direction and origin). N.B. This check is performed by SimpleITK, if it fails, an error is logged, with additional error information from SimpleITK logged with level DEBUG (i.e. logging-level has to be set to debug to store this information in the log file). The tolerance can be increased using the geometryTolerance parameter. Alternatively, if the correctMask parameter is True, PyRadiomics will check if the mask contains a valid ROI (inside image physical area) and if so, resample the mask to image geometry. See Settings for more info.
  2. Check if the label is present in the mask
  3. Count the number of dimensions in which the size of the ROI > 1 (i.e. does the ROI represent a single voxel (0), a line (1), a surface (2) or a volume (3)) and compare this to the minimum number of dimension required (specified in minimumROIDimensions).
  4. Optional. Check if there are at least N voxels in the ROI. N is defined in minimumROISize, this test is skipped if minimumROISize = None.

This function returns a tuple of two items. The first item (if not None) is the bounding box of the mask. The second item is the mask that has been corrected by resampling to the input image geometry (if that resampling was successful).

If a check fails, an error is logged and a (None,None) tuple is returned. No features will be extracted for this mask. If the mask passes all tests, this function returns the bounding box, which is used in the cropToTumorMask() function.

The bounding box is calculated during (1.) and used for the subsequent checks. The bounding box is calculated by SimpleITK.LabelStatisticsImageFilter() and returned as a tuple of indices: (L_x, U_x, L_y, U_y, L_z, U_z), where ‘L’ and ‘U’ are lower and upper bound, respectively, and ‘x’, ‘y’ and ‘z’ the three image dimensions.

By reusing the bounding box calculated here, calls to SimpleITK.LabelStatisticsImageFilter() are reduced, improving performance.

Uses the following settings:

  • minimumROIDimensions [1]: Integer, range 1-3, specifies the minimum dimensions (1D, 2D or 3D, respectively). Single-voxel segmentations are always excluded.
  • minimumROISize [None]: Integer, > 0, specifies the minimum number of voxels required. Test is skipped if this parameter is set to None.

Note

If the first check fails there are generally 2 possible causes:

  1. The image and mask are matched, but there is a slight difference in origin, direction or spacing. The exact cause, difference and used tolerance are stored with level DEBUG in a log (if enabled). For more information on setting up logging, see “setting up logging” and the helloRadiomics examples (located in the pyradiomics/examples folder). This problem can be fixed by changing the global tolerance (geometryTolerance parameter) or enabling mask correction (correctMask parameter).
  2. The image and mask do not match, but the ROI contained within the mask does represent a physical volume contained within the image. If this is the case, resampling is needed to ensure matching geometry between image and mask before features can be extracted. This can be achieved by enabling mask correction using the correctMask parameter.
radiomics.imageoperations.cropToTumorMask(imageNode, maskNode, boundingBox, padDistance=0)[source]

Create a sitkImage of the segmented region of the image based on the input label.

Create a sitkImage of the labelled region of the image, cropped to have a cuboid shape equal to the ijk boundaries of the label.

Parameters:
  • boundingBox – The bounding box used to crop the image. This is the bounding box as returned by checkMask().
  • label – [1], value of the label, onto which the image and mask must be cropped.
Returns:

Cropped image and mask (SimpleITK image instances).

radiomics.imageoperations.resampleImage(imageNode, maskNode, resampledPixelSpacing, interpolator=3, label=1, padDistance=5)[source]

Resamples image and mask to the specified pixel spacing (The default interpolator is Bspline).

Resampling can be enabled using the settings ‘interpolator’ and ‘resampledPixelSpacing’ in the parameter file or as part of the settings passed to the feature extractor. See also feature extractor.

‘imageNode’ and ‘maskNode’ are SimpleITK Objects, and ‘resampledPixelSpacing’ is the output pixel spacing (sequence of 3 elements).

If only in-plane resampling is required, set the output pixel spacing for the out-of-plane dimension (usually the last dimension) to 0. Spacings with a value of 0 are replaced by the spacing as it is in the original mask.

Only part of the image and labelmap are resampled. The resampling grid is aligned to the input origin, but only voxels covering the area of the image ROI (defined by the bounding box) and the padDistance are resampled. This results in a resampled and partially cropped image and mask. Additional padding is required as some filters also sample voxels outside of segmentation boundaries. For feature calculation, image and mask are cropped to the bounding box without any additional padding, as the feature classes do not need the gray level values outside the segmentation.

The resampling grid is calculated using only the input mask. Even when image and mask have different directions, both the cropped image and mask will have the same direction (equal to direction of the mask). Spacing and size are determined by settings and bounding box of the ROI.

Note

Before resampling the bounds of the non-padded ROI are compared to the bounds. If the ROI bounding box includes areas outside of the physical space of the image, an error is logged and (None, None) is returned. No features will be extracted. This enables the input image and mask to have different geometry, so long as the ROI defines an area within the image.

Note

The additional padding is adjusted, so that only the physical space within the mask is resampled. This is done to prevent resampling outside of the image. Please note that this assumes the image and mask to image the same physical space. If this is not the case, it is possible that voxels outside the image are included in the resampling grid, these will be assigned a value of 0. It is therefore recommended, but not enforced, to use an input mask which has the same or a smaller physical space than the image.

radiomics.imageoperations.normalizeImage(image, scale=1, outliers=None)[source]

Normalizes the image 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.

\(f(x) = \frac{s(x - \mu_x)}{\sigma_x}\)

Where:

  • \(x\) and \(f(x)\) are the original and normalized intensity, respectively.
  • \(\mu_x\) and \(\sigma_x\) are the mean and standard deviation of the image instensity values.
  • \(s\) is an optional scaling defined by scale. By default, it is set to 1.

Optionally, outliers can be removed, in which case values for which \(x > \mu_x + n\sigma_x\) or \(x < \mu_x - n\sigma_x\) are set to \(\mu_x + n\sigma_x\) and \(\mu_x - n\sigma_x\), respectively. Here, \(n>0\) and defined by outliers. This, in turn, is controlled by the removeOutliers parameter. Removal of outliers is done after the values of the image are normalized, but before scale is applied.

radiomics.imageoperations.resegmentMask(imageNode, maskNode, resegmentRange, label=1)[source]

Resegment the Mask based on the range specified in resegmentRange. All voxels with a gray level outside the range specified are removed from the mask. The resegmented mask is therefore always equal or smaller in size than the original mask. The resegemented mask is then checked for size (as specified by parameter minimumROISize, defaults to minimum size 1). When this check fails, an error is logged and maskArray is reset to the original mask.

radiomics.imageoperations.getOriginalImage(inputImage, **kwargs)[source]

This function does not apply any filter, but returns the original image. This function is needed to dynamically expose the original image as a valid image type.

Returns:Yields original image, ‘original’ and kwargs
radiomics.imageoperations.getLoGImage(inputImage, **kwargs)[source]

Applies a Laplacian of Gaussian filter to the input image and yields a derived image for each sigma value specified.

Following settings are possible:

  • sigma: List of floats or integers, must be greater than 0. Sigma values to use for the filter (determines coarseness).

Warning

Setting for sigma must be provided. If omitted, no LoG image features are calculated and the function will return an empty dictionary.

Returned filter name reflects LoG settings: log-sigma-<sigmaValue>-3D.

Returns:Yields log filtered image for each specified sigma, corresponding image type name and kwargs (customized settings).
radiomics.imageoperations.getWaveletImage(inputImage, **kwargs)[source]

Applies wavelet filter to the input image and yields the decompositions and the approximation.

Following settings are possible:

  • start_level [0]: integer, 0 based level of wavelet which should be used as first set of decompositions from which a signature is calculated
  • level [1]: integer, number of levels of wavelet decompositions from which a signature is calculated.
  • wavelet [“coif1”]: string, type of wavelet decomposition. Enumerated value, validated against possible values present in the pyWavelet.wavelist(). Current possible values (pywavelet version 0.4.0) (where an aditional number is needed, range of values is indicated in []):
    • haar
    • dmey
    • sym[2-20]
    • db[1-20]
    • coif[1-5]
    • bior[1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5, 6.8]
    • rbio[1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5, 6.8]

Returned filter name reflects wavelet type: wavelet[level]-<decompositionName>

N.B. only levels greater than the first level are entered into the name.

Returns:Yields each wavelet decomposition and final approximation, corresponding imaget type name and kwargs (customized settings).
radiomics.imageoperations.getSquareImage(inputImage, **kwargs)[source]

Computes the square of the image intensities.

Resulting values are rescaled on the range of the initial original image and negative intensities are made negative in resultant filtered image.

\(f(x) = (cx)^2,\text{ where } c=\displaystyle\frac{1}{\sqrt{\max(|x|)}}\)

Where \(x\) and \(f(x)\) are the original and filtered intensity, respectively.

Returns:Yields square filtered image, ‘square’ and kwargs (customized settings).
radiomics.imageoperations.getSquareRootImage(inputImage, **kwargs)[source]

Computes the square root of the absolute value of image intensities.

Resulting values are rescaled on the range of the initial original image and negative intensities are made negative in resultant filtered image.

\(f(x) = \left\{ {\begin{array}{lcl} \sqrt{cx} & \mbox{for} & x \ge 0 \\ -\sqrt{-cx} & \mbox{for} & x < 0\end{array}} \right.,\text{ where } c=\max(|x|)\)

Where \(x\) and \(f(x)\) are the original and filtered intensity, respectively.

Returns:Yields square root filtered image, ‘squareroot’ and kwargs (customized settings).
radiomics.imageoperations.getLogarithmImage(inputImage, **kwargs)[source]

Computes the logarithm of the absolute value of the original image + 1.

Resulting values are rescaled on the range of the initial original image and negative intensities are made negative in resultant filtered image.

\(f(x) = \left\{ {\begin{array}{lcl} c\log{(x + 1)} & \mbox{for} & x \ge 0 \\ -c\log{(-x + 1)} & \mbox{for} & x < 0\end{array}} \right. \text{, where } c=\frac{\max(|x|)}{\log(\max(|x|) + 1)}\)

Where \(x\) and \(f(x)\) are the original and filtered intensity, respectively.

Returns:Yields logarithm filtered image, ‘logarithm’ and kwargs (customized settings)
radiomics.imageoperations.getExponentialImage(inputImage, **kwargs)[source]

Computes the exponential of the original image.

Resulting values are rescaled on the range of the initial original image.

\(f(x) = e^{cx},\text{ where } c=\displaystyle\frac{\log(\max(|x|))}{\max(|x|)}\)

Where \(x\) and \(f(x)\) are the original and filtered intensity, respectively.

Returns:Yields exponential filtered image, ‘exponential’ and kwargs (customized settings)

General Info Module

class radiomics.generalinfo.GeneralInfo(imagePath, maskPath, resampledMask, settings, enabledImageTypes)[source]
execute()[source]

Return a dictionary containing all general info items. Format is <info_item>:<value>, where the type of the value is preserved. For CSV format, this will result in conversion to string and quotes where necessary, for JSON, the values will be interpreted and stored as JSON strings.

getBoundingBoxValue()[source]

Calculate and return the boundingbox extracted using the specified label. Elements 0, 1 and 2 are the x, y and z coordinates of the lower bound, respectively. Elements 3, 4 and 5 are the size of the bounding box in x, y and z direction, respectively.

Values are based on the resampledMask.

getGeneralSettingsValue()[source]

Return a string representation of the general settings. Format is {<settings_name>:<value>, ...}.

getImageHashValue()[source]

Returns the sha1 hash of the image. This enables checking whether two images are the same, regardless of the file location.

If the reading of the image fails, an empty string is returned.

getImageSpacingValue()[source]

Returns the original spacing (before any resampling) of the image.

If the reading of the image fails, an empty string is returned.

getEnabledImageTypesValue()[source]

Return a string representation of the enabled image types and any custom settings for each image type. Format is {<imageType_name>:{<setting_name>:<value>, ...}, ...}.

getMaskHashValue()[source]

Returns the sha1 hash of the mask. This enables checking whether two masks are the same, regardless of the file location.

If the reading of the mask fails, an empty string is returned. Uses the original mask, specified in maskPath.

getVersionValue()[source]

Return the current version of this package.

getVolumeNumValue()[source]

Calculate and return the number of zones within the mask for the specified label. A zone is defined as a group of connected neighbours that are segmented with the specified label, and a voxel is considered a neighbour using 26-connectedness for 3D and 8-connectedness for 2D.

Values are based on the resampledMask.

getVoxelNumValue()[source]

Calculate and return the number of voxels that have been segmented using the specified label.

Values are based on the resampledMask.

Feature Class Base

class radiomics.base.RadiomicsFeaturesBase(inputImage, inputMask, **kwargs)[source]

Bases: object

This is the abstract class, which defines the common interface for the feature classes. All feature classes inherit (directly of indirectly) from this class.

At initialization, image and labelmap are passed as SimpleITK image objects (inputImage and inputMask, respectively.) The motivation for using SimpleITK images as input is to keep the possibility of reusing the optimized feature calculators implemented in SimpleITK in the future. If either the image or the mask is None, initialization fails and a warning is logged (does not raise an error).

Logging is set up using a child logger from the parent ‘radiomics’ logger. This retains the toolbox structure in the generated log. The child logger is named after the module containing the feature class (e.g. ‘radiomics.glcm’).

Any pre calculations needed before the feature functions are called can be added by overriding the _initSegmentBasedCalculation function, which prepares the input for feature extraction. If image discretization is needed, this can be implemented by adding a call to _applyBinning to this initialization function, which also instantiates coefficients holding the maximum (‘Ng’) and unique (‘GrayLevels’) that can be found inside the ROI after binning. This function also instantiates the matrix variable, which holds the discretized image (the imageArray variable will hold only original gray levels).

The following variables are instantiated at initialization:

  • kwargs: dictionary holding all customized settings passed to this feature class.
  • binWidth: bin width, as specified in **kwargs. If key is not present, a default value of 25 is used.
  • label: label value of Region of Interest (ROI) in labelmap. If key is not present, a default value of 1 is used.
  • featureNames: list containing the names of features defined in the feature class. See getFeatureNames()
  • inputImage: SimpleITK image object of the input image (dimensions x, y, z)

The following variables are instantiated by the _initSegmentBasedCalculation function:

  • inputMask: SimpleITK image object of the input labelmap (dimensions x, y, z)
  • imageArray: numpy array of the gray values in the input image (dimensions z, y, x)
  • maskArray: numpy boolean array with elements set to True where labelmap = label, False otherwise, (dimensions z, y, x).
  • labelledVoxelCoordinates: tuple of 3 numpy arrays containing the z, x and y coordinates of the voxels included in the ROI, respectively. Length of each array is equal to total number of voxels inside ROI.
  • boundingBoxSize: tuple of 3 integers containing the z, x and y sizes of the ROI bounding box, respectively.
  • matrix: copy of the imageArray variable, with gray values inside ROI discretized using the specified binWidth. This variable is only instantiated if a call to _applyBinning is added to an override of _initSegmentBasedCalculation in the feature class.

Note

Although some variables listed here have similar names to customization settings, they do not represent all the possible settings on the feature class level. These variables are listed here to help developers develop new feature classes, which make use of these variables. For more information on customization, see Customizing the Extraction, which includes a comprehensive list of all possible settings, including default values and explanation of usage.

enableFeatureByName(featureName, enable=True)[source]

Enables or disables feature specified by featureName. If feature is not present in this class, a lookup error is raised. enable specifies whether to enable or disable the feature.

enableAllFeatures()[source]

Enables all features found in this class for calculation.

Note

Features that have been marked “deprecated” are not enabled by this function. They can still be enabled manually by a call to enableFeatureByName(), enableFeaturesByName() or in the parameter file (by specifying the feature by name, not when enabling all features). However, in most cases this will still result only in a deprecation warning.

disableAllFeatures()[source]

Disables all features. Additionally resets any calculated features.

classmethod getFeatureNames()[source]

Dynamically enumerates features defined in the feature class. Features are identified by the get<Feature>FeatureValue signature, where <Feature> is the name of the feature (unique on the class level).

Found features are returned as a dictionary of the feature names, where the value True if the feature is deprecated, False otherwise ({<Feature1>:<deprecated>, <Feature2>:<deprecated>, ...}).

This function is called at initialization, found features are stored in the featureNames variable.

calculateFeatures()[source]

Calculates all features enabled in enabledFeatures. A feature is enabled if it’s key is present in this dictionary and it’s value is True.

Calculated values are stored in the featureValues dictionary, with feature name as key and the calculated feature value as value. If an exception is thrown during calculation, the error is logged, and the value is set to NaN.

Global Toolbox Functions

radiomics.cMatsEnabled()[source]

Returns a boolean indicating whether or not the C extensions are enabled. This function is called by the feature classes to switch between C-enhanced calculation and full python mode.

radiomics.deprecated(func)[source]

Decorator function to mark functions as deprecated. This is used to ensure deprecated feature functions are not added to the enabled features list when enabling ‘all’ features.

radiomics.enableCExtensions(enabled=True)[source]

By default, calculation of GLCM, GLRLM and GLSZM is done in C, using extension _cmatrices.py

If an error occurs during loading of this extension, a warning is logged and the extension is disabled, matrices are then calculated in python. The C extension can be disabled by calling this function as enableCExtensions(False), which forces the calculation of the matrices to full-python mode.

Re-enabling use of C implementation is also done by this function, but if the extension is not loaded correctly, a warning is logged and matrix calculation is forced to full-python mode.

radiomics.getFeatureClasses()[source]

Iterates over all modules of the radiomics package using pkgutil and subsequently imports those modules.

Return a dictionary of all modules containing featureClasses, with modulename as key, abstract class object of the featureClass as value. Assumes only one featureClass per module

This is achieved by inspect.getmembers. Modules are added if it contains a member that is a class, with name starting with ‘Radiomics’ and is inherited from radiomics.base.RadiomicsFeaturesBase.

This iteration only runs once (at initialization of toolbox), subsequent calls return the dictionary created by the first call.

radiomics.getImageTypes()[source]

Returns a list of possible image types (i.e. the possible filters and the “Original”, unfiltered image type). This function finds the image types dynamically by matching the signature (“get<imageType>Image”) against functions defined in imageoperations. Returns a list containing available image type names (<imageType> part of the corresponding function name).

This iteration only occurs once, at initialization of the toolbox. Found results are stored and returned on subsequent calls.

radiomics.getParameterValidationFiles()[source]

Returns file locations for the parameter schema and custom validation functions, which are needed when validating a parameter file using PyKwalify.core. This functions returns a tuple with the file location of the schema as first and python script with custom validation functions as second element.

radiomics.getProgressReporter(*args, **kwargs)[source]

This function returns an instance of the progressReporter, if it is set and the logging level is defined at level INFO or DEBUG. In all other cases a dummy progress reporter is returned.

To enable progress reporting, the progressReporter variable should be set to a class object (NOT an instance), which fits the following signature:

  1. Accepts an iterable as the first positional argument and a keyword argument (‘desc’) specifying a label to display
  2. Can be used in a ‘with’ statement (i.e. exposes a __enter__ and __exit__ function)
  3. Is iterable (i.e. at least specifies an __iter__ function, which iterates over the iterable passed at initialization).

It is also possible to create your own progress reporter. To achieve this, additionally specify a function __next__, and have the __iter__ function return self. The __next__ function takes no arguments and returns a call to the __next__ function of the iterable (i.e. return self.iterable.__next__()). Any prints/progress reporting calls can then be inserted in this function prior to the return statement.

radiomics.getTestCase(testCase, repoDirectory=None)[source]

This function provides an image and mask for testing PyRadiomics. One of five test cases can be selected:

  • brain1
  • brain2
  • breast1
  • lung1
  • lung2

If the repository is available locally (including all five test cases, the path to the root folder of the repository can be specified in repoDirectory, preventing unnecessary downloads. If the repository is not found, or the repository does not contain the requested test case, PyRadiomics checks if it is run in development mode (directly from the source code in the repository), and if so, if it can find the test case relative to it’s own location.

If the requested test case could not be found in the repository, PyRadiomics downloads the test case from the GitHub repository and stores it in temporary files. If the test case was already downloaded, this is returned instead.

Returns a tuple of two strings: (path/to/image.nrrd, path/to/mask.nrrd)

radiomics.setVerbosity(level)[source]

Change the amount of information PyRadiomics should print out during extraction. The lower the level, the more information is printed to the output (stderr).

Using the level (Python defined logging levels) argument, the following levels are possible:

  • 60: Quiet mode, no messages are printed to the stderr
  • 50: Only log messages of level “CRITICAL” are printed
  • 40: Log messages of level “ERROR” and up are printed
  • 30: Log messages of level “WARNING” and up are printed
  • 20: Log messages of level “INFO” and up are printed
  • 10: Log messages of level “DEBUG” and up are printed (i.e. all log messages)

By default, the radiomics logger is set to level “INFO” and the stderr handler to level “WARNING”. Therefore a log storing the extraction log messages from level “INFO” and up can be easily set up by adding an appropriate handler to the radiomics logger, while the output to stderr will still only contain warnings and errors.

Note

This function assumes the handler added to the radiomics logger at initialization of the toolbox is not removed from the logger handlers and therefore remains the first handler.

Note

This does not affect the level of the logger itself (e.g. if verbosity level = 3, log messages with DEBUG level can still be stored in a log file if an appropriate handler is added to the logger and the logging level of the logger has been set to the correct level. Exception: In case the verbosity is set to DEBUG, the level of the logger is also lowered to DEBUG. If the verbosity level is then raised again, the logger level will remain DEBUG.