DOC Adds an example to PatchExtractor (#12819)

* Finalizes fix for #12202 from abandonned PR by @parul-l

* Completes 12202 fix abandoned by @parul-l

* Completes 12202 fix abandoned by @parul-l

* Extends 12202 fix over feature_extraction/image.py

* Closes #12202; white space removal

* Closes #12202; white space removal2

* Closes #12202; 3.5 compliance; added >>> in docstring code.

* Closes #12202; indentation discrep.

* Closes #12202; indentation discrep.2

* Example output formating; @jnotham

* Example output formating; forgot flake8

* Closes #12202; Removed excessive indentation in docstring (#wimlds)

* Closes #12202; Fixed inconsistent indentation in docstring (#wimlds)

* Closes #12202 (#wimlds); intentation, v3.5 compliance

* Closes #12202 (#wimlds); Output format issue solved with addition of # doctest: +NORMALIZE_WHITESPACE +DONT_ACCEPT_BLANKLINE +ELLIPSIS for print statements.

* Closes #12202 (#wimlds); Output format issue solved with addition of # doctest: +NORMALIZE_WHITESPACE +DONT_ACCEPT_BLANKLINE for print statements.

* Closes #12202 (#wimlds); Testing doctest direc.: removed DONT_ACCEPT_BLANKLINE (@jnothmam, @reshamas)

* Closes #12202 (#wimlds); Removed blank lines in doctest example.

sklearn/feature_extraction/image.py

@@ -51,7 +51,7 @@ def _make_edges_3d(n_x, n_y, n_z=1):
 
 
 def _compute_gradient_3d(edges, img):
-    n_x, n_y, n_z = img.shape
+    _, n_y, n_z = img.shape
     gradient = np.abs(img[edges[0] // (n_y * n_z),
                       (edges[0] % (n_y * n_z)) // n_z,
                       (edges[0] % (n_y * n_z)) % n_z] -
@@ -331,33 +331,33 @@ def extract_patches_2d(image, patch_size, max_patches=None, random_state=None):
     Returns
     -------
     patches : array, shape = (n_patches, patch_height, patch_width) or
-         (n_patches, patch_height, patch_width, n_channels)
-         The collection of patches extracted from the image, where `n_patches`
-         is either `max_patches` or the total number of patches that can be
-         extracted.
+        (n_patches, patch_height, patch_width, n_channels)
+        The collection of patches extracted from the image, where `n_patches`
+        is either `max_patches` or the total number of patches that can be
+        extracted.
 
     Examples
     --------
-    >>> import numpy as np
+    >>> from sklearn.datasets import load_sample_images
     >>> from sklearn.feature_extraction import image
-    >>> one_image = np.arange(16).reshape((4, 4))
-    >>> one_image
-    array([[ 0,  1,  2,  3],
-           [ 4,  5,  6,  7],
-           [ 8,  9, 10, 11],
-           [12, 13, 14, 15]])
+    >>> # Use the array data from the first image in this dataset:
+    >>> one_image = load_sample_images().images[0]
+    >>> print('Image shape: {}'.format(one_image.shape))
+    Image shape: (427, 640, 3)
     >>> patches = image.extract_patches_2d(one_image, (2, 2))
-    >>> patches.shape
-    (9, 2, 2)
-    >>> patches[0]
-    array([[0, 1],
-           [4, 5]])
-    >>> patches[1]
-    array([[1, 2],
-           [5, 6]])
-    >>> patches[8]
-    array([[10, 11],
-           [14, 15]])
+    >>> print('Patches shape: {}'.format(patches.shape))
+    Patches shape: (272214, 2, 2, 3)
+    >>> # Here are just two of these patches:
+    >>> print(patches[1]) # doctest: +NORMALIZE_WHITESPACE
+    [[[174 201 231]
+      [174 201 231]]
+     [[173 200 230]
+      [173 200 230]]]
+    >>> print(patches[800])# doctest: +NORMALIZE_WHITESPACE
+    [[[187 214 243]
+      [188 215 244]]
+     [[187 214 243]
+      [188 215 244]]]
     """
     i_h, i_w = image.shape[:2]
     p_h, p_w = patch_size
@@ -420,7 +420,6 @@ def reconstruct_from_patches_2d(patches, image_size):
     -------
     image : array, shape = image_size
         the reconstructed image
-
     """
     i_h, i_w = image_size[:2]
     p_h, p_w = patches.shape[1:3]
@@ -461,7 +460,21 @@ class PatchExtractor(BaseEstimator):
         If None, the random number generator is the RandomState instance used
         by `np.random`.
 
+    Examples
+    --------
+    >>> from sklearn.datasets import load_sample_images
+    >>> from sklearn.feature_extraction import image
+    >>> # Use the array data from the second image in this dataset:
+    >>> X = load_sample_images().images[1]
+    >>> print('Image shape: {}'.format(X.shape))
+    Image shape: (427, 640, 3)
+    >>> pe = image.PatchExtractor(patch_size=(2, 2))
+    >>> pe_fit = pe.fit(X)
+    >>> pe_trans = pe.transform(X)
+    >>> print('Patches shape: {}'.format(pe_trans.shape))
+    Patches shape: (545706, 2, 2)
     """
+
     def __init__(self, patch_size=None, max_patches=None, random_state=None):
         self.patch_size = patch_size
         self.max_patches = max_patches
@@ -498,7 +511,6 @@ def transform(self, X):
              The collection of patches extracted from the images, where
              `n_patches` is either `n_samples * max_patches` or the total
              number of patches that can be extracted.
-
         """
         self.random_state = check_random_state(self.random_state)
         n_images, i_h, i_w = X.shape[:3]