Standardize function signature of compare_images.

TODO.txt

@@ -8,6 +8,11 @@ Version 0.25
   and remove `test_gaussian.py::test_deprecated_gaussian_output`.
   Make arguments after the deprecated `output` parameter, keyword only:
   `gaussian(image, sigma, *, ...)`.
+* In `skimage/util/compare.py`, remove deprecated parameter `image2` as
+  well as `test_compare_images_replaced_param` in `skimage/util/tests/test_compare.py`
+  (and all `pytest.warns(FutureWarning)` context managers there).
+  Make all arguments from `method` (inclusive) keyword-only:
+  `compare_images(image0, image1, *, method='diff', ...)`.
 
 Version 0.26
 ------------

skimage/util/compare.py

@@ -1,27 +1,143 @@
+import functools
+import inspect
+import warnings
+from itertools import product
+
 import numpy as np
 
 from .dtype import img_as_float
-from itertools import product
+from skimage._shared.utils import (
+    DEPRECATED,
+)
+
+
+class _rename_image_params:
+    """Deprecate parameters `image1, image2` in favour of `image0, image1` in
+    function `compare_images`.
+
+    Parameters
+    ----------
+    deprecated_name : str
+        The name of the deprecated parameter.
+    start_version : str
+        The package version in which the warning was introduced.
+    stop_version : str
+        The package version in which the warning will be replaced by
+        an error / the deprecation is completed.
+    """
+
+    def __init__(
+        self,
+        deprecated_name,
+        *,
+        start_version,
+        stop_version,
+    ):
+        self.deprecated_name = deprecated_name
+        self.start_version = start_version
+        self.stop_version = stop_version
+
+    def __call__(self, func):
+        parameters = inspect.signature(func).parameters
+        if parameters['image2'].default is not DEPRECATED:
+            raise RuntimeError(
+                f"Expected `{self.deprecated_name}` to have the value {DEPRECATED!r} "
+                f"to indicate its status in the rendered signature."
+            )
+        warning_message = (
+            "Since version 0.23, the two input images are named `image0` and "
+            "`image1` (instead of `image1` and `image2`, respectively). Please use "
+            "`image0, image1` to avoid this warning for now, and avoid an error "
+            "from version 0.25 onwards."
+        )
+        wm_method = (
+            "Starting in version 0.25, all arguments following `image0, image1` "
+            "(including `method`) will be keyword-only. Please pass `method=` "
+            "in the function call to avoid this warning for now, and avoid an error "
+            "from version 0.25 onwards."
+        )
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if 'image2' not in kwargs.keys():
+                kwargs['image2'] = DEPRECATED
+
+            # Pass first all args as kwargs
+            if len(args) > 0:
+                kwargs['image0'] = args[0]
+                if len(args) > 1:
+                    kwargs['image1'] = args[1]
+                    if len(args) > 2 and args[len(args) - 1] in [
+                        'diff',
+                        'blend',
+                        'checkerboard',
+                    ]:
+                        warnings.warn(wm_method, category=FutureWarning)
+                        kwargs['method'] = args[len(args) - 1]
+
+            if kwargs['image2'] is not DEPRECATED:
+                deprecated_value = kwargs['image2']
+                kwargs['image2'] = DEPRECATED
+                if 'image1' in kwargs.keys():
+                    if 'image0' in kwargs.keys():
+                        raise RuntimeError(
+                            "Use `image0, image1` to pass the two input images."
+                        )
+                    else:
+                        warnings.warn(warning_message, category=FutureWarning)
+                        args = (kwargs['image1'], deprecated_value)
+                else:
+                    if 'image0' in kwargs.keys():
+                        warnings.warn(warning_message, category=FutureWarning)
+                        args = (kwargs['image0'], deprecated_value)
+
+            kwargs.pop('image2')
+            if 'image0' in kwargs.keys():
+                kwargs.pop('image0')
+            if 'image1' in kwargs.keys():
+                kwargs.pop('image1')
+            return func(*args, **kwargs)
+
+        return wrapper
 
 
-def compare_images(image1, image2, method='diff', *, n_tiles=(8, 8)):
+@_rename_image_params("image2", start_version="0.23", stop_version="0.25")
+def compare_images(image0, image1, image2=DEPRECATED, method='diff', *, n_tiles=(8, 8)):
     """
     Return an image showing the differences between two images.
 
     .. versionadded:: 0.16
 
     Parameters
     ----------
-    image1, image2 : ndarray, shape (M, N)
-        Images to process, must be of the same shape.
+    image0 : ndarray, shape (M, N)
+        First input image.
+
+        .. versionadded:: 0.23
+    image1 : ndarray, shape (M, N)
+        Second input image. Must be of the same shape as `image0`.
+
+        .. versionchanged:: 0.23
+            `image1` changed from being the name of the first image to that of
+            the second image.
     method : string, optional
         Method used for the comparison.
         Valid values are {'diff', 'blend', 'checkerboard'}.
         Details are provided in the note section.
+
+    .. versionchanged:: 0.23
+            This parameter is now keyword-only.
     n_tiles : tuple, optional
         Used only for the `checkerboard` method. Specifies the number
         of tiles (row, column) to divide the image.
 
+    Other Parameters
+    ----------------
+    image2 : DEPRECATED
+        Deprecated in favor of `image1`.
+
+        .. deprecated:: 0.23
+
     Returns
     -------
     comparison : ndarray, shape (M, N)
@@ -34,11 +150,12 @@ def compare_images(image1, image2, method='diff', *, n_tiles=(8, 8)):
     ``'checkerboard'`` makes tiles of dimension `n_tiles` that display
     alternatively the first and the second image.
     """
-    if image1.shape != image2.shape:
+
+    if image1.shape != image0.shape:
         raise ValueError('Images must have the same shape.')
 
-    img1 = img_as_float(image1)
-    img2 = img_as_float(image2)
+    img1 = img_as_float(image0)
+    img2 = img_as_float(image1)
 
     if method == 'diff':
         comparison = np.abs(img2 - img1)

skimage/util/tests/test_compare.py

@@ -1,15 +1,13 @@
 import numpy as np
-
-from skimage._shared.testing import assert_array_equal
-from skimage._shared import testing
+import pytest
 
 from skimage.util.compare import compare_images
 
 
-def test_compate_images_ValueError_shape():
+def test_compare_images_ValueError_shape():
     img1 = np.zeros((10, 10), dtype=np.uint8)
     img2 = np.zeros((10, 1), dtype=np.uint8)
-    with testing.raises(ValueError):
+    with pytest.raises(ValueError):
         compare_images(img1, img2)
 
 
@@ -20,8 +18,22 @@ def test_compare_images_diff():
     img2[3:8, 0:8] = 255
     expected_result = np.zeros_like(img1, dtype=np.float64)
     expected_result[3:8, 0:3] = 1
-    result = compare_images(img1, img2, method='diff')
-    assert_array_equal(result, expected_result)
+    with pytest.warns(FutureWarning):
+        result = compare_images(img1, img2, 'diff')
+    np.testing.assert_array_equal(result, expected_result)
+
+
+def test_compare_images_replaced_param():
+    img1 = np.zeros((10, 10), dtype=np.uint8)
+    img1[3:8, 3:8] = 255
+    img2 = np.zeros_like(img1)
+    img2[3:8, 0:8] = 255
+    with pytest.warns(FutureWarning):
+        compare_images(image1=img1, image2=img2)
+    with pytest.warns(FutureWarning):
+        compare_images(image0=img1, image2=img2)
+    with pytest.warns(FutureWarning):
+        compare_images(img1, image2=img2)
 
 
 def test_compare_images_blend():
@@ -33,7 +45,7 @@ def test_compare_images_blend():
     expected_result[3:8, 3:8] = 1
     expected_result[3:8, 0:3] = 0.5
     result = compare_images(img1, img2, method='blend')
-    assert_array_equal(result, expected_result)
+    np.testing.assert_array_equal(result, expected_result)
 
 
 def test_compare_images_checkerboard_default():
@@ -45,9 +57,9 @@ def test_compare_images_checkerboard_default():
     exp_row2 = np.array([1., 1., 0., 0., 1., 1., 0., 0., 1., 1., 0., 0., 1., 1., 0., 0.])
     # fmt: on
     for i in (0, 1, 4, 5, 8, 9, 12, 13):
-        assert_array_equal(res[i, :], exp_row1)
+        np.testing.assert_array_equal(res[i, :], exp_row1)
     for i in (2, 3, 6, 7, 10, 11, 14, 15):
-        assert_array_equal(res[i, :], exp_row2)
+        np.testing.assert_array_equal(res[i, :], exp_row2)
 
 
 def test_compare_images_checkerboard_tuple():
@@ -61,6 +73,6 @@ def test_compare_images_checkerboard_tuple():
         [1.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0]
     )
     for i in (0, 1, 2, 3, 8, 9, 10, 11):
-        assert_array_equal(res[i, :], exp_row1)
+        np.testing.assert_array_equal(res[i, :], exp_row1)
     for i in (4, 5, 6, 7, 12, 13, 14, 15):
-        assert_array_equal(res[i, :], exp_row2)
+        np.testing.assert_array_equal(res[i, :], exp_row2)