From cd6e4d52d9bcd8d2152b97c9cf8902eeec4642ca Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Wed, 8 Jan 2020 23:23:01 +0530 Subject: [PATCH] DOC improve random_state docstring from decomposition module (#11902) * [MRG] Fix random_state docstrings in decomposition module * Add more details, and specify reproducibility * [MRG] docs for random_state in decomposition module Update the wording for reproducible results. * [MRG] Update doc for optional parameter to match numpy doc style * apply new style Co-authored-by: Guillaume Lemaitre --- sklearn/decomposition/_dict_learning.py | 45 ++++++++++++----------- sklearn/decomposition/_factor_analysis.py | 9 ++--- sklearn/decomposition/_fastica.py | 20 +++++----- sklearn/decomposition/_kernel_pca.py | 9 ++--- sklearn/decomposition/_lda.py | 8 ++-- sklearn/decomposition/_nmf.py | 39 ++++++++++---------- sklearn/decomposition/_pca.py | 9 ++--- sklearn/decomposition/_sparse_pca.py | 19 +++++----- sklearn/decomposition/_truncated_svd.py | 9 ++--- 9 files changed, 80 insertions(+), 87 deletions(-) diff --git a/sklearn/decomposition/_dict_learning.py b/sklearn/decomposition/_dict_learning.py index a2f3f601f41..f19305dbfc2 100644 --- a/sklearn/decomposition/_dict_learning.py +++ b/sklearn/decomposition/_dict_learning.py @@ -361,11 +361,10 @@ def _update_dict(dictionary, Y, code, verbose=False, return_r2=False, Whether to compute and return the residual sum of squares corresponding to the computed solution. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used for randomly initializing the dictionary. Pass an int for + reproducible results across multiple function calls. + See :term:`Glossary `. positive : boolean, optional Whether to enforce positivity when finding the dictionary. @@ -483,10 +482,9 @@ def dict_learning(X, n_components, alpha, max_iter=100, tol=1e-8, To control the verbosity of the procedure. random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + Used for randomly initializing the dictionary. Pass an int for + reproducible results across multiple function calls. + See :term:`Glossary `. return_n_iter : bool Whether or not to return the number of iterations. @@ -690,10 +688,11 @@ def dict_learning_online(X, n_components=2, alpha=1, n_iter=100, initialization. random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + Used for initializing the dictionary when ``dict_init`` is not + specified, randomly shuffling the data when ``shuffle`` is set to + ``True``, and updating the dictionary. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. return_inner_stats : boolean, optional Return the inner statistics A (dictionary covariance) and B @@ -1132,11 +1131,12 @@ class DictionaryLearning(SparseCodingMixin, BaseEstimator): its negative part and its positive part. This can improve the performance of downstream classifiers. - random_state : int, RandomState instance or None, default=None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance or None, optional (default=None) + Used for initializing the dictionary when ``dict_init`` is not + specified, randomly shuffling the data when ``shuffle`` is set to + ``True``, and updating the dictionary. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. positive_code : bool, default=False Whether to enforce positivity when finding the code. @@ -1323,10 +1323,11 @@ class MiniBatchDictionaryLearning(SparseCodingMixin, BaseEstimator): performance of downstream classifiers. random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + Used for initializing the dictionary when ``dict_init`` is not + specified, randomly shuffling the data when ``shuffle`` is set to + ``True``, and updating the dictionary. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. positive_code : bool Whether to enforce positivity when finding the code. diff --git a/sklearn/decomposition/_factor_analysis.py b/sklearn/decomposition/_factor_analysis.py index 14f0648d937..f9bb249c8a0 100644 --- a/sklearn/decomposition/_factor_analysis.py +++ b/sklearn/decomposition/_factor_analysis.py @@ -89,11 +89,10 @@ class FactorAnalysis(TransformerMixin, BaseEstimator): Number of iterations for the power method. 3 by default. Only used if ``svd_method`` equals 'randomized' - random_state : int, RandomState instance or None, optional (default=0) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. Only used when ``svd_method`` equals 'randomized'. + random_state : int, RandomState instance, default=None + Only used when ``svd_method`` equals 'randomized'. Pass an int for + reproducible results across multiple function calls. + See :term:`Glossary `. Attributes ---------- diff --git a/sklearn/decomposition/_fastica.py b/sklearn/decomposition/_fastica.py index c191f5e41ab..44e665556b8 100644 --- a/sklearn/decomposition/_fastica.py +++ b/sklearn/decomposition/_fastica.py @@ -202,11 +202,11 @@ def fastica(X, n_components=None, algorithm="parallel", whiten=True, Initial un-mixing array of dimension (n.comp,n.comp). If None (default) then an array of normal r.v.'s is used. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used to initialize ``w_init`` when not specified, with a + normal distribution. Pass an int, for reproducible results + across multiple function calls. + See :term:`Glossary `. return_X_mean : bool, optional If True, X_mean is returned too. @@ -341,11 +341,11 @@ class FastICA(TransformerMixin, BaseEstimator): w_init : None of an (n_components, n_components) ndarray The mixing matrix to be used to initialize the algorithm. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used to initialize ``w_init`` when not specified, with a + normal distribution. Pass an int, for reproducible results + across multiple function calls. + See :term:`Glossary `. Attributes ---------- diff --git a/sklearn/decomposition/_kernel_pca.py b/sklearn/decomposition/_kernel_pca.py index 169b0942e74..a8559f34159 100644 --- a/sklearn/decomposition/_kernel_pca.py +++ b/sklearn/decomposition/_kernel_pca.py @@ -76,11 +76,10 @@ class KernelPCA(TransformerMixin, BaseEstimator): When n_components is None, this parameter is ignored and components with zero eigenvalues are removed regardless. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. Used when ``eigen_solver`` == 'arpack'. + random_state : int, RandomState instance, default=None + Used when ``eigen_solver`` == 'arpack'. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. .. versionadded:: 0.18 diff --git a/sklearn/decomposition/_lda.py b/sklearn/decomposition/_lda.py index 8fcb51896d1..48b52df8117 100644 --- a/sklearn/decomposition/_lda.py +++ b/sklearn/decomposition/_lda.py @@ -222,11 +222,9 @@ class LatentDirichletAllocation(TransformerMixin, BaseEstimator): verbose : int, optional (default=0) Verbosity level. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Pass an int for reproducible results across multiple function calls. + See :term:`Glossary `. Attributes ---------- diff --git a/sklearn/decomposition/_nmf.py b/sklearn/decomposition/_nmf.py index 6d5509611ce..9458390c884 100644 --- a/sklearn/decomposition/_nmf.py +++ b/sklearn/decomposition/_nmf.py @@ -287,11 +287,10 @@ def _initialize_nmf(X, n_components, init=None, eps=1e-6, eps : float Truncate all values less then this in output to zero. - random_state : int, RandomState instance or None, optional, default: None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. Used when ``random`` == 'nndsvdar' or 'random'. + random_state : int, RandomState instance, default=None + Used when ``init`` == 'nndsvdar' or 'random'. Pass an int for + reproducible results across multiple function calls. + See :term:`Glossary `. Returns ------- @@ -472,11 +471,11 @@ def _fit_coordinate_descent(X, W, H, tol=1e-4, max_iter=200, l1_reg_W=0, shuffle : boolean, default: False If true, randomize the order of coordinates in the CD solver. - random_state : int, RandomState instance or None, optional, default: None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used to randomize the coordinates in the CD solver, when + ``shuffle`` is set to ``True``. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. Returns ------- @@ -963,11 +962,11 @@ def non_negative_factorization(X, W=None, H=None, n_components=None, Select whether the regularization affects the components (H), the transformation (W), both or none of them. - random_state : int, RandomState instance or None, optional, default: None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used for NMF initialisation (when ``init`` == 'nndsvdar' or + 'random'), and in Coordinate Descent. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. verbose : integer, default: 0 The verbosity level. @@ -1156,11 +1155,11 @@ class NMF(TransformerMixin, BaseEstimator): max_iter : integer, default: 200 Maximum number of iterations before timing out. - random_state : int, RandomState instance or None, optional, default: None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used for initialisation (when ``init`` == 'nndsvdar' or + 'random'), and in Coordinate Descent. Pass an int for reproducible + results across multiple function calls. + See :term:`Glossary `. alpha : double, default: 0. Constant that multiplies the regularization terms. Set it to zero to diff --git a/sklearn/decomposition/_pca.py b/sklearn/decomposition/_pca.py index e3fcf2dfcc6..faa083e099b 100644 --- a/sklearn/decomposition/_pca.py +++ b/sklearn/decomposition/_pca.py @@ -189,11 +189,10 @@ class PCA(_BasePCA): .. versionadded:: 0.18.0 - random_state : int, RandomState instance or None, optional (default None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. Used when ``svd_solver`` == 'arpack' or 'randomized'. + random_state : int, RandomState instance, default=None + Used when ``svd_solver`` == 'arpack' or 'randomized'. Pass an int + for reproducible results across multiple function calls. + See :term:`Glossary `. .. versionadded:: 0.18.0 diff --git a/sklearn/decomposition/_sparse_pca.py b/sklearn/decomposition/_sparse_pca.py index 3e31994d689..98aecc4a43d 100644 --- a/sklearn/decomposition/_sparse_pca.py +++ b/sklearn/decomposition/_sparse_pca.py @@ -79,11 +79,10 @@ class SparsePCA(TransformerMixin, BaseEstimator): verbose : int Controls the verbosity; the higher, the more messages. Defaults to 0. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used during dictionary learning. Pass an int for reproducible results + across multiple function calls. + See :term:`Glossary `. normalize_components : 'deprecated' This parameter does not have any effect. The components are always @@ -282,11 +281,11 @@ class MiniBatchSparsePCA(SparsePCA): Lasso solution (linear_model.Lasso). Lars will be faster if the estimated components are sparse. - random_state : int, RandomState instance or None, optional (default=None) - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used for random shuffling when ``shuffle`` is set to ``True``, + during online dictionary learning. Pass an int for reproducible results + across multiple function calls. + See :term:`Glossary `. normalize_components : 'deprecated' This parameter does not have any effect. The components are always diff --git a/sklearn/decomposition/_truncated_svd.py b/sklearn/decomposition/_truncated_svd.py index 73e4dfbe9f5..e3bddd23c4d 100644 --- a/sklearn/decomposition/_truncated_svd.py +++ b/sklearn/decomposition/_truncated_svd.py @@ -56,11 +56,10 @@ class TruncatedSVD(TransformerMixin, BaseEstimator): `~sklearn.utils.extmath.randomized_svd` to handle sparse matrices that may have large slowly decaying spectrum. - random_state : int, RandomState instance or None, optional, default = None - If int, random_state is the seed used by the random number generator; - If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by `np.random`. + random_state : int, RandomState instance, default=None + Used during randomized svd. Pass an int for reproducible results across + multiple function calls. + See :term:`Glossary `. tol : float, optional Tolerance for ARPACK. 0 means machine precision. Ignored by randomized