MNT Rename DetCurveDisplay parameters estimator_name and **kwargs (scikit-learn#34443)

Co-authored-by: Olivier Grisel <olivier.grisel@ensta.org>

Author: AnneBeyer

doc/whats_new/upcoming_changes/sklearn.metrics/34443.api.rst

@@ -0,0 +1,6 @@
+- In :class:`metrics.DetCurveDisplay` the `estimator_name` parameter is deprecated in
+  favour of `name` and will be removed in 1.12. The `**kwargs` parameter of
+  :meth:`metrics.DetCurveDisplay.plot`, :meth:`metrics.DetCurveDisplay.from_estimator`
+  and :meth:`metrics.DetCurveDisplay.from_predictions` is also deprecated in favour of
+  `curve_kwargs` and will be removed in 1.12.
+  By :user:`AnneBeyer`.

examples/model_selection/plot_det.py

@@ -98,8 +98,10 @@
 ax_det.grid(linestyle="--")
 
 for name, clf in classifiers.items():
-    (color, linestyle) = (
-        ("black", "--") if name == "Non-informative baseline" else (None, None)
+    curve_kwargs = (
+        dict(color="black", linestyle="--")
+        if name == "Non-informative baseline"
+        else None
     )
     clf.fit(X_train, y_train)
     RocCurveDisplay.from_estimator(
@@ -108,10 +110,15 @@
         y_test,
         ax=ax_roc,
         name=name,
-        curve_kwargs=dict(color=color, linestyle=linestyle),
+        curve_kwargs=curve_kwargs,
     )
     DetCurveDisplay.from_estimator(
-        clf, X_test, y_test, ax=ax_det, name=name, color=color, linestyle=linestyle
+        clf,
+        X_test,
+        y_test,
+        ax=ax_det,
+        name=name,
+        curve_kwargs=curve_kwargs,
     )
 
 plt.legend()

sklearn/metrics/_plot/det_curve.py

@@ -7,6 +7,7 @@
 from sklearn.metrics._ranking import det_curve
 from sklearn.utils._plotting import (
     _BinaryClassifierCurveDisplayMixin,
+    _deprecate_estimator_name,
     _deprecate_y_pred_parameter,
 )
 
@@ -33,13 +34,23 @@ class DetCurveDisplay(_BinaryClassifierCurveDisplayMixin):
     fnr : ndarray
         False negative rate.
 
-    estimator_name : str, default=None
-        Name of estimator. If None, the estimator name is not shown.
+    name : str, default=None
+        Name for labeling the legend entry. If None, the estimator name is not shown.
+
+        .. versionchanged:: 1.10
+            `estimator_name` was deprecated in favor of `name`.
 
     pos_label : int, float, bool or str, default=None
         The label of the positive class. If not `None`, this value is displayed in
         the x- and y-axes labels.
 
+    estimator_name : str, default=None
+        Name of estimator. If None, the estimator name is not shown.
+
+        .. deprecated:: 1.10
+            `estimator_name` is deprecated and will be removed in 1.12. Use `name`
+            instead.
+
     Attributes
     ----------
     line_ : matplotlib Artist
@@ -73,17 +84,19 @@ class DetCurveDisplay(_BinaryClassifierCurveDisplayMixin):
     >>> y_score = clf.decision_function(X_test)
     >>> fpr, fnr, _ = det_curve(y_test, y_score)
     >>> display = DetCurveDisplay(
-    ...     fpr=fpr, fnr=fnr, estimator_name="SVC"
+    ...     fpr=fpr, fnr=fnr, name="SVC"
     ... )
     >>> display.plot()
     <...>
     >>> plt.show()
     """
 
-    def __init__(self, *, fpr, fnr, estimator_name=None, pos_label=None):
+    def __init__(
+        self, *, fpr, fnr, name=None, pos_label=None, estimator_name="deprecated"
+    ):
         self.fpr = fpr
         self.fnr = fnr
-        self.estimator_name = estimator_name
+        self.name = _deprecate_estimator_name(estimator_name, name, "1.10")
         self.pos_label = pos_label
 
     @classmethod
@@ -99,6 +112,7 @@ def from_estimator(
         pos_label=None,
         name=None,
         ax=None,
+        curve_kwargs=None,
         **kwargs,
     ):
         """Plot DET curve given an estimator and data.
@@ -151,9 +165,18 @@ def from_estimator(
             Axes object to plot on. If `None`, a new figure and axes is
             created.
 
+        curve_kwargs : dict, default=None
+            Keywords arguments to be passed to matplotlib's `plot` function.
+
+            .. versionadded:: 1.10
+
         **kwargs : dict
             Additional keywords arguments passed to matplotlib `plot` function.
 
+            .. deprecated:: 1.10
+                `**kwargs` is deprecated and will be removed in 1.12. Pass matplotlib
+                arguments to `curve_kwargs` as a dictionary instead.
+
         Returns
         -------
         display : :class:`~sklearn.metrics.DetCurveDisplay`
@@ -197,6 +220,7 @@ def from_estimator(
             drop_intermediate=drop_intermediate,
             name=name,
             ax=ax,
+            curve_kwargs=curve_kwargs,
             pos_label=pos_label,
             **kwargs,
         )
@@ -212,6 +236,7 @@ def from_predictions(
         pos_label=None,
         name=None,
         ax=None,
+        curve_kwargs=None,
         y_pred="deprecated",
         **kwargs,
     ):
@@ -260,6 +285,11 @@ class or non-thresholded decision values (as returned by
             Axes object to plot on. If `None`, a new figure and axes is
             created.
 
+        curve_kwargs : dict, default=None
+            Keywords arguments to be passed to matplotlib's `plot` function.
+
+            .. versionadded:: 1.10
+
         y_pred : array-like of shape (n_samples,)
             Target scores, can either be probability estimates of the positive
             class or non-thresholded decision values (as returned by
@@ -272,6 +302,10 @@ class or non-thresholded decision values (as returned by
         **kwargs : dict
             Additional keywords arguments passed to matplotlib `plot` function.
 
+            .. deprecated:: 1.10
+                `**kwargs` is deprecated and will be removed in 1.12. Pass matplotlib
+                arguments to `curve_kwargs` as a dictionary instead.
+
         Returns
         -------
         display : :class:`~sklearn.metrics.DetCurveDisplay`
@@ -316,13 +350,13 @@ class or non-thresholded decision values (as returned by
         viz = cls(
             fpr=fpr,
             fnr=fnr,
-            estimator_name=name,
+            name=name,
             pos_label=pos_label_validated,
         )
 
-        return viz.plot(ax=ax, name=name, **kwargs)
+        return viz.plot(ax=ax, name=name, curve_kwargs=curve_kwargs, **kwargs)
 
-    def plot(self, ax=None, *, name=None, **kwargs):
+    def plot(self, ax=None, *, name=None, curve_kwargs=None, **kwargs):
         """Plot visualization.
 
         Parameters
@@ -332,21 +366,38 @@ def plot(self, ax=None, *, name=None, **kwargs):
             created.
 
         name : str, default=None
-            Name of DET curve for labeling. If `None`, use `estimator_name` if
-            it is not `None`, otherwise no labeling is shown.
+            Name of DET curve for labeling. If `None`, use `name` provided at
+            `DetCurveDisplay` initialization, otherwise no labeling is shown.
+
+        curve_kwargs : dict, default=None
+            Keywords arguments to be passed to matplotlib's `plot` function.
+
+            .. versionadded:: 1.10
 
         **kwargs : dict
             Additional keywords arguments passed to matplotlib `plot` function.
 
+            .. deprecated:: 1.10
+                `**kwargs` is deprecated and will be removed in 1.12. Pass matplotlib
+                arguments to `curve_kwargs` as a dictionary instead.
+
         Returns
         -------
         display : :class:`~sklearn.metrics.DetCurveDisplay`
             Object that stores computed values.
         """
         self.ax_, self.figure_, name = self._validate_plot_params(ax=ax, name=name)
 
-        line_kwargs = {} if name is None else {"label": name}
-        line_kwargs.update(**kwargs)
+        _, legend_metric = self._get_legend_metric(curve_kwargs, 1, None)
+        (curve_kwargs,) = self._validate_curve_kwargs(
+            1,
+            name,
+            legend_metric,
+            "",
+            curve_kwargs=curve_kwargs,
+            removed_version="1.12",
+            **kwargs,
+        )
 
         # We have the following bounds:
         # sp.stats.norm.ppf(0.0) = -np.inf
@@ -359,7 +410,7 @@ def plot(self, ax=None, *, name=None, **kwargs):
         (self.line_,) = self.ax_.plot(
             sp.stats.norm.ppf(self.fpr),
             sp.stats.norm.ppf(self.fnr),
-            **line_kwargs,
+            **curve_kwargs,
         )
         info_pos_label = (
             f" (Positive label: {self.pos_label})" if self.pos_label is not None else ""
@@ -369,7 +420,7 @@ def plot(self, ax=None, *, name=None, **kwargs):
         ylabel = "False Negative Rate" + info_pos_label
         self.ax_.set(xlabel=xlabel, ylabel=ylabel)
 
-        if "label" in line_kwargs:
+        if curve_kwargs.get("label") is not None:
             self.ax_.legend(loc="lower right")
 
         ticks = [0.001, 0.01, 0.05, 0.20, 0.5, 0.80, 0.95, 0.99, 0.999]

sklearn/metrics/_plot/tests/test_common_curve_display.py

@@ -261,7 +261,7 @@ def test_display_curve_name_overwritten_by_plot_multiple_calls(
             pytest.skip(f"`from_cv_results` not implemented in {Display}")
 
     # TODO: Clean-up once `estimator_name` deprecated in all displays
-    if Display in (PrecisionRecallDisplay, RocCurveDisplay):
+    if Display in (PrecisionRecallDisplay, RocCurveDisplay, DetCurveDisplay):
         assert disp.name == clf_name
     else:
         assert disp.estimator_name == clf_name
@@ -306,7 +306,7 @@ def test_display_curve_not_fitted_errors(pyplot, data_binary, clf, Display):
     disp = Display.from_estimator(model, X, y)
     assert model.__class__.__name__ in disp.line_.get_label()
     # TODO: Clean-up once `estimator_name` deprecated in all displays
-    if Display in (PrecisionRecallDisplay, RocCurveDisplay):
+    if Display in (PrecisionRecallDisplay, RocCurveDisplay, DetCurveDisplay):
         assert disp.name == model.__class__.__name__
     else:
         assert disp.estimator_name == model.__class__.__name__
@@ -802,6 +802,11 @@ def test_display_from_cv_results_curve_kwargs_default_kwargs(
             PrecisionRecallDisplay,
             {"precision": np.array([1, 0.5, 0]), "recall": np.array([0, 0.5, 1])},
         ),
+        # TODO(1.12): Remove
+        (
+            DetCurveDisplay,
+            {"fpr": np.array([0, 0.5, 1]), "fnr": np.array([1, 0.5, 0])},
+        ),
     ],
 )
 def test_display_estimator_name_deprecation(pyplot, Display, display_kwargs):
@@ -818,6 +823,11 @@ def test_display_estimator_name_deprecation(pyplot, Display, display_kwargs):
             PrecisionRecallDisplay,
             {"precision": np.array([1, 0.5, 0]), "recall": np.array([0, 0.5, 1])},
         ),
+        # TODO(1.12): Remove
+        (
+            DetCurveDisplay,
+            {"fpr": np.array([0, 0.5, 1]), "fnr": np.array([1, 0.5, 0])},
+        ),
     ],
 )
 @pytest.mark.parametrize(

sklearn/metrics/_plot/tests/test_det_curve_display.py

@@ -45,7 +45,7 @@ def test_det_curve_display(
 
     common_kwargs = {
         "name": lr.__class__.__name__,
-        "alpha": 0.8,
+        "curve_kwargs": {"alpha": 0.8},
         "sample_weight": sample_weight,
         "drop_intermediate": drop_intermediate,
         "pos_label": pos_label,
@@ -66,7 +66,7 @@ def test_det_curve_display(
     assert_allclose(disp.fpr, fpr, atol=1e-7)
     assert_allclose(disp.fnr, fnr, atol=1e-7)
 
-    assert disp.estimator_name == "LogisticRegression"
+    assert disp.name == "LogisticRegression"
 
     # cannot fail thanks to pyplot fixture
     import matplotlib as mpl
@@ -109,7 +109,7 @@ def test_det_curve_display_default_name(
     else:
         disp = DetCurveDisplay.from_predictions(y, y_score)
 
-    assert disp.estimator_name == expected_clf_name
+    assert disp.name == expected_clf_name
     assert disp.line_.get_label() == expected_clf_name