Repository: scikit-learn/scikit-learn
Pull request: DOC add example docstring for make_low_rank_matrix
closes #27982

This the remaining docstring that needs to be addressed in #27982.
We can close the issue then.

Problem statement:
Ensure that we have an example in the docstring of each public function or class
We should make sure that we have a small example for all public functions or classes. Most of the missing examples are linked to functions.

I could list the following classes and functions for which `numpydoc` did not find any example:

- [x] sklearn.base.BaseEstimator
- [x] sklearn.base.BiclusterMixin
- [x] sklearn.base.ClassNamePrefixFeaturesOutMixin
- [x] sklearn.base.ClassifierMixin
- [x] sklearn.base.ClusterMixin
- [x] sklearn.base.DensityMixin
- [x] sklearn.base.MetaEstimatorMixin
- [x] sklearn.base.OneToOneFeatureMixin
- [x] sklearn.base.OutlierMixin
- [x] sklearn.base.RegressorMixin
- [x] sklearn.base.TransformerMixin
- [x] sklearn.base.clone
- [x] sklearn.base.is_classifier
- [x] sklearn.base.is_regressor
- [x] sklearn.cluster.affinity_propagation
- [x] sklearn.cluster.cluster_optics_dbscan
- [x] sklearn.cluster.cluster_optics_xi
- [x] sklearn.cluster.compute_optics_graph
- [x] sklearn.cluster.estimate_bandwidth
- [x] sklearn.cluster.k_means
- [x] sklearn.cluster.mean_shift
- [x] sklearn.cluster.spectral_clustering
- [x] sklearn.cluster.ward_tree
- [x] sklearn.covariance.graphical_lasso
- [x] sklearn.covariance.ledoit_wolf
- [x] sklearn.covariance.ledoit_wolf_shrinkage
- [x] sklearn.covariance.shrunk_covariance
- [x] sklearn.datasets.clear_data_home
- [x] sklearn.datasets.dump_svmlight_file
- [x] sklearn.datasets.fetch_20newsgroups
- [x] sklearn.datasets.fetch_20newsgroups_vectorized
- [x] sklearn.datasets.fetch_california_housing
- [x] sklearn.datasets.fetch_covtype
- [x] sklearn.datasets.fetch_kddcup99
- [x] sklearn.datasets.fetch_lfw_pairs
- [x] sklearn.datasets.fetch_lfw_people
- [x] sklearn.datasets.fetch_olivetti_faces
- [x] sklearn.datasets.fetch_openml
- [x] sklearn.datasets.fetch_rcv1
- [x] sklearn.datasets.fetch_species_distributions
- [x] sklearn.datasets.get_data_home
- [x] sklearn.datasets.load_diabetes
- [x] sklearn.datasets.load_files
- [x] sklearn.datasets.load_linnerud
- [x] sklearn.datasets.load_svmlight_files
- [x] sklearn.datasets.make_biclusters
- [x] sklearn.datasets.make_checkerboard
- [x] sklearn.datasets.make_circles
- [x] sklearn.datasets.make_classification
- [x] sklearn.datasets.make_friedman1
- [x] sklearn.datasets.make_friedman2
- [x] sklearn.datasets.make_friedman3
- [x] sklearn.datasets.make_gaussian_quantiles
- [x] sklearn.datasets.make_hastie_10_2
- [x] sklearn.datasets.make_low_rank_matrix
- [x] sklearn.datasets.make_moons
- [x] sklearn.datasets.make_multilabel_classification
- [x] sklearn.datasets.make_s_curve
- [x] sklearn.datasets.make_sparse_coded_signal
- [x] sklearn.datasets.make_sparse_spd_matrix
- [x] sklearn.datasets.make_sparse_uncorrelated
- [x] sklearn.datasets.make_spd_matrix
- [x] sklearn.datasets.make_swiss_roll
- [x] sklearn.decomposition.dict_learning
- [x] sklearn.decomposition.dict_learning_online
- [x] sklearn.decomposition.sparse_encode
- [x] sklearn.feature_extraction.image.grid_to_graph
- [x] sklearn.feature_extraction.image.img_to_graph
- [x] sklearn.feature_extraction.image.reconstruct_from_patches_2d
- [x] sklearn.feature_selection.SelectorMixin
- [x] sklearn.feature_selection.chi2
- [x] sklearn.feature_selection.f_classif
- [x] sklearn.feature_selection.f_regression
- [x] sklearn.feature_selection.mutual_info_classif
- [x] sklearn.feature_selection.mutual_info_regression
- [x] sklearn.feature_selection.r_regression
- [x] sklearn.gaussian_process.kernels.Kernel
- [x] sklearn.get_config
- [x] sklearn.isotonic.check_increasing
- [x] sklearn.isotonic.isotonic_regression
- [x] sklearn.linear_model.enet_path
- [x] sklearn.linear_model.lars_path
- [x] sklearn.linear_model.lars_path_gram
- [x] sklearn.linear_model.orthogonal_mp
- [x] sklearn.linear_model.orthogonal_mp_gram
- [x] sklearn.linear_model.ridge_regression
- [x] sklearn.manifold.locally_linear_embedding
- [x] sklearn.manifold.smacof
- [x] sklearn.manifold.spectral_embedding
- [x] sklearn.manifold.trustworthiness
- [x] sklearn.metrics.calinski_harabasz_score
- [x] sklearn.metrics.check_scoring
- [x] sklearn.metrics.cohen_kappa_score
- [x] sklearn.metrics.consensus_score
- [x] sklearn.metrics.coverage_error
- [x] sklearn.metrics.davies_bouldin_score
- [x] sklearn.metrics.get_scorer
- [x] sklearn.metrics.get_scorer_names
- [x] sklearn.metrics.homogeneity_completeness_v_measure
- [x] sklearn.metrics.label_ranking_loss
- [x] sklearn.metrics.mutual_info_score
- [x] sklearn.metrics.pairwise.additive_chi2_kernel
- [x] sklearn.metrics.pairwise.chi2_kernel
- [x] sklearn.metrics.pairwise.cosine_distances
- [x] sklearn.metrics.pairwise.cosine_similarity
- [x] sklearn.metrics.pairwise.distance_metrics
- [x] sklearn.metrics.pairwise.kernel_metrics
- [x] sklearn.metrics.pairwise.laplacian_kernel
- [x] sklearn.metrics.pairwise.linear_kernel
- [x] sklearn.metrics.pairwise.paired_cosine_distances
- [x] sklearn.metrics.pairwise.paired_euclidean_distances
- [x] sklearn.metrics.pairwise.pairwise_kernels
- [x] sklearn.metrics.pairwise.polynomial_kernel
- [x] sklearn.metrics.pairwise.rbf_kernel
- [x] sklearn.metrics.pairwise.sigmoid_kernel
- [x] sklearn.metrics.pairwise_distances
- [x] sklearn.metrics.pairwise_distances_argmin
- [x] sklearn.metrics.pairwise_distances_argmin_min
- [x] sklearn.metrics.silhouette_samples
- [x] sklearn.metrics.silhouette_score
- [x] sklearn.model_selection.check_cv
- [x] sklearn.model_selection.permutation_test_score
- [x] sklearn.model_selection.validation_curve
- [x] sklearn.neighbors.sort_graph_by_row_values
- [x] sklearn.preprocessing.binarize
- [x] sklearn.preprocessing.maxabs_scale
- [x] sklearn.preprocessing.minmax_scale
- [x] sklearn.preprocessing.normalize
- [x] sklearn.preprocessing.robust_scale
- [x] sklearn.preprocessing.scale
- [x] sklearn.set_config
- [x] sklearn.show_versions
- [x] sklearn.svm.l1_min_c
- [x] sklearn.utils._safe_indexing
- [x] sklearn.utils.arrayfuncs.min_pos
- [x] sklearn.utils.as_float_array
- [x] sklearn.utils.assert_all_finite
- [x] sklearn.utils.check_X_y
- [x] sklearn.utils.check_array
- [x] sklearn.utils.check_consistent_length
- [x] sklearn.utils.check_random_state
- [x] sklearn.utils.check_scalar
- [x] sklearn.utils.class_weight.compute_class_weight
- [x] sklearn.utils.class_weight.compute_sample_weight
- [x] sklearn.utils.deprecated
- [x] sklearn.utils.discovery.all_displays
- [x] sklearn.utils.discovery.all_estimators
- [x] sklearn.utils.discovery.all_functions
- [x] sklearn.utils.estimator_checks.check_estimator
- [x] sklearn.utils.estimator_html_repr
- [x] sklearn.utils.extmath.density
- [x] sklearn.utils.extmath.randomized_range_finder
- [x] sklearn.utils.extmath.safe_sparse_dot
- [x] sklearn.utils.indexable
- [x] sklearn.utils.metadata_routing.MetadataRequest
- [x] sklearn.utils.metadata_routing.MetadataRouter
- [x] sklearn.utils.metadata_routing.MethodMapping
- [x] sklearn.utils.metadata_routing.get_routing_for_object
- [x] sklearn.utils.metadata_routing.process_routing
- [x] sklearn.utils.murmurhash3_32
- [x] sklearn.utils.parallel.Parallel
- [x] sklearn.utils.parallel.delayed
- [x] sklearn.utils.parallel_backend
- [x] sklearn.utils.random.sample_without_replacement
- [x] sklearn.utils.register_parallel_backend
- [x] sklearn.utils.safe_mask
- [x] sklearn.utils.safe_sqr
- [x] sklearn.utils.sparsefuncs.incr_mean_variance_axis
- [x] sklearn.utils.sparsefuncs.inplace_column_scale
- [x] sklearn.utils.sparsefuncs.inplace_csr_column_scale
- [x] sklearn.utils.sparsefuncs.inplace_row_scale
- [x] sklearn.utils.sparsefuncs.inplace_swap_column
- [x] sklearn.utils.sparsefuncs.inplace_swap_row
- [x] sklearn.utils.sparsefuncs.mean_variance_axis
- [x] sklearn.utils.sparsefuncs_fast.inplace_csr_row_normalize_l1
- [x] sklearn.utils.sparsefuncs_fast.inplace_csr_row_normalize_l2
- [x] sklearn.utils.validation.check_is_fitted
- [x] sklearn.utils.validation.check_memory
- [x] sklearn.utils.validation.check_symmetric
- [x] sklearn.utils.validation.column_or_1d

The code used to find the list above is detailed below:

<details>

```python
import importlib
import inspect
from pathlib import Path

from numpydoc.docscrape import NumpyDocString

path_sklearn_doc = Path(
    "/{path_to_git_repo}/scikit-learn/doc/_build/html/stable/"
    "modules/generated"
)

missing_examples_name = []
for document in path_sklearn_doc.glob("*.html"):
    extracted_doc = []
    full_name = document.stem
    try:
        module_name, class_or_function_name = full_name.rsplit(".", maxsplit=1)
        module = importlib.import_module(module_name)
        class_or_function = getattr(module, class_or_function_name)
    except (ValueError, AttributeError, ImportError):
        # This is due to the experimental module and function with
        # module name
        continue
    is_class = inspect.isclass(class_or_function)
    docstring = NumpyDocString(class_or_function.__doc__)
    if not docstring["Examples"]:
        missing_examples_name.append(full_name)

for full_name in sorted(missing_examples_name):
    print(f"- [ ] {full_name}")
```

</details>

Hints from issue discussion:
I am new to GitHub, and I want to work on this!
Hi @AdarshWase, to start working on this, you can fork the scikit-learn repository, clone it to your local machine, make your changes, and then send a pull request. The pull request should mention this issue (#27982).

I've already send a PR for the clustering functions, so you should work on some other functions.

Hope this helped. Lmk if you have any other questions :)
Hi @raj-pulapakura 

I added docstring examples of all metric.pairwise functions (except `sklearn.metrics.pairwise.distance_metrics` and `sklearn.metrics.pairwise.kernel_metrics`) and created a pull request. There are some errors in my pull request. I am not sure how to fix them. 
Hi @AdarshWase. I've given some of my insight in the PR convo.
Hi, I would like to take up documentation examples for functions from `sklearn.datasets`.

Will fork the repo, make changes and send a PR.
Assuming no one has started working on the feature_selection functions., I'll get started on those 👍.
I will get started on `sklearn.utils.sparsefuncs`
I would like to work on one of the functions, am new here; I need someone to guide
I  will get started on sklearn.gaussian_process.kernels.Kernel
I'll work on 

 sklearn.utils.parallel.Parallel
sklearn.utils.parallel.delayed

Commit message: DOC add example docstring for make_low_rank_matrix

Patch to review:
diff --git a/sklearn/datasets/_samples_generator.py b/sklearn/datasets/_samples_generator.py
index 9d689da99fa45..527c87641403d 100644
--- a/sklearn/datasets/_samples_generator.py
+++ b/sklearn/datasets/_samples_generator.py
@@ -1411,6 +1411,22 @@ def make_low_rank_matrix(
     -------
     X : ndarray of shape (n_samples, n_features)
         The matrix.
+
+    Examples
+    --------
+    >>> from numpy.linalg import svd
+    >>> from sklearn.datasets import make_low_rank_matrix
+    >>> X = make_low_rank_matrix(n_samples=50,
+    ...     n_features=25,
+    ...     effective_rank=5,
+    ...     tail_strength=0.01,
+    ...     random_state=0,
+    ... )
+    >>> X.shape
+    (50, 25)
+    >>> U, s, V = svd(X)
+    >>> s.sum()
+    5...
     """
     generator = check_random_state(random_state)
     n = min(n_samples, n_features)


Code review comments:
diff_hunk: @@ -1411,6 +1411,22 @@ def make_low_rank_matrix(
     -------
     X : ndarray of shape (n_samples, n_features)
         The matrix.
+
+    Examples
+    --------
+    >>> from numpy.linalg import svd
+    >>> from sklearn.datasets import make_low_rank_matrix
+    >>> X = make_low_rank_matrix(n_samples=50,
+    ...     n_features=25,
+    ...     effective_rank=5,
+    ...     tail_strength=0.01,
+    ...     random_state=0,
+    ... )
+    >>> X.shape
+    (50, 25)
+    >>> U, s, V = svd(X)
+    >>> s.sum()
+    5...
path: sklearn/datasets/_samples_generator.py
text: @user1:
I don't think that this is a valid confirmation of the effective rank. The rank is not the sum of the singular values but the number of non-zero singular values. Suppose X has rank 5, then 10*X has also rank 5 but the sum of its singular values is 10 times bigger.

@author:
Good point. Our test is therefore quite bad 😁

@author:
Apparently the profile is not the one that we expect. The singular value should follow a exponential decay controlled by the effective rank parameter. So we should probably avoid this last line.