Rename nl_means_denoising to denoise_nl_means

TODO.txt

@@ -1,8 +1,11 @@
 Remember to list any API changes below in `doc/source/api_changes.txt`.
 
+
+
 Version 0.14
 ------------
 * Remove deprecated ``ntiles_*` kwargs in ``equalize_adapthist``.
+* Remove deprecated ``skimage.restoration.nl_means_denoising``.
 
 
 Version 0.13

doc/examples/plot_nonlocal_means.py

@@ -15,7 +15,7 @@ import numpy as np
 import matplotlib.pyplot as plt
 
 from skimage import data, img_as_float
-from skimage.restoration import nl_means_denoising
+from skimage.restoration import denoise_nl_means
 
 
 astro = img_as_float(data.astronaut())
@@ -24,7 +24,7 @@ astro = astro[30:180, 150:300]
 noisy = astro + 0.3 * np.random.random(astro.shape)
 noisy = np.clip(noisy, 0, 1)
 
-denoise = nl_means_denoising(noisy, 7, 9, 0.08)
+denoise = denoise_nl_means(noisy, 7, 9, 0.08)
 
 fig, ax = plt.subplots(ncols=2, figsize=(8, 4))
 

skimage/restoration/__init__.py

@@ -22,7 +22,12 @@ from .deconvolution import wiener, unsupervised_wiener, richardson_lucy
 from .unwrap import unwrap_phase
 from ._denoise import denoise_tv_chambolle, denoise_tv_bregman, \
                       denoise_bilateral
-from .non_local_means import nl_means_denoising
+from .non_local_means import denoise_nl_means
+from .._shared.utils import copy_func, deprecated
+
+nl_means_denoising = copy_func(denoise_nl_means, name='nl_means_denoising')
+nl_means_denoising = deprecated('skimage.restoration.denoise_nl_means')(nl_means_denoising)
+
 
 __all__ = ['wiener',
            'unsupervised_wiener',
@@ -31,4 +36,7 @@ __all__ = ['wiener',
            'denoise_tv_bregman',
            'denoise_tv_chambolle',
            'denoise_bilateral',
+           'denoise_nl_means',
            'nl_means_denoising']
+
+del copy_func, deprecated

skimage/restoration/non_local_means.py

@@ -6,8 +6,8 @@ from ._nl_means_denoising import (
     _fast_nl_means_denoising_3d)
 
 
-def nl_means_denoising(image, patch_size=7, patch_distance=11, h=0.1,
-                       multichannel=True, fast_mode=True):
+def denoise_nl_means(image, patch_size=7, patch_distance=11, h=0.1,
+                     multichannel=True, fast_mode=True):
     """
     Perform non-local means denoising on 2-D or 3-D grayscale images, and
     2-D RGB images.
@@ -41,10 +41,6 @@ def nl_means_denoising(image, patch_size=7, patch_distance=11, h=0.1,
     result : ndarray
         Denoised image, of same shape as `image`.
 
-    See Also
-    --------
-    fast_nl_means_denoising
-
     Notes
     -----
 
@@ -68,19 +64,19 @@ def nl_means_denoising(image, patch_size=7, patch_distance=11, h=0.1,
 
     image.size * patch_distance ** image.ndim
 
-    The computing time depends only weakly on the patch size, thanks to the
-    computation of the integral of patches distances for a given shift, that
-    reduces the number of operations [1]_. Therefore, this algorithm executes
-    faster than `nl_means_denoising`, at the expense of using twice as much
-    memory.
+    The computing time depends only weakly on the patch size, thanks to
+    the computation of the integral of patches distances for a given
+    shift, that reduces the number of operations [1]_. Therefore, this
+    algorithm executes faster than the classic algorith
+    (``fast_mode=False``), at the expense of using twice as much memory.
 
-    Compared to the classic non-local means algorithm implemented in
-    `nl_means_denoising`, all pixels of a patch contribute to the distance to
-    another patch with the same weight, no matter their distance to the center
-    of the patch. This coarser computation of the distance can result in a
-    slightly poorer denoising performance. Moreover, for small images (images
-    with a linear size that is only a few times the patch size), the classic
-    algorithm can be faster due to boundary effects.
+    Compared to the classic algorithm, all pixels of a patch contribute
+    to the distance to another patch with the same weight, no matter
+    their distance to the center of the patch. This coarser computation
+    of the distance can result in a slightly poorer denoising
+    performance. Moreover, for small images (images with a linear size
+    that is only a few times the patch size), the classic algorithm can
+    be faster due to boundary effects.
 
     The image is padded using the `reflect` mode of `skimage.util.pad`
     before denoising.
@@ -97,8 +93,8 @@ def nl_means_denoising(image, patch_size=7, patch_distance=11, h=0.1,
     --------
     >>> a = np.zeros((40, 40))
     >>> a[10:-10, 10:-10] = 1.
-    >>> a += 0.3*np.random.randn(*a.shape)
-    >>> denoised_a = nl_means_denoising(a, 7, 5, 0.1)
+    >>> a += 0.3 * np.random.randn(*a.shape)
+    >>> denoised_a = denoise_nl_means(a, 7, 5, 0.1)
     """
     if image.ndim == 2:
         image = image[..., np.newaxis]

skimage/restoration/tests/test_denoise.py

@@ -153,49 +153,49 @@ def test_nl_means_denoising_2d():
     img = np.zeros((40, 40))
     img[10:-10, 10:-10] = 1.
     img += 0.3*np.random.randn(*img.shape)
-    denoised = restoration.nl_means_denoising(img, 7, 5, 0.2, fast_mode=True)
+    denoised = restoration.denoise_nl_means(img, 7, 5, 0.2, fast_mode=True)
     # make sure noise is reduced
     assert img.std() > denoised.std()
-    denoised = restoration.nl_means_denoising(img, 7, 5, 0.2, fast_mode=False)
+    denoised = restoration.denoise_nl_means(img, 7, 5, 0.2, fast_mode=False)
     # make sure noise is reduced
     assert img.std() > denoised.std()
 
 
-def test_nl_means_denoising_2drgb():
+def test_denoise_nl_means_2drgb():
     # reduce image size because nl means is very slow
     img = np.copy(astro[:50, :50])
     # add some random noise
     img += 0.5 * img.std() * np.random.random(img.shape)
     img = np.clip(img, 0, 1)
-    denoised = restoration.nl_means_denoising(img, 7, 9, 0.3, fast_mode=True)
+    denoised = restoration.denoise_nl_means(img, 7, 9, 0.3, fast_mode=True)
     # make sure noise is reduced
     assert img.std() > denoised.std()
-    denoised = restoration.nl_means_denoising(img, 7, 9, 0.3, fast_mode=False)
+    denoised = restoration.denoise_nl_means(img, 7, 9, 0.3, fast_mode=False)
     # make sure noise is reduced
     assert img.std() > denoised.std()
 
 
-def test_nl_means_denoising_3d():
+def test_denoise_nl_means_3d():
     img = np.zeros((20, 20, 10))
     img[5:-5, 5:-5, 3:-3] = 1.
     img += 0.3*np.random.randn(*img.shape)
-    denoised = restoration.nl_means_denoising(img, 5, 4, 0.2, fast_mode=True,
+    denoised = restoration.denoise_nl_means(img, 5, 4, 0.2, fast_mode=True,
                                               multichannel=False)
     # make sure noise is reduced
     assert img.std() > denoised.std()
-    denoised = restoration.nl_means_denoising(img, 5, 4, 0.2, fast_mode=False,
+    denoised = restoration.denoise_nl_means(img, 5, 4, 0.2, fast_mode=False,
                                               multichannel=False)
     # make sure noise is reduced
     assert img.std() > denoised.std()
 
 
-def test_nl_means_denoising_multichannel():
+def test_denoise_nl_means_multichannel():
     img = np.zeros((21, 20, 10))
     img[10, 9:11, 2:-2] = 1.
     img += 0.3*np.random.randn(*img.shape)
-    denoised_wrong_multichannel = restoration.nl_means_denoising(img,
+    denoised_wrong_multichannel = restoration.denoise_nl_means(img,
                     5, 4, 0.1, fast_mode=True, multichannel=True)
-    denoised_ok_multichannel = restoration.nl_means_denoising(img,
+    denoised_ok_multichannel = restoration.denoise_nl_means(img,
                     5, 4, 0.1, fast_mode=True, multichannel=False)
     snr_wrong = 10 * np.log10(1. /
                             ((denoised_wrong_multichannel - img)**2).mean())
@@ -204,9 +204,9 @@ def test_nl_means_denoising_multichannel():
     assert snr_ok > snr_wrong
 
 
-def test_nl_means_denoising_wrong_dimension():
+def test_denoise_nl_means_wrong_dimension():
     img = np.zeros((5, 5, 5, 5))
-    assert_raises(NotImplementedError, restoration.nl_means_denoising, img)
+    assert_raises(NotImplementedError, restoration.denoise_nl_means, img)
 
 
 def test_no_denoising_for_small_h():
@@ -214,9 +214,9 @@ def test_no_denoising_for_small_h():
     img[10:-10, 10:-10] = 1.
     img += 0.3*np.random.randn(*img.shape)
     # very small h should result in no averaging with other patches
-    denoised = restoration.nl_means_denoising(img, 7, 5, 0.01, fast_mode=True)
+    denoised = restoration.denoise_nl_means(img, 7, 5, 0.01, fast_mode=True)
     assert np.allclose(denoised, img)
-    denoised = restoration.nl_means_denoising(img, 7, 5, 0.01, fast_mode=False)
+    denoised = restoration.denoise_nl_means(img, 7, 5, 0.01, fast_mode=False)
     assert np.allclose(denoised, img)