Skip to content

Commit

Permalink
Updated documentation to address #69.
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexzwanenburg
alexzwanenburg committed Apr 3, 2024
1 parent 4d5df12 commit f8d0d8e
Show file tree
Hide file tree
Showing 6 changed files with 88 additions and 40 deletions.
56 changes: 48 additions & 8 deletions docs_source/source/quantitative_image_analysis.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ Process image and compute quantitative image features
=====================================================

Two of the main uses for MIRP are to process images and compute quantitative features from images. Both use the same
standardized, IBSI 1 and IBSI 2 compliant, workflow. Two versions of the image processing and feature computation
function exist:
standardized, IBSI 1 and IBSI 2 compliant, workflow [Zwanenburg2020]_, [Whybra2024]_. Two versions of the image
processing and feature computation function exist:

* :func:`~mirp.extract_features_and_images.extract_features_and_images`: conventional function that processes images and
computes features.
Expand All @@ -15,13 +15,18 @@ images) and only processing images (without computing features):

* :func:`~mirp.extract_features_and_images.extract_features`: conventional function that only computes features.
* :func:`~mirp.extract_features_and_images.extract_features_generator`: generator that only yields feature values.
* :func:`~mirp.extract_features_and_images.extract_features_and_images`: conventional function that only processes images.
* :func:`~mirp.extract_features_and_images.extract_features_and_images_generator`: generator that yields processed images.
* :func:`~mirp.extract_features_and_images.extract_images`: conventional function that only processes images.
* :func:`~mirp.extract_features_and_images.extract_images_generator`: generator that yields processed images.

Examples
--------

MIRP can compute features from regions of interest in images. The simplest example is:
MIRP can compute features from regions of interest in images. The features are described in [Zwanenburg2016]_.

Minimal example
^^^^^^^^^^^^^^^

The following computes features from a single image and mask:

.. code-block:: python
Expand All @@ -37,6 +42,9 @@ MIRP can compute features from regions of interest in images. The simplest examp
The ``base_discretisation_method`` and its corresponding parameters are required as long as any texture or
intensity-histogram features are involved.

Interpolation example
^^^^^^^^^^^^^^^^^^^^^

A more realistic example involves interpolation to ensure that voxel spacing is the same for all images in a dataset.
For example, a positron emission tomography (PET) dataset may be resampled to 3 by 3 by 3 mm isotropic voxels. This
is achieved by providing the ``new_spacing`` argument, i.e. ``new_spacing=3.0`` or ``new_spacing=[3.0, 3.0, 3.0]``.
Expand All @@ -57,6 +65,9 @@ is achieved by providing the ``new_spacing`` argument, i.e. ``new_spacing=3.0``
Here, ``image_modality="PET"`` is used to declare that the image is a PET image. If this is a DICOM image, this
argument is not necessary -- the modality can be inferred from the metadata.

Slice-wise example
^^^^^^^^^^^^^^^^^^

Sometimes, in-plane resolution is much higher than axial resolution. For example, in (older) computed tomography (CT)
images, in-plane resolution may be 1 by 1 mm, but the distance between slices can be 7 mm or greater.
Resampling to isotropic 1 by 1 by 1 mm voxels causes considerable data to be inferred between slices,
Expand All @@ -79,6 +90,9 @@ This is achieved by providing the ``by_slice`` argument, i.e. ``by_slice=True``.
In the above example ``new_spacing=1.0`` causes all images to be resampled in-plane to a 1 mm resolution.

Fixed Bin Number discretisation example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The previous examples used the *Fixed Bin Number* to discretise intensities within the mask into a fixed number of bins.
For some imaging modalities, intensities carry a physical (or at least calibrated) meaning, such as Hounsfield units in
computed tomography and standardised uptake values in positron emission tomography. For these *Fixed Bin Size* (also
Expand All @@ -102,6 +116,9 @@ Because the resegmentation range is not set, the lower bound of the initial bin
base_discretisation_bin_width=25.0
)
Mask resegmentation example
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the region of interest contained in the mask in the above example covers soft tissue, this default might not be good.
We can change this by providing the ``resegmentation_intensity_range`` argument. Here, we provide a window more fitting
for soft tissues: ``resegmentation_intensity_range=[-200.0, 200.0]``. Thus the lower bound of the initial bin is set to
Expand All @@ -121,8 +138,12 @@ for soft tissues: ``resegmentation_intensity_range=[-200.0, 200.0]``. Thus the l
base_discretisation_bin_width=25.0
)
Basic image filter example
^^^^^^^^^^^^^^^^^^^^^^^^^^

The above examples all compute features from the base image. Filters can be applied to images to enhance patterns such
as edges. In the example below, we compute features from a Laplacian-of-Gaussian filtered image:
as edges. MIRP implements multiple filters [Depeursinge2020]_. In the example below, we compute features from a
Laplacian-of-Gaussian filtered image:

.. code-block:: python
Expand All @@ -138,6 +159,9 @@ as edges. In the example below, we compute features from a Laplacian-of-Gaussian
laplacian_of_gaussian_sigma=2.0
)
Image filter with additional features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, only statistical features are computed from filtered images, and features are still extracted from the
base image. You can change this by specifying ``base_feature_families="none"`` (to prevent computing features from
the base image) and specifying ``response_map_feature_families``. In the example below, we compute both statistical
Expand All @@ -159,8 +183,9 @@ features and intensity histogram features.
Even though intensity histogram features require discretisation, you don't have to provide a discretisation method
and associated parameters. This is because for many filters, intensities in the filtered images no longer represent a
measurable quantity. Hence a *Fixed Bin Number* algorithm is used by default, with 16 bins. These parameters can be
changed using the ``response_map_discretisation_method`` and ``response_map_discretisation_n_bins`` arguments.
measurable quantity such as Hounsfield Units. Hence a *Fixed Bin Number* algorithm is used by default, with 16 bins.
These parameters can be changed using the ``response_map_discretisation_method`` and
``response_map_discretisation_n_bins`` arguments.

API documentation
-----------------
Expand All @@ -177,3 +202,18 @@ API documentation

.. autofunction:: mirp.extract_features_and_images.extract_images_generator

References
----------
.. [Depeursinge2020] Depeursinge A, Andrearczyk V, Whybra P, van Griethuysen J, Mueller H, Schaer R, et al.
Standardised convolutional filtering for radiomics. arXiv [eess.IV]. 2020. doi:10.48550/arXiv.2006.05470
.. [Whybra2024] Whybra P, Zwanenburg A, Andrearczyk V, Schaer R, Apte AP, Ayotte A, et al. The Image Biomarker
Standardization Initiative: Standardized Convolutional Filters for Reproducible Radiomics and Enhanced Clinical
Insights. Radiology. 2024;310: e231319. doi:10.1148/radiol.231319
.. [Zwanenburg2016] Zwanenburg A, Leger S, Vallieres M, Loeck S. Image Biomarker Standardisation Initiative. arXiv
[cs.CV] 2016. doi:10.48550/arXiv.1612.070035
.. [Zwanenburg2020] Zwanenburg A, Vallieres M, Abdalah MA, Aerts HJWL, Andrearczyk V, Apte A, et al. The Image
Biomarker Standardization Initiative: Standardized Quantitative Radiomics for High-Throughput Image-based
Phenotyping. Radiology. 2020;295: 328-338. doi:10.1148/radiol.2020191145
5 changes: 3 additions & 2 deletions docs_source/source/quick_start.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,8 @@ Note that metadata for other file types (e.g. NIfTI) are considerably more limit

References
----------
.. [Zwanenburg2016] Zwanenburg A, Leger S, Vallieres M, Loeck S. Image Biomarker Standardisation Initiative. arXiv
[cs.CV] 2016. doi:10.48550/arXiv.1612.070035

.. [Simonyan2015] Simonyan K, Zisserman A. Very Deep Convolutional Networks for Large-Scale Image Recognition. arXiv
[cs.CV] 2014. doi:10.48550/arXiv.1409.1556
.. [Zwanenburg2016] Zwanenburg A, Leger S, Vallieres M, Loeck S. Image Biomarker Standardisation Initiative. arXiv
[cs.CV] 2016. doi:10.48550/arXiv.1612.070035
2 changes: 1 addition & 1 deletion mirp/settings/feature_parameters.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
class FeatureExtractionSettingsClass:
"""
Parameters related to feature computation. Many are conditional on the type of features that will be computed (
``base_feature_families``).
``base_feature_families``). Features and their parameters are defined `here <https://arxiv.org/abs/1612.07003>`_.
Parameters
----------
Expand Down
3 changes: 2 additions & 1 deletion mirp/settings/image_processing_parameters.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ class ImagePostProcessingClass:
deviation of intensities.
.. note::
intensity normalisation may remove any physical meaning of intensity units.
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
Expand Down
10 changes: 7 additions & 3 deletions mirp/settings/interpolation_parameters.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,7 @@
class ImageInterpolationSettingsClass:
"""
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. Note that when the
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 may be recommended.
voxel spacing to ensure that their spatial representation does not vary between samples.
For parameters related to mask interpolation / resampling, see
:class:`~mirp.settings.interpolation_parameters.MaskInterpolationSettingsClass`.
Expand Down Expand Up @@ -38,9 +36,15 @@ class ImageInterpolationSettingsClass:
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.] <http://dx.doi.org/10.1371/journal.pone.0178524>`_.
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.
<http://dx.doi.org/10.1038/s41598-018-36938-4>`_.
**kwargs: dict, optional
Unused keyword arguments.
Expand Down
52 changes: 27 additions & 25 deletions mirp/settings/transformation_parameters.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
class ImageTransformationSettingsClass:
"""
Parameters related to image transformation using filters. Many parameters are conditional on the selected image
filter (``filter_kernels``). By default, only statistical features are computed from filtered images.
filter (``filter_kernels``). Filters and their parameters are defined `here <https://arxiv.org/abs/2006.05470>`_
By default, only statistical features are computed from filtered images.
.. note::
Many feature extraction parameters are copied from
Expand Down Expand Up @@ -60,7 +61,7 @@ class ImageTransformationSettingsClass:
* "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, because these are mask-based and are invariant to filtering.
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.
Expand Down Expand Up @@ -124,7 +125,7 @@ class ImageTransformationSettingsClass:
.. 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 of Riesz transformations is unlikely to be reproducible.
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
Expand Down Expand Up @@ -154,17 +155,17 @@ class ImageTransformationSettingsClass:
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. 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.
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. These maps are then merged using
the pooling method (``separable_wavelet_pooling_method``).
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. This sets the method for
pooling.
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.
Expand All @@ -190,9 +191,9 @@ class ImageTransformationSettingsClass:
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 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.
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
Expand All @@ -215,8 +216,8 @@ class ImageTransformationSettingsClass:
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 for filters with different widths (``laplacian_of_gaussian_sigma``)
are pooled.
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.
Expand All @@ -240,19 +241,19 @@ class ImageTransformationSettingsClass:
``by_slice=False``).
laws_compute_energy: bool, optional, default: True
Determine whether an energy image should be computed, or just the response map.
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. These maps are then merged using
the pooling method (``laws_pooling_method``).
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. This sets the method for
pooling.
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.
Expand Down Expand Up @@ -286,17 +287,17 @@ class ImageTransformationSettingsClass:
stepping.
gabor_response: {"modulus", "abs", "magnitude", "angle", "phase", "argument", "real", "imaginary"}, optional, default: "modulus"
Type of response map 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.
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. This sets the method for
pooling.
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.
Expand All @@ -313,7 +314,8 @@ class ImageTransformationSettingsClass:
``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.
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
Expand Down

0 comments on commit f8d0d8e

Please sign in to comment.