DOC add a more complex example to gridsearch for nested parameters (#14548)

* add a more complex example to gridsearch for nested parameters

* slight formatting fixes

* normalize whitespace doesn't do what I thought it does

* more whitespace yay

* Update doc/modules/compose.rst

Co-Authored-By: Thomas J Fan <thomasjpfan@gmail.com>

* Update doc/modules/grid_search.rst

Co-Authored-By: Joel Nothman <joel.nothman@gmail.com>

* reformulate according to Joel's suggestions

* typo

* ellipsis

* Update doc/modules/grid_search.rst

Co-Authored-By: Nicolas Hug <contact@nicolas-hug.com>

* Update doc/modules/grid_search.rst

Co-Authored-By: Nicolas Hug <contact@nicolas-hug.com>

* change the link to point to api docs for pipeline

* one more explicit use of pipeline module for linking to the API docs

* Update doc/modules/grid_search.rst

Co-Authored-By: Joel Nothman <joel.nothman@gmail.com>

Author: 2 people

doc/modules/compose.rst

@@ -101,6 +101,9 @@ permitted). This is convenient for performing only some of the transformations
     >>> pipe[-1:]
     Pipeline(steps=[('clf', SVC())])
 
+
+.. _pipeline_nested_parameters:
+
 Nested parameters
 .................
 
@@ -128,7 +131,7 @@ ignored by setting them to ``'passthrough'``::
 
 The estimators of the pipeline can be retrieved by index:
 
-    >>> pipe[0] 
+    >>> pipe[0]
     PCA()
 
 or by name::
@@ -147,7 +150,7 @@ or by name::
 
 .. topic:: See also:
 
- * :ref:`grid_search`
+ * :ref:`composite_grid_search`
 
 
 Notes
@@ -369,7 +372,7 @@ Like ``Pipeline``, individual steps may be replaced using ``set_params``,
 and ignored by setting to ``'drop'``::
 
     >>> combined.set_params(kernel_pca='drop')
-    FeatureUnion(transformer_list=[('linear_pca', PCA()), 
+    FeatureUnion(transformer_list=[('linear_pca', PCA()),
                                    ('kernel_pca', 'drop')])
 
 .. topic:: Examples:
@@ -420,7 +423,7 @@ preprocessing or a specific feature extraction method::
 
 For this data, we might want to encode the ``'city'`` column as a categorical
 variable using :class:`preprocessing.OneHotEncoder
-<sklearn.preprocessing.OneHotEncoder>` but apply a 
+<sklearn.preprocessing.OneHotEncoder>` but apply a
 :class:`feature_extraction.text.CountVectorizer
 <sklearn.feature_extraction.text.CountVectorizer>` to the ``'title'`` column.
 As we might use multiple feature extraction methods on the same column, we give

doc/modules/grid_search.rst

@@ -43,7 +43,7 @@ Note that it is common that a small subset of those parameters can have a large
 impact on the predictive or computation performance of the model while others
 can be left to their default values. It is recommended to read the docstring of
 the estimator class to get a finer understanding of their expected behavior,
-possibly by reading the enclosed reference to the literature.  
+possibly by reading the enclosed reference to the literature.
 
 Exhaustive Grid Search
 ======================
@@ -192,11 +192,47 @@ result in an error when using multiple metrics.
 See :ref:`sphx_glr_auto_examples_model_selection_plot_multi_metric_evaluation.py`
 for an example usage.
 
+.. _composite_grid_search:
+
 Composite estimators and parameter spaces
 -----------------------------------------
+`GridSearchCV` and `RandomizedSearchCV` allow searching over parameters of
+composite or nested estimators such as `pipeline.Pipeline`,
+`ColumnTransformer`, `VotingClassifier` or `CalibratedClassifierCV`
+using a dedicated ``<estimator>__<parameter>`` syntax::
+
+  >>> from sklearn.model_selection import GridSearchCV
+  >>> from sklearn.calibration import CalibratedClassifierCV
+  >>> from sklearn.ensemble import RandomForestClassifier
+  >>> from sklearn.datasets import make_moons
+  >>> X, y = make_moons()
+  >>> calibrated_forest = CalibratedClassifierCV(
+  ...    base_estimator=RandomForestClassifier(n_estimators=10))
+  >>> param_grid = {
+  ...    'base_estimator__max_depth': [2, 4, 6, 8]}
+  >>> search = GridSearchCV(calibrated_forest, param_grid, cv=5)
+  >>> search.fit(X, y)
+  GridSearchCV(cv=5,
+               estimator=CalibratedClassifierCV(...),
+               param_grid={'base_estimator__max_depth': [2, 4, 6, 8]})
+
+Here, ``<estimator>`` is the parameter name of the nested estimator,
+in this case ``base_estimator``.
+If the meta-estimator is constructed as a collection of estimators as in
+`pipeline.Pipeline`, then ``<estimator>`` refers to the name of the estimator,
+see :ref:`pipeline_nested_parameters`.  In practice, there can be several
+levels of nesting::
+
+  >>> from sklearn.pipeline import Pipeline
+  >>> from sklearn.feature_selection import SelectKBest
+  >>> pipe = Pipeline([
+  ...    ('select', SelectKBest()),
+  ...    ('model', calibrated_forest)])
+  >>> param_grid = {
+  ...    'select__k': [1, 2],
+  ...    'model__base_estimator__max_depth': [2, 4, 6, 8]}
+  >>> search = GridSearchCV(pipe, param_grid, cv=5).fit(X, y)
 
-:ref:`pipeline` describes building composite estimators whose
-parameter space can be searched with these tools.
 
 Model selection: development and evaluation
 -------------------------------------------