Repository: scikit-image/scikit-image

Issue:
skimage.segmentation.quickshift signature is missing from API docs
See http://scikit-image.org/docs/dev/api/skimage.segmentation.html#quickshift .
Probably, due to `float` in https://github.com/scikit-image/scikit-image/blob/master/skimage/segmentation/_quickshift.pyx#L17 .



Discussion:
@ahojnnes Hi! How the docs are being deployed? When to expect website to be updated to verify the fix?

@soupault, the dev docs are automatically deployed when a PR is merged.  https://github.com/blink1073/scikit-image/blob/master/tools/deploy_docs.sh

@blink1073 I see, thanks!
The issue isn't fixed then. :( Any other ideas on the cause?

@soupault The function needs a pure python wrapper, see e.g. `slic()`.

@ahojnnes Thanks! That was one of my top2 guesses :). It is really strange to me that the docstring is handled correctly, while the signature isn't.

Probably just a limitation of sphinx.


Resolving patch:
diff --git a/skimage/segmentation/_quickshift.py b/skimage/segmentation/_quickshift.py
new file mode 100644
--- /dev/null
+++ b/skimage/segmentation/_quickshift.py
@@ -0,0 +1,74 @@
+import numpy as np
+
+import scipy.ndimage as ndi
+
+from ..util import img_as_float
+from ..color import rgb2lab
+
+from ._quickshift_cy import _quickshift_cython
+
+
+def quickshift(image, ratio=1.0, kernel_size=5, max_dist=10,
+               return_tree=False, sigma=0, convert2lab=True, random_seed=42):
+    """Segments image using quickshift clustering in Color-(x,y) space.
+
+    Produces an oversegmentation of the image using the quickshift mode-seeking
+    algorithm.
+
+    Parameters
+    ----------
+    image : (width, height, channels) ndarray
+        Input image.
+    ratio : float, optional, between 0 and 1 (default 1).
+        Balances color-space proximity and image-space proximity.
+        Higher values give more weight to color-space.
+    kernel_size : float, optional (default 5)
+        Width of Gaussian kernel used in smoothing the
+        sample density. Higher means fewer clusters.
+    max_dist : float, optional (default 10)
+        Cut-off point for data distances.
+        Higher means fewer clusters.
+    return_tree : bool, optional (default False)
+        Whether to return the full segmentation hierarchy tree and distances.
+    sigma : float, optional (default 0)
+        Width for Gaussian smoothing as preprocessing. Zero means no smoothing.
+    convert2lab : bool, optional (default True)
+        Whether the input should be converted to Lab colorspace prior to
+        segmentation. For this purpose, the input is assumed to be RGB.
+    random_seed : int, optional (default 42)
+        Random seed used for breaking ties.
+
+    Returns
+    -------
+    segment_mask : (width, height) ndarray
+        Integer mask indicating segment labels.
+
+    Notes
+    -----
+    The authors advocate to convert the image to Lab color space prior to
+    segmentation, though this is not strictly necessary. For this to work, the
+    image must be given in RGB format.
+
+    References
+    ----------
+    .. [1] Quick shift and kernel methods for mode seeking,
+           Vedaldi, A. and Soatto, S.
+           European Conference on Computer Vision, 2008
+    """
+
+    image = img_as_float(np.atleast_3d(image))
+    if convert2lab:
+        if image.shape[2] != 3:
+            ValueError("Only RGB images can be converted to Lab space.")
+        image = rgb2lab(image)
+
+    if kernel_size < 1:
+        raise ValueError("`kernel_size` should be >= 1.")
+
+    image = ndi.gaussian_filter(image, [sigma, sigma, 0])
+    image = np.ascontiguousarray(image * ratio)
+
+    segment_mask = _quickshift_cython(
+        image, kernel_size=kernel_size, max_dist=max_dist,
+        return_tree=return_tree, random_seed=random_seed)
+    return segment_mask
diff --git a/skimage/segmentation/setup.py b/skimage/segmentation/setup.py
--- a/skimage/segmentation/setup.py
+++ b/skimage/segmentation/setup.py
@@ -14,8 +14,8 @@ def configuration(parent_package='', top_path=None):
     cython(['_felzenszwalb_cy.pyx'], working_path=base_path)
     config.add_extension('_felzenszwalb_cy', sources=['_felzenszwalb_cy.c'],
                          include_dirs=[get_numpy_include_dirs()])
-    cython(['_quickshift.pyx'], working_path=base_path)
-    config.add_extension('_quickshift', sources=['_quickshift.c'],
+    cython(['_quickshift_cy.pyx'], working_path=base_path)
+    config.add_extension('_quickshift_cy', sources=['_quickshift_cy.c'],
                          include_dirs=[get_numpy_include_dirs()])
     cython(['_slic.pyx'], working_path=base_path)
     config.add_extension('_slic', sources=['_slic.c'],


Test patch:
diff --git a/skimage/segmentation/tests/test_quickshift.py b/skimage/segmentation/tests/test_quickshift.py
--- a/skimage/segmentation/tests/test_quickshift.py
+++ b/skimage/segmentation/tests/test_quickshift.py
@@ -41,7 +41,7 @@ def test_color():
     assert_array_equal(seg[10:, 10:], 3)
 
     seg2 = quickshift(img, kernel_size=1, max_dist=2, random_seed=0,
-            convert2lab=False, sigma=0)
+                      convert2lab=False, sigma=0)
     # very oversegmented:
     assert_equal(len(np.unique(seg2)), 7)
     # still don't cross lines