DOC Ensures that sklearn.utils.extmath.randomized_svd passes numpydoc validation (#24607)

awinml · glemaitre · web-flow · commit aa7fd7ad0f94 · 2022-10-13T23:31:36.000+02:00
Co-authored-by: Guillaume Lemaitre &lt;g.lemaitre58@gmail.com&gt;
diff --git a/sklearn/tests/test_docstrings.py b/sklearn/tests/test_docstrings.py
@@ -13,7 +13,6 @@
 
 FUNCTION_DOCSTRING_IGNORE_LIST = [
     "sklearn.utils.extmath.fast_logdet",
-    "sklearn.utils.extmath.randomized_svd",
     "sklearn.utils.metaestimators.if_delegate_has_method",
 ]
 FUNCTION_DOCSTRING_IGNORE_LIST = set(FUNCTION_DOCSTRING_IGNORE_LIST)
diff --git a/sklearn/utils/extmath.py b/sklearn/utils/extmath.py
@@ -274,7 +274,7 @@ def randomized_svd(
     random_state="warn",
     svd_lapack_driver="gesdd",
 ):
-    """Computes a truncated randomized SVD.
+    """Compute a truncated randomized SVD.
 
     This method solves the fixed-rank approximation problem described in [1]_
     (problem (1.5), p5).
@@ -357,6 +357,15 @@ def randomized_svd(
 
         .. versionadded:: 1.2
 
+    Returns
+    -------
+    u : ndarray of shape (n_samples, n_components)
+        Unitary matrix having left singular vectors with signs flipped as columns.
+    s : ndarray of shape (n_components,)
+        The singular values, sorted in non-increasing order.
+    vh : ndarray of shape (n_components, n_features)
+        Unitary matrix having right singular vectors with signs flipped as rows.
+
     Notes
     -----
     This algorithm finds a (usually very good) approximate truncated
@@ -381,6 +390,17 @@ def randomized_svd(
 
     .. [3] An implementation of a randomized algorithm for principal component
       analysis A. Szlam et al. 2014
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from sklearn.utils.extmath import randomized_svd
+    >>> a = np.array([[1, 2, 3, 5],
+    ...               [3, 4, 5, 6],
+    ...               [7, 8, 9, 10]])
+    >>> U, s, Vh = randomized_svd(a, n_components=2, random_state=0)
+    >>> U.shape, s.shape, Vh.shape
+    ((3, 2), (2,), (2, 4))
     """
     if isinstance(M, (sparse.lil_matrix, sparse.dok_matrix)):
         warnings.warn(

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,6 @@`
`13`	`13`
`14`	`14`	`FUNCTION_DOCSTRING_IGNORE_LIST = [`
`15`	`15`	`"sklearn.utils.extmath.fast_logdet",`
`16`		`- "sklearn.utils.extmath.randomized_svd",`
`17`	`16`	`"sklearn.utils.metaestimators.if_delegate_has_method",`
`18`	`17`	`]`
`19`	`18`	`FUNCTION_DOCSTRING_IGNORE_LIST = set(FUNCTION_DOCSTRING_IGNORE_LIST)`