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.
RadiomicsFeatureExtractor
(*args, **kwargs)[source]¶ Bases:
object
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 (string pointing to yaml or json structured file) or dictionary can be provided containing all necessary settings (top level containing keys “setting”, “imageType” and/or “featureClass). This is done by passing it as the first positional argument. If no positional argument is supplied, or the argument is not either a dictionary or a string pointing to a valid file, defaults will be applied. Moreover, 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
). Settings specified here will override those in the parameter file/dict/default settings. 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.
-
loadJSONParams
(JSON_configuration)[source]¶ Pars JSON structured configuration string 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 string does not match the requirements (i.e. unrecognized names or invalid values for a setting), a pykwalify error is raised.
-
execute
(imageFilepath, maskFilepath, label=None, label_channel=None, voxelBased=False)[source]¶ Compute radiomics signature for provide image and mask combination. It comprises of the following steps:
- Image and mask are loaded and normalized/resampled if necessary.
- Validity of ROI is checked using
checkMask()
, which also computes and returns the bounding box. - If enabled, provenance information is calculated and stored as part of the result. (Not available in voxel-based extraction)
- Shape features are calculated on a cropped (no padding) version of the original image. (Not available in voxel-based extraction)
- If enabled, resegment the mask based upon the range specified in
resegmentRange
(default None: resegmentation disabled). - 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. - 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.
- label_channel – Integer, index of the channel to use when maskFilepath yields a SimpleITK.Image with a vector pixel type. Default index is 0.
- voxelBased – Boolean, default False. If set to true, a voxel-based extraction is performed, segment-based otherwise.
Returns: dictionary containing calculated signature (“<imageType>_<featureClass>_<featureName>”:value). In case of segment-based extraction, value type for features is float, if voxel-based, type is SimpleITK.Image. Type of diagnostic features differs, but can always be represented as a string.
-
static
loadImage
(ImageFilePath, MaskFilePath, generalInfo=None, **kwargs)[source]¶ Load and pre-process 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 toimage
. All other cases are ignored (nothing calculated). Equal approach is used for assignment ofmask
using MaskFilePath. If necessary, a segmentation object (i.e. mask volume with vector-image type) is then converted to a labelmap (=scalar image type). Data type is forced to UInt32. See alsogetMask()
.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.
Parameters: - ImageFilePath – SimpleITK.Image object or string pointing to SimpleITK readable file representing the image to use.
- MaskFilePath – SimpleITK.Image object or string pointing to SimpleITK readable file representing the mask to use.
- generalInfo – GeneralInfo Object. If provided, it is used to store diagnostic information of the pre-processing.
- kwargs – Dictionary containing the settings to use for this particular image type.
Returns: 2 SimpleITK.Image objects representing the loaded image and mask, respectively.
-
computeShape
(image, mask, boundingBox, **kwargs)[source]¶ Calculate the shape (2D and/or 3D) features for the passed image and mask.
Parameters: - image – SimpleITK.Image object representing the image used
- mask – SimpleITK.Image object representing the mask used
- boundingBox – The boundingBox calculated by
checkMask()
, i.e. a tuple with lower (even indices) and upper (odd indices) bound of the bounding box for each dimension. - kwargs – Dictionary containing the settings to use.
Returns: collections.OrderedDict containing the calculated shape features. If no features are calculated, an empty OrderedDict will be returned.
-
computeFeatures
(image, mask, imageTypeName, **kwargs)[source]¶ Compute signature using image, mask and **kwargs settings.
This function computes the signature for just the passed image (original or derived), it does not pre-process or apply a filter to the passed image. Features / Classes to use for calculation of signature are defined in
self.enabledFeatures
. See alsoenableFeaturesByName()
.Parameters: - image – The cropped (and optionally filtered) SimpleITK.Image object representing the image used
- mask – The cropped SimpleITK.Image object representing the mask used
- imageTypeName – String specifying the filter applied to the image, or “original” if no filter was applied.
- kwargs – Dictionary containing the settings to use for this particular image type.
Returns: collections.OrderedDict containing the calculated features for all enabled classes. If no features are calculated, an empty OrderedDict will be returned.
Note
shape descriptors are independent of gray level and therefore calculated separately (handled in execute). In this function, no shape features are calculated.
-
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.
- Gradient: Returns the gradient magnitude.
- LBP2D: Calculates and returns a local binary pattern applied in 2D.
- LBP3D: Calculates and returns local binary pattern maps applied in 3D using spherical harmonics. Last returned image is the corresponding kurtosis map.
For the mathmetical formulas of square, squareroot, logarithm and exponential, see their respective functions in imageoperations (
getSquareImage()
,getSquareRootImage()
,getLogarithmImage()
,getExponentialImage()
,getGradientImage()
,getLBP2DImage()
andgetLBP3DImage()
, 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()
ordisableAllInputImages()
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.
-
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()
orenableFeatureClassByName()
instead.
-
Image Processing and Filters¶
-
radiomics.imageoperations.
getMask
(mask, **kwargs)[source]¶ Function to get the correct mask. Includes enforcing a correct pixel data type (UInt32).
Also supports extracting the mask for a segmentation (stored as SimpleITK Vector image) if necessary. In this case, the mask at index
label_channel
is extracted. The resulting 3D volume is then treated as it were a scalar input volume (i.e. with the region of interest defined by voxels with value matchinglabel
).Note
If only one or non-overlapping Segments are defined when using 3D Slicer, it may be the case that it is stored as a labelmap (i.e. only 1
label_channel
, with different segmentations identified by different values forlabel
). This is easy to check by loading the mask as a SimpleITK image and checking the GetNumberOfComponentsPerPixel(), if the return value is1
, it is a label map (i.e. uselabel
), otherwise it is a VectorImage (i.e. uselabel_channel
).Finally, checks if the mask volume contains an ROI identified by
label
. Raises a value error if the label is not present (including a list of valid labels found).Parameters: - mask – SimpleITK Image object representing the mask. Can be a vector image to allow for overlapping masks.
- kwargs – keyword arguments. If argument
label_channel
is present, this is used to select the channel. Otherwise label_channel0
is assumed.
Returns: SimpleITK.Image with pixel type UInt32 representing the mask volume
-
radiomics.imageoperations.
getBinEdges
(parameterValues, **kwargs)[source]¶ Calculate and return the histogram using parameterValues (1D array of all segmented voxels in the image).
Fixed bin width:
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})\). These bin edges represent the half-open ranges of each bin \([\text{lower_edge}, \text{upper_edge})\) and result in gray value discretization as follows:
\[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.In the case where the maximum gray level intensity is equally dividable by the binWidth, i.e. \(\max(X_{gl}) \mod W = 0\), this will result in that maximum gray level being assigned to bin \([\max(X_{gl}), \max(X_{gl}) + W)\), which is consistent with numpy.digitize, but different from the behaviour of numpy.histogram, where the final bin has a closed range, including the maximum gray level, i.e. \([\max(X_{gl}) - W, \max(X_{gl})]\).
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.
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 ornumpy.digitize
to discretize the ROI gray values. See alsobinImage()
.Fixed bin Count:
\[\begin{split}X_{b, i} = \left\{ {\begin{array}{lcl} \lfloor N_b\frac{(X_{gl, i} - \min(X_{gl})}{\max(X_{gl}) - \min(X_{gl})} \rfloor + 1 & \mbox{for} & X_{gl, i} < \max(X_{gl}) \\ N_b & \mbox{for} & X_{gl, i} = \max(X_{gl}) \end{array}} \right.\end{split}\]Here, \(N_b\) is the number of bins to use, as defined in
binCount
.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
(parameterMatrix, parameterMatrixCoordinates=None, **kwargs)[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.
-
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.
- 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 thecorrectMask
parameter isTrue
, 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. - Check if the label is present in the mask
- 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
). - Optional. Check if there are at least N voxels in the ROI. N is defined in
minimumROISize
, this test is skipped ifminimumROISize = None
.
This function returns a tuple of two items. The first item 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, a ValueError is raised. 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:
- 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). - 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.
- 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
-
radiomics.imageoperations.
cropToTumorMask
(imageNode, maskNode, boundingBox, **kwargs)[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).
- boundingBox – The bounding box used to crop the image. This is the bounding box as returned by
-
radiomics.imageoperations.
resampleImage
(imageNode, maskNode, **kwargs)[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, **kwargs)[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 segmentation.
\(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 theremoveOutliers
parameter. Removal of outliers is done after the values of the image are normalized, but beforescale
is applied.
-
radiomics.imageoperations.
resegmentMask
(imageNode, maskNode, **kwargs)[source]¶ Resegment the Mask based on the range specified by the threshold(s) in
resegmentRange
. Either 1 or 2 thresholds can be defined. In case of 1 threshold, all values equal to or higher than that threshold are included. If there are 2 thresholds, all voxels with a value inside the closed-range defined by these thresholds is included (i.e. a voxels is included if \(T_{lower} \leq X_gl \leq T_{upper}\)). The resegmented mask is therefore always equal or smaller in size than the original mask. In the case where either resegmentRange or resegmentMode contains illigal values, a ValueError is raised.There are 3 modes for defining the threshold:
- absolute (default): The values in resegmentRange define as absolute values (i.e. corresponding to the gray values in the image
- relative: The values in resegmentRange define the threshold as relative to the maximum value found in the ROI. (e.g. 0.5 indicates a threshold at 50% of maximum gray value)
- sigma: The threshold is defined as the number of sigma from the mean. (e.g. resegmentRange [-3, 3] will include all voxels that have a value that differs 3 or less standard deviations from the mean).
-
radiomics.imageoperations.
getOriginalImage
(inputImage, inputMask, **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, inputMask, **kwargs)[source]¶ Applies a Laplacian of Gaussian filter to the input image and yields a derived image for each sigma value specified.
A Laplacian of Gaussian image is obtained by convolving the image with the second derivative (Laplacian) of a Gaussian kernel.
The Gaussian kernel is used to smooth the image and is defined as
\[G(x, y, z, \sigma) = \frac{1}{(\sigma \sqrt{2 \pi})^3}e^{-\frac{x^2 + y^2 + z^2}{2\sigma^2}}\]The Gaussian kernel is convolved by the laplacian kernel \(\nabla^2G(x, y, z)\), which is sensitive to areas with rapidly changing intensities, enhancing edges. The width of the filter in the Gaussian kernel is determined by \(\sigma\) and can be used to emphasize more fine (low \(\sigma\) values) or coarse (high \(\sigma\) values) textures.
Warning
The LoG filter implemented in PyRadiomics is a 3D LoG filter, and therefore requires 3D input. Features using a single slice (2D) segmentation can still be extracted, but the input image must be a 3D image, with a minimum size in all dimensions \(\geq \sigma\). If input image is too small, a warning is logged and \(\sigma\) value is skipped. Moreover, the image size must be at least 4 voxels in each dimensions, if this constraint is not met, no LoG derived images can be generated.
Following settings are possible:
- sigma: List of floats or integers, must be greater than 0. Filter width (mm) to use for the Gaussian kernel (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.
References:
- SimpleITK Doxygen documentation
- ITK Doxygen documentation
- https://en.wikipedia.org/wiki/Blob_detection#The_Laplacian_of_Gaussian
Returns: Yields log filtered image for each specified sigma, corresponding image type name and kwargs
(customized settings).
-
radiomics.imageoperations.
getWaveletImage
(inputImage, inputMask, **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, inputMask, **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, inputMask, **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, inputMask, **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, inputMask, **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)
-
radiomics.imageoperations.
getGradientImage
(inputImage, inputMask, **kwargs)[source]¶ Compute and return the Gradient Magnitude in the image. By default, takes into account the image spacing, this can be switched off by specifying
gradientUseSpacing = False
.References:
-
radiomics.imageoperations.
getLBP2DImage
(inputImage, inputMask, **kwargs)[source]¶ Compute and return the Local Binary Pattern (LBP) in 2D. If
force2D
is set to false (= feature extraction in 3D) a warning is logged, as this filter processes the image in a by-slice operation. The plane in which the LBP is applied can be controlled by theforce2Ddimension
parameter (see alsogenerateAngles()
).Following settings are possible (in addition to
force2Ddimension
):lbp2DRadius
[1]: Float, specifies the radius in which the neighbours should be sampledlbp2DSamples
[9]: Integer, specifies the number of samples to uselbp2DMethod
[‘uniform’]: String, specifies the method for computing the LBP to use.
For more information see scikit documentation
Returns: Yields LBP filtered image, ‘lbp-2D’ and kwargs
(customized settings)Note
LBP can often return only a very small number of different gray levels. A customized bin width is often needed.
Warning
Requires package
scikit-image
to function. If not available, this filter logs a warning and does not yield an image.References:
- T. Ojala, M. Pietikainen, and D. Harwood (1994), “Performance evaluation of texture measures with classification based on Kullback discrimination of distributions”, Proceedings of the 12th IAPR International Conference on Pattern Recognition (ICPR 1994), vol. 1, pp. 582 - 585.
- T. Ojala, M. Pietikainen, and D. Harwood (1996), “A Comparative Study of Texture Measures with Classification Based on Feature Distributions”, Pattern Recognition, vol. 29, pp. 51-59.
-
radiomics.imageoperations.
getLBP3DImage
(inputImage, inputMask, **kwargs)[source]¶ Compute and return the Local Binary Pattern (LBP) in 3D using spherical harmonics. If
force2D
is set to true (= feature extraction in 2D) a warning is logged.LBP is only calculated for voxels segmented in the mask
Following settings are possible:
lbp3DLevels
[2]: integer, specifies the the number of levels in spherical harmonics to use.lbp3DIcosphereRadius
[1]: Float, specifies the radius in which the neighbours should be sampledlbp3DIcosphereSubdivision
[1]: Integer, specifies the number of subdivisions to apply in the icosphere
Returns: Yields LBP filtered image for each level, ‘lbp-3D-m<level>’ and kwargs
(customized settings). Additionally yields the kurtosis image, ‘lbp-3D-k’ andkwargs
.Note
LBP can often return only a very small number of different gray levels. A customized bin width is often needed.
Warning
Requires package
scipy
andtrimesh
to function. If not available, this filter logs a warning and does not yield an image.References:
- Banerjee, J, Moelker, A, Niessen, W.J, & van Walsum, T.W. (2013), “3D LBP-based rotationally invariant region description.” In: Park JI., Kim J. (eds) Computer Vision - ACCV 2012 Workshops. ACCV 2012. Lecture Notes in Computer Science, vol 7728. Springer, Berlin, Heidelberg. doi:10.1007/978-3-642-37410-4_3
General Info Module¶
-
class
radiomics.generalinfo.
GeneralInfo
[source]¶ Bases:
object
-
getGeneralInfo
()[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.
-
addStaticElements
()[source]¶ Adds the following elements to the general info:
- Version: current version of PyRadiomics
- NumpyVersion: version of numpy used
- SimpleITKVersion: version SimpleITK used
- PyWaveletVersion: version of PyWavelet used
- PythonVersion: version of the python interpreter running PyRadiomics
-
addImageElements
(image, prefix='original')[source]¶ Calculates provenance info for the image
Adds the following:
- Hash: sha1 hash of the mask, which can be used to check if the same mask was used during reproducibility tests. (Only added when prefix is “original”)
- Dimensionality: Number of dimensions (e.g. 2D, 3D) in the image. (Only added when prefix is “original”)
- Spacing: Pixel spacing (x, y, z) in mm.
- Size: Dimensions (x, y, z) of the image in number of voxels.
- Mean: Mean intensity value over all voxels in the image.
- Minimum: Minimum intensity value among all voxels in the image.
- Maximum: Maximum intensity value among all voxels in the image.
A prefix is added to indicate what type of image is described:
- original: Image as loaded, without pre-processing.
- interpolated: Image after it has been resampled to a new spacing (includes cropping).
-
addMaskElements
(image, mask, label, prefix='original')[source]¶ Calculates provenance info for the mask
Adds the following:
- MaskHash: sha1 hash of the mask, which can be used to check if the same mask was used during reproducibility tests. (Only added when prefix is “original”)
- BoundingBox: bounding box of the ROI defined by 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.
- VoxelNum: Number of voxels included in the ROI defined by the specified label.
- VolumeNum: Number of fully connected (26-connectivity) volumes in the ROI defined by the specified label.
- CenterOfMassIndex: x, y and z coordinates of the center of mass of the ROI in terms of the image coordinate space (continuous index).
- CenterOfMass: the real-world x, y and z coordinates of the center of mass of the ROI
- ROIMean: Mean intensity value over all voxels in the ROI defined by the specified label.
- ROIMinimum: Minimum intensity value among all voxels in the ROI defined by the specified label.
- ROIMaximum: Maximum intensity value among all voxels in the ROI defined by the specified label.
A prefix is added to indicate what type of mask is described:
- original: Mask as loaded, without pre-processing.
- corrected: Mask after it has been corrected by
imageoperations.checkMask()
. - interpolated: Mask after it has been resampled to a new spacing (includes cropping).
- resegmented: Mask after resegmentation has been applied.
-
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
andinputMask
, 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.
- 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.
- 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.
-
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.
-
execute
()[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.
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.
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:
- Accepts an iterable as the first positional argument and a keyword argument (‘desc’) specifying a label to display
- Can be used in a ‘with’ statement (i.e. exposes a __enter__ and __exit__ function)
- 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, dataDirectory=None)[source]¶ This function provides an image and mask for testing PyRadiomics. One of seven test cases can be selected:
- brain1
- brain2
- breast1
- lung1
- lung2
- test_wavelet_64x64x64
- test_wavelet_37x37x37
Checks if the test case (consisting of an image and mask file with signature <testCase>_image.nrrd and <testCase>_label.nrrd, respectively) is available in the
dataDirectory
. If not available, the testCase is downloaded from the GitHub repository and stored in thedataDirectory
. Also creates thedataDirectory
if necessary. If nodataDirectory
has been specified, PyRadiomics will use a temporary directory: <TEMPDIR>/pyradiomics/data.If the test case has been found or downloaded successfully, this function returns a tuple of two strings:
(path/to/image.nrrd, path/to/mask.nrrd)
. In case of an error(None, None)
is returned.Note
To get the testcase with the corresponding single-slice label, append “_2D” to the testCase.
-
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.