Repository: scikit-image/scikit-image

Issue:
Reintroduce `dtype.convert`
## Description

`dtype.convert` used to be a very useful function in older versions of scikit-image.

In 0.17 it was decided that it should be removed without a deprecation cycle.

Not fun.

Could we get it back in 0.17.2 with a deprecation cycle?
https://github.com/scikit-image/scikit-image/pull/4590
If so, i can make the PR.


Discussion:
As I was saying in #4590 we did not deprecate because the function was not public (in the sense of not being exposed in the public API). @sciunto's first intent was to make it public (as you say it's a useful function, although most people don't know about it I guess since it's not public and we don't use it in any of the doc examples), but then we thought that it was not the right time to make this function public since the function will likely change a lot when we drop range rescaling.

That said, it does not hurt if we have a deprecation cycle for a non-public function, so if you make the PR I'll be happy to accept and backport if merged. Thoughts anyone?
ah the chronological orders were not clear to me. I get that it might be useless in the near future.

Since there is at least 1 person supporting this, I can make the PR.

Resolving patch:
diff --git a/skimage/util/dtype.py b/skimage/util/dtype.py
--- a/skimage/util/dtype.py
+++ b/skimage/util/dtype.py
@@ -349,6 +349,28 @@ def _convert(image, dtype, force_copy=False, uniform=False):
     return image.astype(dtype_out)
 
 
+def convert(image, dtype, force_copy=False, uniform=False):
+    warn("The use of this function is discouraged as its behavior may change "
+         "dramatically in scikit-image 1.0. This function will be removed"
+         "in scikit-image 1.0.", FutureWarning, stacklevel=2)
+    return _convert(image=image, dtype=dtype,
+                    force_copy=force_copy, uniform=uniform)
+
+
+if _convert.__doc__ is not None:
+    convert.__doc__ = _convert.__doc__ + """
+
+    Warns
+    -----
+    FutureWarning:
+        .. versionadded:: 0.17
+
+        The use of this function is discouraged as its behavior may change
+        dramatically in scikit-image 1.0. This function will be removed
+        in scikit-image 1.0.
+    """
+
+
 def img_as_float32(image, force_copy=False):
     """Convert an image to single-precision (32-bit) floating point format.
 


Test patch:
diff --git a/skimage/util/tests/test_dtype.py b/skimage/util/tests/test_dtype.py
--- a/skimage/util/tests/test_dtype.py
+++ b/skimage/util/tests/test_dtype.py
@@ -167,6 +167,22 @@ def test_float_conversion_dtype():
         assert y.dtype == np.dtype(dtype_out)
 
 
+def test_float_conversion_dtype_warns():
+    """Test that convert issues a warning when called"""
+    from skimage.util.dtype import convert
+    x = np.array([-1, 1])
+
+    # Test all combinations of dtypes convertions
+    dtype_combin = np.array(np.meshgrid(float_dtype_list,
+                                        float_dtype_list)).T.reshape(-1, 2)
+
+    for dtype_in, dtype_out in dtype_combin:
+        x = x.astype(dtype_in)
+        with expected_warnings(["The use of this function is discouraged"]):
+            y = convert(x, dtype_out)
+        assert y.dtype == np.dtype(dtype_out)
+
+
 def test_subclass_conversion():
     """Check subclass conversion behavior"""
     x = np.array([-1, 1])