Configure the image processing and feature extraction workflow

MIRP implements the standardised image processing and feature extraction workflow recommended by the Image Biomarker Standardization Initiative. Many aspects of this workflow can be configured. This can be done in several ways:

  • Using keyword arguments. The keyword arguments match the parameters used to initialise the various settings objects documented below.

  • By creating a SettingsClass object. This object can be initialised using the same keyword arguments as above. Alternatively, the attributes of the SettingsClass can be filled with the specific objects documented below.

  • By specifying the configuration in a stand-alone settings xml file. An empty copy of the xml file can be created using get_settings_xml().

General settings

class mirp.settings.general_parameters.GeneralSettingsClass(by_slice: bool = False, ibsi_compliant: bool = True, mask_merge: bool = False, mask_split: bool = False, mask_select_largest_region: bool = False, mask_select_largest_slice: bool = False, config_str: str = '', no_approximation: bool = False, **kwargs)[source]

Bases: object

Set of overall process parameters. The most important parameter here is by_slice which affects how images are processed and features are computed.

Parameters:

  • by_slice (bool, optional, default: False) – Defines whether image processing and computations should be performed in 2D (True) or 3D (False).

  • ibsi_compliant (bool, optional, default: True) – Limits use of methods and computation of features to those that exist in the IBSI reference standard.

  • mask_merge (bool, optional, default: False) – Defines whether multiple mask objects should be combined into a single mask.

  • mask_split (bool, optional, default: False) – Defines whether a mask that contains multiple regions should be split into separate mask objects.

  • mask_select_largest_region (bool, optional, default: False) – Defines whether the largest region within a mask object should be selected. For example, in a mask that contains multiple separate lesions. mask_select_largest_region = True will remove all but the largest lesion.

  • mask_select_largest_slice (bool, optional, default: False) – Defines whether the largest slice within a mask object should be selected.

  • config_str (str, optional) – Sets a configuration string, which can be used to differentiate results obtained using other settings.

  • no_approximation (bool, optional, default: False) – Disables approximation within MIRP. This currently only affects computation of features such as Geary’s c-measure. Can be True or False (default). False means that approximation is performed.

  • **kwargs (dict, optional) – Unused keyword arguments.

Image processing settings

class mirp.settings.image_processing_parameters.ImagePostProcessingClass(bias_field_correction: bool = False, bias_field_correction_n_fitting_levels: int = 1, bias_field_correction_n_max_iterations: int | list[int] | None = None, bias_field_convergence_threshold: float = 0.001, pet_suv_conversion: str = 'body_weight', intensity_normalisation: str = 'none', intensity_normalisation_range: list[float] | None = None, intensity_normalisation_saturation: list[float] | None = None, intensity_scaling: float | None = None, tissue_mask_type: str = 'relative_range', tissue_mask_range: list[float] | None = None, **kwargs)[source]

Bases: object

Parameters related to image processing. Note that parameters concerning image perturbation / augmentation and resampling are set separately, see ImagePerturbationSettingsClass and ImageInterpolationSettingsClass.

Parameters:

  • bias_field_correction (bool, optional, default: False) –

    Determines whether N4 bias field correction should be performed. When a tissue mask is present, bias field correction is conducted using the information contained within the mask.

    Note

    Bias-field correction can only be applied to MR imaging.

  • bias_field_correction_n_fitting_levels (int, optional, default: 1) – The number of fitting levels for the N4 bias field correction algorithm.

  • bias_field_correction_n_max_iterations (int or list of int, optional, default: 50) – The number of fitting iterations for the N4 bias field algorithm. A single integer, or a list of integers with a length equal to the number of fitting levels is expected.

  • bias_field_convergence_threshold (float, optional, default: 0.001) – Convergence threshold for N4 bias field correction algorithm.

  • pet_suv_conversion ({"body_weight", "body_surface_area", "lean_body_mass", "lean_body_mass_bmi", "ideal_body_weight". "none"}, default: "body_weight") –

    Intensities in PET imaging are often stored as detected radiotracer activity. To make detected activity more comparable between patients, these are converted to standardised uptake values. The following are possible:

    • ”body_weight”: activity is normalised by body weight.

    • ”body_surface_area”: activity is normalised by body surface area according to DuBois (A formula to estimate the approximate surface area if height and weight be known. Arch intern med. 1916;17:863-71).

    • ”lean_body_mass”: activity is normalised by lean body mass according to James et al. (DHSS/MRC Group on Obesity Research, James WP, Waterlow JC. Research on Obesity: A Report of the DHSS/MRC Group; Compiled by WPT James. HM Stationery Office; 1976).

    • ”lean_body_mass_bmi”: activity is normalised by lean body mass according to Janmahasatian et al. (Quantification of lean bodyweight. Clinical pharmacokinetics. 2005 Oct;44:1051-65).

    • ”ideal_body_weight”: activity is normalised by ideal body weight according to Zasadny and Wahl ( Standardized uptake values of normal tissues at PET with 2-[fluorine-18]-fluoro-2-deoxy-D-glucose: variations with body weight and a method for correction. Radiology. 1993 Dec;189(3):847-50).

    • ”none”: activity is not normalised.

    Note

    Conversion of activity to standardised uptake values can only be performed for PET data.

    Warning

    Conversion of activity to standardised uptake values requires metadata related to image acquisition and to the patient. These metadata are only present in DICOM files. MIRP cannot convert activity to standardised uptake values for images in different formats, and this parameter will have no effect.

  • intensity_normalisation ({"none", "range", "relative_range", "quantile_range", "standardisation"}, default: "none") –

    Specifies the algorithm used to normalise intensities in the image. Will use only intensities in voxels masked by the tissue mask (of present). The following are possible:

    • ”none”: no normalisation

    • ”range”: normalises intensities based on a fixed mapping against the intensity_normalisation_range parameter, which is interpreted to represent an intensity range.

    • ”relative_range”: normalises intensities based on a fixed mapping against the intensity_normalisation_range parameter, which is interpreted to represent a relative intensity range.

    • ”quantile_range”: normalises intensities based on a fixed mapping against the intensity_normalisation_range parameter, which is interpreted to represent a quantile range.

    • ”standardisation”: normalises intensities by subtraction of the mean intensity and division by the standard deviation of intensities.

    Note

    Intensity normalisation may remove any physical meaning of intensity units. For example, intensity normalisation of CT images yield intensities that no longer represent Hounsfield Units.

  • intensity_normalisation_range (list of float, optional) –

    Required for “range”, “relative_range”, and “quantile_range” intensity normalisation methods, and defines the intensities that are mapped to the [0.0, 1.0] range during normalisation. The default range depends on the type of normalisation method:

    • ”range”: [np.nan, np.nan]: the minimum and maximum intensity value present in the image are used to set the mapping range.

    • ”relative_range”: [0.0. 1.0]: the minimum (0.0) and maximum (1.0) intensity value present in the image are used to set the mapping range.

    • ”quantile_range”: [0.025, 0.975] the 2.5th and 97.5th percentiles of the intensities in the image are used to set the mapping range.

    The lower end of the range is mapped to 0.0 and the upper end to 1.0. However, if intensities below the lower end or above the upper end are present in the image, values below 0.0 or above 1.0 may be encountered after normalisation. Use intensity_normalisation_saturation to cap intensities after normalisation to a specific range.

  • intensity_normalisation_saturation (list of float, optional, default: [np.nan, np.nan]) – Defines the start and endpoint for the saturation range. Normalised intensities that lie outside this range are mapped to the limits of the saturation range, e.g. with a range of [0.0, 0.8] all values greater than 0.8 are assigned a value of 0.8. np.nan can be used to define limits where the intensity values should not be saturated.

  • intensity_scaling (float, optional) – Defines scaling parameter to linearly scale intensities with. The scaling parameter is applied after normalisation (if any). For example, intensity_scaling = 1000.0, combined with intensity_normalisation = “range” results in intensities being mapped to a [0.0, 1000.0] range instead of [0.0, 1.0].

  • tissue_mask_type ({"none", "range", "relative_range"}, optional, default: "relative_range") – Type of algorithm used to produce an approximate tissue mask of the tissue. Such masks can be used to select pixels for bias correction and intensity normalisation by excluding non-tissue voxels.

  • tissue_mask_range (list of float, optional) – Range values for creating an approximate mask of the tissue. Required for “range” and “relative_range” options. Default: [0.02, 1.00] ("relative_range"); [np.nan, np.nan] ("range"; effectively all voxels are considered to represent tissue).

  • **kwargs – Unused keyword arguments.

Image perturbation settings

class mirp.settings.perturbation_parameters.ImagePerturbationSettingsClass(crop_around_roi: bool = False, crop_distance: float = 150.0, perturbation_noise_repetitions: int = 0, perturbation_noise_level: None | float = None, perturbation_rotation_angles: None | float | list[float] = 0.0, perturbation_translation_fraction: None | float | list[float] = 0.0, perturbation_roi_adapt_type: str = 'distance', perturbation_roi_adapt_size: None | float | list[float] = 0.0, perturbation_roi_adapt_max_erosion: float = 0.8, perturbation_randomise_roi_repetitions: int = 0, roi_split_boundary_size: None | float | list[float] = 0.0, roi_split_max_erosion: float = 0.6, **kwargs)[source]

Bases: object

Parameters related to image and mask perturbation / augmentation. By default images and masks are not perturbed or augmented.

Parameters:

  • crop_around_roi (bool, optional, default: False) – Determines whether the image may be cropped around the regions of interest. Setting this to True may speed up computation and save memory.

  • crop_distance (float, optional, default: 150.0) – Physical distance around the mask that should be maintained when cropping the image. When using convolutional kernels for filtering an image, we recommend to leave some distance to prevent boundary effects. A crop distance of 0.0 crops the image tightly around the mask.

  • perturbation_noise_repetitions (int, optional, default: 0) – Number of repetitions where noise is randomly added to the image. A value of 0 means that no noise will be added.

  • perturbation_noise_level (float, optional, default: None) – Set the noise level in intensity units. This determines the width of the normal distribution used to generate random noise. If None (default), noise is determined from the image itself.

  • perturbation_rotation_angles (float or list of float, optional, default: 0.0) – Angles (in degrees) over which the image and mask are rotated. This rotation is only in the x-y (axial) plane. Multiple angles can be provided to create images with different rotations.

  • perturbation_translation_fraction (float or list of float, optional, default: 0.0) – Sub-voxel translation distance fractions of the interpolation grid. This forces the interpolation grid to shift slightly and interpolate at different points. Multiple values can be provided. All values should be between 0.0 and 1.0.

  • perturbation_roi_adapt_type ({"fraction", "distance"}, optional, default: "distance") – Determines how the mask is grown or shrunk. Can be either “fraction” or “distance”. “fraction” is used to grow or shrink the mask by a certain fraction (see the perturbation_roi_adapt_size parameter). “distance” is used to grow or shrink the mask by a certain physical distance, defined using the perturbation_roi_adapt_size parameter.

  • perturbation_roi_adapt_size (float or list of float, optional, default: 0.0) – Determines the extent of growth/shrinkage of the ROI mask. The use of this parameter depends on the growth/shrinkage type (perturbation_roi_adapt_type), For “distance”, this parameter defines growth/shrinkage in physical units, typically mm. For “fraction”, this parameter defines growth/shrinkage in volume fraction (e.g. a value of 0.2 grows the mask by 20%). For either type, positive values indicate growing the mask, whereas negative values indicate its shrinkage. Multiple values can be provided to perturb the volume of the mask.

  • perturbation_roi_adapt_max_erosion (float, optional, default: 0.8) – Limits shrinkage of the mask by distance-based adaptations to avoid forming empty masks. Defined as fraction of the original volume, e.g. a value of 0.8 prevents shrinking the mask below 80% of its original volume. Only used when perturbation_roi_adapt_type=="distance".

  • perturbation_randomise_roi_repetitions (int, optional, default: 0.0) – Number of repetitions where the mask is randomised using supervoxel-based randomisation.

  • roi_split_boundary_size (float or list of float, optional, default: 0.0) – Width of the rim used for splitting the mask into bulk and rim masks, in physical dimensions. Multiple values can be provided to generate rims of different widths.

  • roi_split_max_erosion (float, optional, default: 0.6) – Determines the minimum volume of the bulk mask when splitting the original mask into bulk and rim sections. Fraction of the original volume, e.g. 0.6 means that the bulk contains at least 60% of the original mask.

  • **kwargs (dict, optional) – Unused keyword arguments.

Image interpolation settings

class mirp.settings.interpolation_parameters.ImageInterpolationSettingsClass(by_slice: bool, new_spacing: None | float | int | list[int] | list[float] | list[list[float]] | list[list[int]] = None, spline_order: int = 3, anti_aliasing: bool = True, smoothing_beta: float = 0.98, **kwargs)[source]

Bases: object

Parameters related to image interpolating / resampling. Images in a dataset are typically resampled to uniform voxel spacing to ensure that their spatial representation does not vary between samples.

For parameters related to mask interpolation / resampling, see MaskInterpolationSettingsClass.

Parameters:

  • by_slice (str or bool, optional, default: False) – Defines whether calculations should be performed in 2D (True) or 3D (False), or alternatively only in the largest slice (“largest”). See GeneralSettingsClass.

  • new_spacing (float or list of float or list of list of float, optional:) –

    Sets voxel spacing after interpolation. A single value represents the spacing that will be applied in all directions. Non-uniform voxel spacing may also be provided, but requires 3 values for z, y, and x directions (if by_slice = False) or 2 values for y and x directions (otherwise).

    Multiple spacings may be defined by creating a nested list, e.g. [[1.0], [1.5], [2.0]] to resample the same image multiple times to different (here: isotropic) voxel spacings, namely 1.0, 1.5 and 2.0. Units are defined by the headers of the image files. These are typically millimeters for radiological images.

  • spline_order (int, optional, default: 3) – Sets the spline order used for spline interpolation. mirp uses scipy.ndimage.map_coordinates internally. Spline orders 0, 1, and 3 refer to nearest neighbour, linear interpolation and cubic interpolation, respectively.

  • anti_aliasing (bool, optional, default: true) –

    Determines whether to perform antialiasing, which is done to mitigate aliasing artifacts when downsampling.

    Note

    When voxel spacing in the original image is smaller than that in the resampled image (e.g., 0.5 mm sampled to 1.0 mm), antialiasing is recommended [Mackin et al.].

  • smoothing_beta (float, optional, default: 0.98) – Determines the smoothness of the Gaussian filter used for anti-aliasing. A value of 1.00 equates to no antialiasing, with lower values producing increasingly smooth imaging. Values above 0.90 are recommended. The effect of this parameter is shown in the supplement of Zwanenburg et al..

  • **kwargs (dict, optional) – Unused keyword arguments.

class mirp.settings.interpolation_parameters.MaskInterpolationSettingsClass(roi_spline_order: int = 1, roi_interpolation_mask_inclusion_threshold: float = 0.5, **kwargs)[source]

Bases: object

Parameters related to mask interpolation / resampling. MIRP registers the mask to an interpolated image based, and fewer parameters can be set compared to image interpolation / resampling ( ImageInterpolationSettingsClass).

Parameters:

  • roi_spline_order (int, optional, default: 1) –

    Sets the spline order used for spline interpolation. mirp uses scipy.ndimage.map_coordinates internally. Spline orders 0, 1, and 3 refer to nearest neighbour, linear interpolation and cubic interpolation, respectively.

  • roi_interpolation_mask_inclusion_threshold (float, optional, default: 0.5) – Threshold for partially masked voxels after interpolation. All voxels with a value equal to or greater than this threshold are assigned to the mask.

  • **kwargs (dict, optional) – Unused keyword arguments.

Mask resegmentation settings

class mirp.settings.resegmentation_parameters.ResegmentationSettingsClass(resegmentation_intensity_range: None | list[float] = None, resegmentation_sigma: None | float = None, **kwargs)[source]

Bases: object

Parameters related to mask resegmentation. Resegmentation is used to remove parts of the mask that correspond to undesired intensities that should be excluded, e.g. those corresponding to air. Resegmentation based on an intensity range is also required for using Fixed Bin Size discretisation to set the lower bound of the first bin.

Note

Even though intensity range resegmentation is usually required to perform Fixed Bin Size discretisation, default values are available for computed tomography (CT) and positron emission tomography (PET) imaging, and are set to -1000.0 Hounsfield Units and 0.0 SUV, respectively.

Parameters:

  • resegmentation_intensity_range (list of float, optional) – Intensity threshold for threshold-based re-segmentation (“threshold” and “range”). If set, requires two values for lower and upper range respectively. The upper range value can also be np.nan for half-open ranges.

  • resegmentation_sigma (float, optional) – Number of standard deviations for outlier-based intensity re-segmentation (“sigma” and “outlier”).

  • **kwargs (dict, optional) – Unused keyword arguments.

Feature computation settings

class mirp.settings.feature_parameters.FeatureExtractionSettingsClass(by_slice: bool = False, no_approximation: bool = False, ibsi_compliant: bool = True, base_feature_families: None | str | list[str] = 'none', base_discretisation_method: None | str | list[str] = None, base_discretisation_n_bins: None | int | list[int] = None, base_discretisation_bin_width: None | float | list[float] = None, ivh_discretisation_method: str = 'none', ivh_discretisation_n_bins: None | int = 1000, ivh_discretisation_bin_width: None | float = None, glcm_distance: float | list[float] = 1.0, glcm_spatial_method: None | str | list[str] = None, glrlm_spatial_method: None | str | list[str] = None, glszm_spatial_method: None | str | list[str] = None, gldzm_spatial_method: None | str | list[str] = None, ngtdm_spatial_method: None | str | list[str] = None, ngldm_distance: float | list[float] = 1.0, ngldm_difference_level: float | list[float] = 0.0, ngldm_spatial_method: None | str | list[str] = None, **kwargs)[source]

Bases: object

Parameters related to feature computation. Many are conditional on the type of features that will be computed ( base_feature_families). Features and their parameters are defined here.

Parameters:

  • by_slice (str or bool, optional, default: False) – Defines whether calculations should be performed in 2D (True) or 3D (False), or alternatively only in the largest slice (“largest”). See GeneralSettingsClass.

  • no_approximation (bool, optional, default: False) – Disables approximation of features, such as Geary’s c-measure. Can be True or False (default). See GeneralSettingsClass.

  • ibsi_compliant (bool, optional, default: True) – Limits computation of features to those features that have a reference value in the IBSI reference standard.

  • base_feature_families (str or list of str, optional, default: "none") –

    Determines the feature families for which features are computed. Radiomics features are implemented as defined in the IBSI reference manual. The following feature families are currently present, and can be added using the following tags:

    • Morphological features: “mrp”, “morph”, “morphology”, and “morphological”.

    • Local intensity features: “li”, “loc.int”, “loc_int”, “local_int”, and “local_intensity”.

    • Intensity-based statistical features: “st”, “stat”, “stats”, “statistics”, and “statistical”.

    • Intensity histogram features: “ih”, “int_hist”, “int_histogram”, and “intensity_histogram”.

    • Intensity-volume histogram features: “ivh”, “int_vol_hist”, and “intensity_volume_histogram”.

    • Grey level co-occurrence matrix (GLCM) features: “cm”, “glcm”, “grey_level_cooccurrence_matrix”, and “cooccurrence_matrix”.

    • Grey level run length matrix (GLRLM) features: “rlm”, “glrlm”, “grey_level_run_length_matrix”, and “run_length_matrix”.

    • Grey level size zone matrix (GLSZM) features: “szm”, “glszm”, “grey_level_size_zone_matrix”, and “size_zone_matrix”.

    • Grey level distance zone matrix (GLDZM) features: “dzm”, “gldzm”, “grey_level_distance_zone_matrix”, and “distance_zone_matrix”.

    • Neighbourhood grey tone difference matrix (NGTDM) features: “tdm”, “ngtdm”, “neighbourhood_grey_tone_difference_matrix”, and “grey_tone_difference_matrix”.

    • Neighbouring grey level dependence matrix (NGLDM) features: “ldm”, “ngldm”, “neighbouring_grey_level_dependence_matrix”, and “grey_level_dependence_matrix”.

    In addition, the following tags can be used:

    • ”none”: no features are computed.

    • ”all”: all features are computed.

    A list of strings may be provided to select multiple feature families.

    Note

    Even though "none" is the internal default, the extract_features() function overrides this, and sets the default to "all".

  • base_discretisation_method ({"fixed_bin_number", "fixed_bin_size", "fixed_bin_size_pyradiomics", "none"}) –

    Method used for discretising intensities. Used to compute intensity histogram as well as texture features. The setting is ignored if none of these feature families are being computed. The following options are available:

    • ”fixed_bin_number”: The intensity range within the mask is divided into a fixed number of bins, defined by the base_discretisation_bin_width parameter.

    • ”fixed_bin_size”: The intensity range is divided into bins with a fixed width, defined using the base_discretisation_bin_width parameter. The lower bound of the range is determined from the lower bound of the mask resegmentation range, see the resegmentation_intensity_range in ResegmentationSettingsClass. CT images have a default lower bound of the initial bin at -1000.0 and PET images have a default lower bound at 0.0. Other images, including MRI, normalised CT and PET images and filtered images, do not have a default value.

    • ”fixed_bin_size_pyradiomics”: The intensity range is divided into bins with a fixed width. This follows the non-IBSI compliant implementation in the pyradiomics package.

    • ”none”: The intensity range is not discretised into bins. This method can only be used if the image intensities are integer and strictly positive.

    There is no default method. Multiple methods can be specified as a list to yield features according to each method.

    Warning

    The “fixed_bin_size_pyradiomics” is not IBSI compliant, and should only be used when reproducing results from studies that used pyradiomics.

  • base_discretisation_n_bins (int or list of int) – Number of bins used for the “fixed_bin_number” discretisation method. No default value. Multiple values can be specified in a list to yield features according to each number of bins.

  • base_discretisation_bin_width (float or list of float) – Width of each bin in the “fixed_bin_size” discretisation method. No default value. Multiple values can be specified in a list to yield features according to each bin width.

  • ivh_discretisation_method ({"fixed_bin_number", "fixed_bin_size", "none"}, optional, default: "none") – Method used for discretising intensities for computing intensity-volume histograms. The discretisation methods follow those in base_discretisation_method. The “none” method changes to “fixed_bin_number” if the underlying data are not suitable.

  • ivh_discretisation_n_bins (int, optional, default: 1000) – Number of bins used for the “fixed_bin_number” discretisation method.

  • ivh_discretisation_bin_width (float, optional) – Width of each bin in the “fixed_bin_size” discretisation method. No default value.

  • glcm_distance (float or list of float, optional, default: 1.0) – Distance (in voxels) for GLCM for determining the neighbourhood. Chebyshev, or checkerboard, distance is used. A value of 1.0 will therefore consider all (diagonally) adjacent voxels as its neighbourhood. A list of values can be provided to compute GLCM features at different scales.

  • glcm_spatial_method ({"2d_average", "2d_slice_merge", "2.5d_direction_merge", "2.5d_volume_merge", "3d_average", "3d_volume_merge"}, optional) –

    Determines how co-occurrence matrices are formed and aggregated. One of the following:

    • ”2d_average”: features are computed from all matrices then averaged [IBSI:BTW3].

    • ”2d_slice_merge”: matrices in the same slice are merged, features computed and then averaged [IBSI:SUJT].

    • ”2.5d_direction_merge”: matrices for the same direction are merged, features computed and then averaged [IBSI:JJUI].

    • ”2.5d_volume_merge”: all matrices are merged and a single feature is calculated [IBSI:ZW7Z].

    • ”3d_average”: features are computed from all matrices then averaged [IBSI:ITBB].

    • ”3d_volume_merge”: all matrices are merged and a single feature is computed from the merged matrix [IBSI:IAZD].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d_slice_merge” (by_slice = False) or “3d_volume_merge” (by_slice = True).

  • glrlm_spatial_method ({"2d_average", "2d_slice_merge", "2.5d_direction_merge", "2.5d_volume_merge", "3d_average", "3d_volume_merge"}, optional) –

    Determines how run length matrices are formed and aggregated. One of the following:

    • ”2d_average”: features are calculated from all matrices then averaged [IBSI:BTW3].

    • ”2d_slice_merge”: matrices in the same slice are merged, features computed and then averaged [IBSI:SUJT].

    • ”2.5d_direction_merge”: matrices for the same direction are merged, features computed and then averaged [IBSI:JJUI].

    • ”2.5d_volume_merge”: all matrices are merged and a single feature is computed [IBSI:ZW7Z].

    • ”3d_average”: features are computed from all matrices then averaged [IBSI:ITBB].

    • ”3d_volume_merge”: all matrices are merged and a single feature is computed from the merged matrix [IBSI:IAZD].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d_slice_merge” (by_slice = False) or “3d_volume_merge” (by_slice = True).

  • glszm_spatial_method ({"2d", "2.5d", "3d"}, optional) –

    Determines how the size zone matrices are formed and aggregated. One of the following:

    • ”2d”: features are computed from individual matrices and subsequently averaged [IBSI:8QNN].

    • ”2.5d”: all 2D matrices are merged and features are computed from this single matrix [IBSI:62GR].

    • ”3d”: features are computed from a single 3D matrix [IBSI:KOBO].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d” (by_slice = False) or “3d” (by_slice = True).

  • gldzm_spatial_method ({"2d", "2.5d", "3d"}, optional) –

    Determines how the distance zone matrices are formed and aggregated. One of the following:

    • ”2d”: features are computed from individual matrices and subsequently averaged [IBSI:8QNN].

    • ”2.5d”: all 2D matrices are merged and features are computed from this single matrix [IBSI:62GR].

    • ”3d”: features are computed from a single 3D matrix [IBSI:KOBO].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d” (by_slice = False) or “3d” (by_slice = True).

  • ngtdm_spatial_method ({"2d", "2.5d", "3d"}, optional) –

    Determines how the neighbourhood grey tone difference matrices are formed and aggregated. One of the following:

    • ”2d”: features are computed from individual matrices and subsequently averaged [IBSI:8QNN].

    • ”2.5d”: all 2D matrices are merged and features are computed from this single matrix [IBSI:62GR].

    • ”3d”: features are computed from a single 3D matrix [IBSI:KOBO].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d” (by_slice = False) or “3d” (by_slice = True).

  • ngldm_distance (float or list of float, optional, default: 1.0) – Distance (in voxels) for NGLDM for determining the neighbourhood. Chebyshev, or checkerboard, distance is used. A value of 1.0 will therefore consider all (diagonally) adjacent voxels as its neighbourhood. A list of values can be provided to compute NGLDM features at different scales.

  • ngldm_difference_level (float or list of float, optional, default: 0.0) – Difference level (alpha) for NGLDM. Determines which bins are grouped together in the matrix.

  • ngldm_spatial_method ({"2d", "2.5d", "3d"}, optional) –

    Determines how the neighbourhood grey level dependence matrices are formed and aggregated. One of the following:

    • ”2d”: features are computed from individual matrices and subsequently averaged [IBSI:8QNN].

    • ”2.5d”: all 2D matrices are merged and features are computed from this single matrix [IBSI:62GR].

    • ”3d”: features are computed from a single 3D matrix [IBSI:KOBO].

    A list of values may be provided to extract features for multiple spatial methods. Default: “2d” (by_slice = False) or “3d” (by_slice = True).

  • **kwargs (dict, optional) – Unused keyword arguments.

Image transformation settings

class mirp.settings.transformation_parameters.ImageTransformationSettingsClass(by_slice: bool, ibsi_compliant: bool = True, response_map_feature_settings: FeatureExtractionSettingsClass | None = None, response_map_feature_families: None | str | list[str] = 'statistical', response_map_discretisation_method: None | str | list[str] = 'fixed_bin_number', response_map_discretisation_n_bins: None | int | list[int] = 16, response_map_discretisation_bin_width: None | int | list[float] = None, filter_kernels: None | str | list[str] = None, boundary_condition: None | str = 'mirror', separable_wavelet_families: None | str | list[str] = None, separable_wavelet_set: None | str | list[str] = None, separable_wavelet_stationary: bool = True, separable_wavelet_decomposition_level: None | int | list[int] = 1, separable_wavelet_rotation_invariance: bool = True, separable_wavelet_pooling_method: str = 'max', separable_wavelet_boundary_condition: None | str = None, nonseparable_wavelet_families: None | str | list[str] = None, nonseparable_wavelet_decomposition_level: None | int | list[int] = 1, nonseparable_wavelet_response: None | str = 'real', nonseparable_wavelet_boundary_condition: None | str = None, gaussian_sigma: None | float | list[float] = None, gaussian_kernel_truncate: None | float = 4.0, gaussian_kernel_boundary_condition: None | str = None, laplacian_of_gaussian_sigma: None | float | list[float] = None, laplacian_of_gaussian_kernel_truncate: None | float = 4.0, laplacian_of_gaussian_pooling_method: str = 'none', laplacian_of_gaussian_boundary_condition: None | str = None, laws_kernel: None | str | list[str] = None, laws_delta: int | list[int] = 7, laws_compute_energy: bool = True, laws_rotation_invariance: bool = True, laws_pooling_method: str = 'max', laws_boundary_condition: None | str = None, gabor_sigma: None | float | list[float] = None, gabor_lambda: None | float | list[float] = None, gabor_gamma: None | float | list[float] = 1.0, gabor_theta: None | float | list[float] = 0.0, gabor_theta_step: None | float = None, gabor_response: str = 'modulus', gabor_rotation_invariance: bool = False, gabor_pooling_method: str = 'max', gabor_boundary_condition: None | str = None, mean_filter_kernel_size: None | int | list[int] = None, mean_filter_boundary_condition: None | str = None, riesz_filter_order: None | int | list[int] = None, riesz_filter_tensor_sigma: None | float | list[float] = None, **kwargs)[source]

Bases: object

Parameters related to image transformation using filters. Many parameters are conditional on the selected image filter (filter_kernels). Filters and their parameters are defined here By default, only statistical features are computed from filtered images.

Note

Many feature extraction parameters are copied from FeatureExtractionSettingsClass, except response_map_feature_families, response_map_discretisation_method and response_map_discretisation_n_bins. If other parameters need to be changed from their default settings, first create an object of the current class ( ImageTransformationSettingsClass), and then update the attributes.

Parameters:

  • by_slice (str or bool, optional, default: False) – Defines whether calculations should be performed in 2D (True) or 3D (False), or alternatively only in the largest slice (“largest”). See GeneralSettingsClass.

  • ibsi_compliant (bool, optional, default: True) – Limits use of filters to those that exist in the IBSI reference standard.

  • response_map_feature_families (str or list of str, optional, default: "statistics") –

    Determines the feature families for which features are computed from response maps (filtered images). Radiomics features are implemented as defined in the IBSI reference manual. The following feature families can be computed from response maps:

    • Local intensity features: “li”, “loc.int”, “loc_int”, “local_int”, and “local_intensity”.

    • Intensity-based statistical features: “st”, “stat”, “stats”, “statistics”, and “statistical”.

    • Intensity histogram features: “ih”, “int_hist”, “int_histogram”, and “intensity_histogram”.

    • Intensity-volume histogram features: “ivh”, “int_vol_hist”, and “intensity_volume_histogram”.

    • Grey level co-occurrence matrix (GLCM) features: “cm”, “glcm”, “grey_level_cooccurrence_matrix”, and “cooccurrence_matrix”.

    • Grey level run length matrix (GLRLM) features: “rlm”, “glrlm”, “grey_level_run_length_matrix”, and “run_length_matrix”.

    • Grey level size zone matrix (GLSZM) features: “szm”, “glszm”, “grey_level_size_zone_matrix”, and “size_zone_matrix”.

    • Grey level distance zone matrix (GLDZM) features: “dzm”, “gldzm”, “grey_level_distance_zone_matrix”, and “distance_zone_matrix”.

    • Neighbourhood grey tone difference matrix (NGTDM) features: “tdm”, “ngtdm”, “neighbourhood_grey_tone_difference_matrix”, and “grey_tone_difference_matrix”.

    • Neighbouring grey level dependence matrix (NGLDM) features: “ldm”, “ngldm”, “neighbouring_grey_level_dependence_matrix”, and “grey_level_dependence_matrix”.

    In addition, the following tags can be used:

    • ”none”: no features are computed.

    • ”all”: all features are computed.

    A list of tags may be provided to select multiple feature families. Morphological features are not computed from response maps (filtered images), because these are mask-based and are invariant to filtering.

  • response_map_discretisation_method ({"fixed_bin_number", "fixed_bin_size", "fixed_bin_size_pyradiomics", "none"}, optional, default: "fixed_bin_number") –

    Method used for discretising intensities. Used to compute intensity histogram as well as texture features. The setting is ignored if none of these feature families are being computed. The following options are available:

    • ”fixed_bin_number”: The intensity range within the mask is divided into a fixed number of bins, defined by the base_discretisation_bin_width parameter.

    • ”fixed_bin_size”: The intensity range is divided into bins with a fixed width, defined using the base_discretisation_bin_width parameter. The lower bound of the range is determined from the lower bound of the mask resegmentation range, see the resegmentation_intensity_range in ResegmentationSettingsClass. Other images, including MRI, normalised CT and PET images and filtered images, do not have a default value, and bins are created from using the minimum intensity as lower bound.

    • ”fixed_bin_size_pyradiomics”: The intensity range is divided into bins with a fixed width. This follows the non-IBSI compliant implementation in the pyradiomics package.

    • ”none”: The intensity range is not discretised into bins. This method can only be used if the image intensities are integer and strictly positive.

    Multiple discretisation methods can be specified as a list to yield features according to each method.

    Note

    Use of the “fixed_bin_size”, “fixed_bin_size_pyradiomics”, and “none” discretisation methods is discouraged for transformed images. Due to transformation, a direct link to any meaningful quantity represented by the intensity of the original image (e.g. Hounsfield Units for CT, Standardised Uptake Value for PET) is lost.

  • response_map_discretisation_n_bins (int or list of int, optional, default: 16) – Number of bins used for the “fixed_bin_number” discretisation method. Multiple values can be specified in a list to yield features according to each number of bins.

  • response_map_discretisation_bin_width (float or list of float, optional) – Width of each bin in the “fixed_bin_size” and “fixed_bin_size_pyradiomics” discretisation methods. Multiple values can be specified in a list to yield features according to each bin width.

  • filter_kernels (str or list of str, optional, default: None) –

    Names of the filters applied to the original image to create response maps (filtered images). Filter implementation follows the IBSI reference manual. The following filters are supported:

    • Mean filters: “mean”

    • Gaussian filters: “gaussian”, “riesz_gaussian”, and “riesz_steered_gaussian”

    • Laplacian-of-Gaussian filters: “laplacian_of_gaussian”, “log”, “riesz_laplacian_of_gaussian”, “riesz_log”, “riesz_steered_laplacian_of_gaussian”, and “riesz_steered_log”.

    • Laws kernels: “laws”

    • Gabor kernels: “gabor”, “riesz_gabor”, and “riesz_steered_gabor”

    • Separable wavelets: “separable_wavelet”

    • Non-separable wavelets: “nonseparable_wavelet”, “riesz_nonseparable_wavelet”, and “riesz_steered_nonseparable_wavelet”

    • Function transformations: “pyradiomics_square”, “pyradiomics_square_root”, and “pyradiomics_logarithm”, “pyradiomics_exponential”

    Filters with names that preceded by “riesz” undergo a Riesz transformation. If the filter name is preceded by “riesz_steered”, a steerable riesz filter is used.

    More than one filter name can be provided. By default, no filters are selected, and image transformation is skipped.

    Note

    There is no IBSI reference standard for Gaussian filters. However, the filter implementation is relatively straightforward, and most likely reproducible.

    Warning

    Riesz transformation and steerable riesz transformations are experimental. The implementation of these filter transformations is complex. Since there is no corresponding IBSI reference standard, any feature derived from response maps (filtered images) of Riesz transformations is unlikely to be reproducible.

    Warning

    Function transformations (square, square root, logarithm, exponential) do not have an IBSI reference standard. These transformations follow the definition in pyradiomics, and have been implemented for validation purposes.

  • boundary_condition ({"reflect", "constant", "nearest", "mirror", "wrap"}, optional, default: "mirror") – Sets the boundary condition, which determines how filters behave at the edge of an image. MIRP uses the same nomenclature for boundary conditions as scipy.ndimage. See the mode parameter of scipy.ndimage.convolve

  • separable_wavelet_families (str or list str) – Name of separable wavelet kernel as implemented in the pywavelets package. See pywt.wavelist( kind=”discrete”) for options.

  • separable_wavelet_set (str or list of str, optional) – Filter orientation of separable wavelets. Allows for specifying combinations for high and low-pass filters. For 2D (by_slice=True) filters, the following sets are possible: “hh”, “hl”, “lh”, “ll” (y-x directions). For 3D (by_slice=False) filters, the set of possibilities is larger: “hhh”, “hhl”, “hlh”, “lhh”, “hll”, “lhl”, “llh”, “lll”. More than one orientation may be set. Default: “hh” (2d) or “hhh (3d).

  • separable_wavelet_stationary (bool, optional, default: True) – Determines if wavelets are stationary or not. Stationary wavelets maintain the image dimensions after decomposition.

  • separable_wavelet_decomposition_level (int or list of int, optional, default: 1) – Sets the wavelet decomposition level. For the first decomposition level, the base image is used as input to generate a response map (filtered image). For decomposition levels greater than 1, the low-pass image from the previous level is used as input. More than 1 value may be specified in a list.

  • separable_wavelet_rotation_invariance (bool, optional, default: True) – Determines whether separable filters are applied in a pseudo-rotational invariant manner. This generates permutations of the filter and, as a consequence, additional response maps (filtered images). These maps are then merged using the pooling method (separable_wavelet_pooling_method).

  • separable_wavelet_pooling_method ({"max", "min", "mean", "sum"}, optional, default: "max") –

    Response maps are pooled to create a rotationally invariant response map (filtered image). This sets the method for pooling.

    • ”max”: Each voxel of the pooled response map represents the maximum value for that voxel in the underlying response maps.

    • ”min”: Each voxel of the pooled response map represents the minimum value for that voxel in the underlying response maps.

    • ”mean”: Each voxel of the pooled response map represents the mean value for that voxel in the underlying response maps. For band-pass and high-pass filters, this will likely result in values close to 0.0, and “max” or “min” pooling methods should be used instead.

    • ”sum”: Each voxel of the pooled response map is the sum of intensities for that voxel in the underlying response maps. Similar to the “mean” pooling method, but without the normalisation.

  • separable_wavelet_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for separable wavelets. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • nonseparable_wavelet_families ({"shannon", "simoncelli"}) – Name of non-separable wavelet kernels used for image transformation. Shannon and Simoncelli wavelets are implemented.

  • nonseparable_wavelet_decomposition_level (int or list of int, optional, default: 1) – Sets the wavelet decomposition level. Unlike the decomposition level in separable wavelets, decomposition of non-separable wavelets is purely a filter-based operation.

  • nonseparable_wavelet_response ({"modulus", "abs", "magnitude", "angle", "phase", "argument", "real", "imaginary"}, optional, default: "real") – Nonseparable wavelets produce response maps with complex numbers. The complex-valued response map is converted to a real-valued response map (filtered image) using the specified method. “modulus”, “abs”, “magnitude” are synonymous, as are “angle”, “phase”, and “argument”. “real” selects the real component of the complex values, and “imaginary” selects the imaginary component.

  • nonseparable_wavelet_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for non-separable wavelets. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • gaussian_sigma (float or list of float, optional) – Width of the Gaussian filter in physical dimensions (e.g. mm). Multiple values can be specified.

  • gaussian_kernel_truncate (float, optional, default: 4.0) – Width, in units of sigma, at which the filter is truncated.

  • gaussian_kernel_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for Gaussian filters. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • laplacian_of_gaussian_sigma (float or list of float, optional) – Width of the Gaussian filter in physical dimensions (e.g. mm). Multiple values can be specified.

  • laplacian_of_gaussian_kernel_truncate (float, optional, default: 4.0) – Width, in sigma, at which the filter is truncated.

  • laplacian_of_gaussian_pooling_method ({"max", "min", "mean", "sum", "none"}, optional, default: "none") –

    Determines whether and how response maps (filtered images) for filters with different widths ( laplacian_of_gaussian_sigma) are pooled.

    • ”max”: Each voxel of the pooled response map represents the maximum value for that voxel in the underlying response maps.

    • ”min”: Each voxel of the pooled response map represents the minimum value for that voxel in the underlying response maps.

    • ”mean”: Each voxel of the pooled response map represents the mean value for that voxel in the underlying response maps. For band-pass and high-pass filters, this will likely result in values close to 0.0, and “max” or “min” pooling methods should be used instead.

    • ”sum”: Each voxel of the pooled response map is the sum of intensities for that voxel in the underlying response maps. Similar to the “mean” pooling method, but without the normalisation.

    • ”none”: Each Laplacian-of-Gaussian response map is treated separately, without pooling.

  • laplacian_of_gaussian_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for Laplacian-of-Gaussian filters. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • laws_kernel (str or list of str, optional) – Compute specific Laws kernels these typically are specific combinations of kernels such as L5S5E5, E5E5E5. The following kernels are available: ‘l5’, ‘e5’, ‘s5’, ‘w5’, ‘r5’, ‘l3’, ‘e3’, ‘s3’. A combination of two kernels is expected for 2D (by_slice=True), whereas a kernel triplet is expected for 3D filters ( by_slice=False).

  • laws_compute_energy (bool, optional, default: True) – Determine whether an energy image should be computed, or just the response map (filtered) image.

  • laws_delta (int or list of int, optional, default: 7) – Delta for chebyshev distance between center voxel and neighbourhood boundary used to calculate energy maps.

  • laws_rotation_invariance (bool, optional, default: True) – Determines whether separable filters are applied in a pseudo-rotational invariant manner. This generates permutations of the filter and, as a consequence, additional response maps (filtered images). These maps are then merged using the pooling method (laws_pooling_method).

  • laws_pooling_method ({"max", "min", "mean", "sum"}, optional, default: "max") –

    Response maps are pooled to create a rotationally invariant response map (filtered image). This sets the method for pooling.

    • ”max”: Each voxel of the pooled response map represents the maximum value for that voxel in the underlying response maps.

    • ”min”: Each voxel of the pooled response map represents the minimum value for that voxel in the underlying response maps.

    • ”mean”: Each voxel of the pooled response map represents the mean value for that voxel in the underlying response maps. For band-pass and high-pass filters, this will likely result in values close to 0.0, and “max” or “min” pooling methods should be used instead.

    • ”sum”: Each voxel of the pooled response map is the sum of intensities for that voxel in the underlying response maps. Similar to the “mean” pooling method, but without the normalisation.

  • laws_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for Laws filters. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • gabor_sigma (float or list of float, optional) – Width of the Gaussian envelope in physical dimensions (e.g. mm). Multiple values can be specified.

  • gabor_lambda (float or list of float, optional) – Wavelength of the oscillator component of the Gabor filter, in physical dimensions (e.g. mm).

  • gabor_gamma (float or list of float, optional, default: 1.0) – Eccentricity parameter of the Gaussian envelope of the Gabor kernel. Defines width of y-axis relative to x-axis for 0-angle Gabor kernel. Default: 1.0

  • gabor_theta (float or list of flaot, optional, default: 0.0) – Initial angle of the Gabor filter in degrees (not radians). Multiple angles can be provided.

  • gabor_theta_step (float, optional, default: None) – Angle step size in degrees for in-plane rotational invariance. A value of 0.0 or None (default) disables stepping.

  • gabor_response ({"modulus", "abs", "magnitude", "angle", "phase", "argument", "real", "imaginary"}, optional, default: "modulus") – Type of response map (filtered image) created by Gabor filters. Gabor kernels consist of complex numbers, and the response map will be complex as well. The complex-valued response map is converted to a real-valued response map using the specified method.

  • gabor_rotation_invariance (bool, optional, default: False) – Determines whether (2D) Gabor filters are applied in a pseudo-rotational invariant manner. If True, Gabor filters are applied in each of the orthogonal planes.

  • gabor_pooling_method ({"max", "min", "mean", "sum"}, optional, default: "max") –

    Response maps are pooled to create a rotationally invariant response map (filtered image). This sets the method for pooling.

    • ”max”: Each voxel of the pooled response map represents the maximum value for that voxel in the underlying response maps.

    • ”min”: Each voxel of the pooled response map represents the minimum value for that voxel in the underlying response maps.

    • ”mean”: Each voxel of the pooled response map represents the mean value for that voxel in the underlying response maps. For band-pass and high-pass filters, this will likely result in values close to 0.0, and “max” or “min” pooling methods should be used instead.

    • ”sum”: Each voxel of the pooled response map is the sum of intensities for that voxel in the underlying response maps. Similar to the “mean” pooling method, but without the normalisation.

  • gabor_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for Gabor filters. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • mean_filter_kernel_size (int or list of int, optional) – Length of the kernel in pixels. Multiple values can be specified to create multiple response maps (filtered images).

  • mean_filter_boundary_condition (str, optional, default: "mirror") – Sets the boundary condition for mean filters. This supersedes any value set by the general boundary_condition parameter. See the boundary_condition parameter above for all valid options.

  • riesz_filter_order (float, list of float or list of list of float, optional) –

    Riesz-transformation order. If required, should be a 2 (2D filter), or 3-element (3D filter) integer vector, e.g. [0,0,1]. Multiple sets can be provided by nesting the list, e.g. [[0, 0, 1], [0, 1, 0]]. If an integer is provided, a set of filters is created. For example when riesz_filter_order = 2 and a 2D filter is used, the following Riesz-transformations are performed: [2, 0], [1, 1] and [0, 2].

    Note

    Riesz filter order uses the numpy coordinate ordering and represents (z, y, x) directions.

  • riesz_filter_tensor_sigma (float or list of float, optional) – Determines width of Gaussian filter used with Riesz filter banks.

  • **kwargs (dict, optional) – Unused keyword arguments.

Generic settings object

class mirp.settings.generic.SettingsClass(general_settings: None | GeneralSettingsClass = None, post_process_settings: None | ImagePostProcessingClass = None, perturbation_settings: None | ImagePerturbationSettingsClass = None, img_interpolate_settings: None | ImageInterpolationSettingsClass = None, roi_interpolate_settings: None | MaskInterpolationSettingsClass = None, roi_resegment_settings: None | ResegmentationSettingsClass = None, feature_extr_settings: None | FeatureExtractionSettingsClass = None, img_transform_settings: None | ImageTransformationSettingsClass = None, **kwargs: Unpack[None | GeneralSettingsClass | ImagePostProcessingClass | ImageInterpolationSettingsClass | MaskInterpolationSettingsClass | ResegmentationSettingsClass | FeatureExtractionSettingsClass | ImageTransformationSettingsClass])[source]

Bases: object

Container for objects used to configure the image processing and feature processing workflow. This object can be initialised in two ways:

  • By providing (already initialised) configuration objects as arguments.

  • By passing arguments to configuration objects as keyword arguments. These configuration objects will then be created while initialising this container.

Parameters:

See also

Creating a settings xml file

mirp.utilities.config_utilities.get_settings_xml(target_dir: str | Path)[source]

Creates a local copy of the settings xml file. This file can be used to configure the image processing and feature extraction workflow.

Parameters:

target_dir (str or Path) – Path where the settings xml file should be copied to.

Returns:

No return values. The settings xml is copied to the intended directory.

Return type:

None