API Deprecates plot_partial_dependence (#20959)

thomasjpfan · adrinjalali · commit af5328fe327e · 2021-09-14T13:28:03.000+02:00
* API Deprecates plot_partial_dependence

* DOC Adds whats new

* DOC Fixes doc build errors

* CLN Removes feature warning

* CLN Address comments

* DOC Fix docstrings

* TST Skip future warning tests

* DOC Adjust docstrings

* REV Reduce diff

* DOC Adds docstring
diff --git a/doc/developers/plotting.rst b/doc/developers/plotting.rst
@@ -64,8 +64,8 @@ Plotting with Multiple Axes
 ---------------------------
 
 Some of the plotting tools like
-:func:`~sklearn.inspection.plot_partial_dependence` and
-:class:`~sklearn.inspection.PartialDependenceDisplay` support plottong on
+:func:`~sklearn.inspection.PartialDependenceDisplay.from_estimator` and
+:class:`~sklearn.inspection.PartialDependenceDisplay` support plotting on
 multiple axes. Two different scenarios are supported:
 
 1. If a list of axes is passed in, `plot` will check if the number of axes is
@@ -87,8 +87,8 @@ be placed. In this case, we suggest using matplotlib's
 By default, the `ax` keyword in `plot` is `None`. In this case, the single
 axes is created and the gridspec api is used to create the regions to plot in.
 
-See for example, :func:`~sklearn.inspection.plot_partial_dependence` which
-plots multiple lines and contours using this API. The axes defining the
+See for example, :func:`~sklearn.inspection.PartialDependenceDisplay.from_estimator
+which plots multiple lines and contours using this API. The axes defining the
 bounding box is saved in a `bounding_ax_` attribute. The individual axes
 created are stored in an `axes_` ndarray, corresponding to the axes position on
 the grid. Positions that are not used are set to `None`. Furthermore, the
diff --git a/doc/modules/partial_dependence.rst b/doc/modules/partial_dependence.rst
@@ -55,20 +55,20 @@ independent of the house age, whereas for values less than 2 there is a strong
 dependence on age.
 
 The :mod:`sklearn.inspection` module provides a convenience function
-:func:`plot_partial_dependence` to create one-way and two-way partial
+:func:`~PartialDependenceDisplay.from_estimator` to create one-way and two-way partial
 dependence plots. In the below example we show how to create a grid of
 partial dependence plots: two one-way PDPs for the features ``0`` and ``1``
 and a two-way PDP between the two features::
 
     >>> from sklearn.datasets import make_hastie_10_2
     >>> from sklearn.ensemble import GradientBoostingClassifier
-    >>> from sklearn.inspection import plot_partial_dependence
+    >>> from sklearn.inspection import PartialDependenceDisplay
 
     >>> X, y = make_hastie_10_2(random_state=0)
     >>> clf = GradientBoostingClassifier(n_estimators=100, learning_rate=1.0,
     ...     max_depth=1, random_state=0).fit(X, y)
     >>> features = [0, 1, (0, 1)]
-    >>> plot_partial_dependence(clf, X, features)
+    >>> PartialDependenceDisplay.from_estimator(clf, X, features)
     <...>
 
 You can access the newly created figure and Axes objects using ``plt.gcf()``
@@ -82,7 +82,7 @@ the PDPs should be created via the ``target`` argument::
     >>> mc_clf = GradientBoostingClassifier(n_estimators=10,
     ...     max_depth=1).fit(iris.data, iris.target)
     >>> features = [3, 2, (3, 2)]
-    >>> plot_partial_dependence(mc_clf, X, features, target=0)
+    >>> PartialDependenceDisplay.from_estimator(mc_clf, X, features, target=0)
     <...>
 
 The same parameter ``target`` is used to specify the target in multi-output
@@ -138,20 +138,20 @@ and the house price in the PD line. However, the ICE lines show that there
 are some exceptions, where the house price remains constant in some ranges of
 the median income.
 
-The :mod:`sklearn.inspection` module's :func:`plot_partial_dependence`
+The :mod:`sklearn.inspection` module's :meth:`PartialDependenceDisplay.from_estimator`
 convenience function can be used to create ICE plots by setting
 ``kind='individual'``. In the example below, we show how to create a grid of
 ICE plots:
 
     >>> from sklearn.datasets import make_hastie_10_2
     >>> from sklearn.ensemble import GradientBoostingClassifier
-    >>> from sklearn.inspection import plot_partial_dependence
+    >>> from sklearn.inspection import PartialDependenceDisplay
 
     >>> X, y = make_hastie_10_2(random_state=0)
     >>> clf = GradientBoostingClassifier(n_estimators=100, learning_rate=1.0,
     ...     max_depth=1, random_state=0).fit(X, y)
     >>> features = [0, 1]
-    >>> plot_partial_dependence(clf, X, features,
+    >>> PartialDependenceDisplay.from_estimator(clf, X, features,
     ...     kind='individual')
     <...>
 
@@ -160,7 +160,7 @@ feature of interest. Hence, it is recommended to use ICE plots alongside
 PDPs. They can be plotted together with
 ``kind='both'``.
 
-    >>> plot_partial_dependence(clf, X, features,
+    >>> PartialDependenceDisplay.from_estimator(clf, X, features,
     ...     kind='both')
     <...>
 
diff --git a/doc/whats_new/v1.0.rst b/doc/whats_new/v1.0.rst
@@ -461,6 +461,11 @@ Changelog
   :func:`~sklearn.inspection.permutation_importance`.
   :pr:`19411` by :user:`Simona Maggio <simonamaggio>`.
 
+- |API| :class:`inspection.PartialDependenceDisplay` exposes a class method:
+  :func:`~inspection.PartialDependenceDisplay.from_estimator`.
+  :func:`inspection.plot_partial_dependence` is deprecated in favor of the
+  class method and will be removed in 1.2. :pr:`20959` by `Thomas Fan`_.
+
 :mod:`sklearn.kernel_approximation`
 ...................................
 
diff --git a/examples/ensemble/plot_monotonic_constraints.py b/examples/ensemble/plot_monotonic_constraints.py
@@ -19,7 +19,7 @@
 <https://xgboost.readthedocs.io/en/latest/tutorials/monotonic.html>`_.
 """
 from sklearn.ensemble import HistGradientBoostingRegressor
-from sklearn.inspection import plot_partial_dependence
+from sklearn.inspection import PartialDependenceDisplay
 import numpy as np
 import matplotlib.pyplot as plt
 
@@ -43,7 +43,7 @@
 # Without any constraint
 gbdt = HistGradientBoostingRegressor()
 gbdt.fit(X, y)
-disp = plot_partial_dependence(
+disp = PartialDependenceDisplay.from_estimator(
     gbdt,
     X,
     features=[0, 1],
@@ -55,7 +55,7 @@
 gbdt = HistGradientBoostingRegressor(monotonic_cst=[1, -1])
 gbdt.fit(X, y)
 
-plot_partial_dependence(
+PartialDependenceDisplay.from_estimator(
     gbdt,
     X,
     features=[0, 1],
diff --git a/examples/inspection/plot_partial_dependence.py b/examples/inspection/plot_partial_dependence.py
@@ -111,12 +111,12 @@
 
 import matplotlib.pyplot as plt
 from sklearn.inspection import partial_dependence
-from sklearn.inspection import plot_partial_dependence
+from sklearn.inspection import PartialDependenceDisplay
 
 print("Computing partial dependence plots...")
 tic = time()
 features = ["MedInc", "AveOccup", "HouseAge", "AveRooms"]
-display = plot_partial_dependence(
+display = PartialDependenceDisplay.from_estimator(
     est,
     X_train,
     features,
@@ -166,7 +166,7 @@
 
 print("Computing partial dependence plots...")
 tic = time()
-display = plot_partial_dependence(
+display = PartialDependenceDisplay.from_estimator(
     est,
     X_train,
     features,
@@ -229,7 +229,7 @@
 print("Computing partial dependence plots...")
 tic = time()
 _, ax = plt.subplots(ncols=3, figsize=(9, 4))
-display = plot_partial_dependence(
+display = PartialDependenceDisplay.from_estimator(
     est,
     X_train,
     features,
diff --git a/examples/miscellaneous/plot_partial_dependence_visualization_api.py b/examples/miscellaneous/plot_partial_dependence_visualization_api.py
@@ -22,7 +22,7 @@
 from sklearn.preprocessing import StandardScaler
 from sklearn.pipeline import make_pipeline
 from sklearn.tree import DecisionTreeRegressor
-from sklearn.inspection import plot_partial_dependence
+from sklearn.inspection import PartialDependenceDisplay
 
 
 # %%
@@ -49,22 +49,22 @@
 #
 # We plot partial dependence curves for features "age" and "bmi" (body mass
 # index) for the decision tree. With two features,
-# :func:`~sklearn.inspection.plot_partial_dependence` expects to plot two
-# curves. Here the plot function place a grid of two plots using the space
+# :func:`~sklearn.inspection.PartialDependenceDisplay.from_estimator` expects to plot
+# two curves. Here the plot function place a grid of two plots using the space
 # defined by `ax` .
 fig, ax = plt.subplots(figsize=(12, 6))
 ax.set_title("Decision Tree")
-tree_disp = plot_partial_dependence(tree, X, ["age", "bmi"], ax=ax)
+tree_disp = PartialDependenceDisplay.from_estimator(tree, X, ["age", "bmi"], ax=ax)
 
 # %%
 # The partial depdendence curves can be plotted for the multi-layer perceptron.
 # In this case, `line_kw` is passed to
-# :func:`~sklearn.inspection.plot_partial_dependence` to change the color of
-# the curve.
+# :func:`~sklearn.inspection.PartialDependenceDisplay.from_estimator` to change the
+# color of the curve.
 fig, ax = plt.subplots(figsize=(12, 6))
 ax.set_title("Multi-layer Perceptron")
-mlp_disp = plot_partial_dependence(mlp, X, ["age", "bmi"], ax=ax,
-                                   line_kw={"color": "red"})
+mlp_disp = PartialDependenceDisplay.from_estimator(mlp, X, ["age", "bmi"], ax=ax,
+                                                   line_kw={"color": "red"})
 
 # %%
 # Plotting partial dependence of the two models together
@@ -129,7 +129,6 @@
 # Here, we plot the partial dependence curves for a single feature, "age", on
 # the same axes. In this case, `tree_disp.axes_` is passed into the second
 # plot function.
-tree_disp = plot_partial_dependence(tree, X, ["age"])
-mlp_disp = plot_partial_dependence(mlp, X, ["age"],
-                                   ax=tree_disp.axes_,
-                                   line_kw={"color": "red"})
+tree_disp = PartialDependenceDisplay.from_estimator(tree, X, ["age"])
+mlp_disp = PartialDependenceDisplay.from_estimator(
+    mlp, X, ["age"], ax=tree_disp.axes_, line_kw={"color": "red"})
diff --git a/sklearn/inspection/_partial_dependence.py b/sklearn/inspection/_partial_dependence.py
@@ -370,7 +370,7 @@ def partial_dependence(
 
     See Also
     --------
-    plot_partial_dependence : Plot Partial Dependence.
+    PartialDependenceDisplay.from_estimator : Plot Partial Dependence.
     PartialDependenceDisplay : Partial Dependence visualization.
 
     Examples
diff --git a/sklearn/inspection/_plot/partial_dependence.py b/sklearn/inspection/_plot/partial_dependence.py
diff --git a/sklearn/inspection/_plot/tests/test_plot_partial_dependence.py b/sklearn/inspection/_plot/tests/test_plot_partial_dependence.py
diff --git a/sklearn/utils/__init__.py b/sklearn/utils/__init__.py
