API Replace y_pred with y_score in DetCurveDisplay and PrecisionRecallDisplay (scikit-learn#31764)

Co-authored-by: Jérémie du Boisberranger <jeremie@probabl.ai>

Author: luiser1401

doc/whats_new/upcoming_changes/sklearn.metrics/31764.fix.rst

@@ -0,0 +1,5 @@
+- `y_pred` is deprecated in favour of `y_score` in
+  :func:`metrics.DetCurveDisplay.from_predictions` and
+  :func:`metrics.PrecisionRecallDisplay.from_predictions`. `y_pred` will be removed in
+  v1.10.
+  By :user:`Luis <luiser1401>`

sklearn/metrics/_plot/det_curve.py

@@ -4,7 +4,10 @@
 import numpy as np
 import scipy as sp
 
-from ...utils._plotting import _BinaryClassifierCurveDisplayMixin
+from ...utils._plotting import (
+    _BinaryClassifierCurveDisplayMixin,
+    _deprecate_y_pred_parameter,
+)
 from .._ranking import det_curve
 
 
@@ -67,8 +70,8 @@ class DetCurveDisplay(_BinaryClassifierCurveDisplayMixin):
     >>> X_train, X_test, y_train, y_test = train_test_split(
     ...     X, y, test_size=0.4, random_state=0)
     >>> clf = SVC(random_state=0).fit(X_train, y_train)
-    >>> y_pred = clf.decision_function(X_test)
-    >>> fpr, fnr, _ = det_curve(y_test, y_pred)
+    >>> y_score = clf.decision_function(X_test)
+    >>> fpr, fnr, _ = det_curve(y_test, y_score)
     >>> display = DetCurveDisplay(
     ...     fpr=fpr, fnr=fnr, estimator_name="SVC"
     ... )
@@ -178,7 +181,7 @@ def from_estimator(
         <...>
         >>> plt.show()
         """
-        y_pred, pos_label, name = cls._validate_and_get_response_values(
+        y_score, pos_label, name = cls._validate_and_get_response_values(
             estimator,
             X,
             y,
@@ -189,7 +192,7 @@ def from_estimator(
 
         return cls.from_predictions(
             y_true=y,
-            y_pred=y_pred,
+            y_score=y_score,
             sample_weight=sample_weight,
             drop_intermediate=drop_intermediate,
             name=name,
@@ -202,13 +205,14 @@ def from_estimator(
     def from_predictions(
         cls,
         y_true,
-        y_pred,
+        y_score=None,
         *,
         sample_weight=None,
         drop_intermediate=True,
         pos_label=None,
         name=None,
         ax=None,
+        y_pred="deprecated",
         **kwargs,
     ):
         """Plot the DET curve given the true and predicted labels.
@@ -225,11 +229,14 @@ def from_predictions(
         y_true : array-like of shape (n_samples,)
             True labels.
 
-        y_pred : array-like of shape (n_samples,)
+        y_score : array-like of shape (n_samples,)
             Target scores, can either be probability estimates of the positive
             class, confidence values, or non-thresholded measure of decisions
             (as returned by `decision_function` on some classifiers).
 
+            .. versionadded:: 1.8
+                `y_pred` has been renamed to `y_score`.
+
         sample_weight : array-like of shape (n_samples,), default=None
             Sample weights.
 
@@ -253,6 +260,15 @@ def from_predictions(
             Axes object to plot on. If `None`, a new figure and axes is
             created.
 
+        y_pred : array-like of shape (n_samples,)
+            Target scores, can either be probability estimates of the positive
+            class, confidence values, or non-thresholded measure of decisions
+            (as returned by “decision_function” on some classifiers).
+
+            .. deprecated:: 1.8
+                `y_pred` is deprecated and will be removed in 1.10. Use
+                `y_score` instead.
+
         **kwargs : dict
             Additional keywords arguments passed to matplotlib `plot` function.
 
@@ -278,19 +294,20 @@ def from_predictions(
         >>> X_train, X_test, y_train, y_test = train_test_split(
         ...     X, y, test_size=0.4, random_state=0)
         >>> clf = SVC(random_state=0).fit(X_train, y_train)
-        >>> y_pred = clf.decision_function(X_test)
+        >>> y_score = clf.decision_function(X_test)
         >>> DetCurveDisplay.from_predictions(
-        ...    y_test, y_pred)
+        ...    y_test, y_score)
         <...>
         >>> plt.show()
         """
+        y_score = _deprecate_y_pred_parameter(y_score, y_pred, "1.8")
         pos_label_validated, name = cls._validate_from_predictions_params(
-            y_true, y_pred, sample_weight=sample_weight, pos_label=pos_label, name=name
+            y_true, y_score, sample_weight=sample_weight, pos_label=pos_label, name=name
         )
 
         fpr, fnr, _ = det_curve(
             y_true,
-            y_pred,
+            y_score,
             pos_label=pos_label,
             sample_weight=sample_weight,
             drop_intermediate=drop_intermediate,

sklearn/metrics/_plot/precision_recall_curve.py

@@ -5,6 +5,7 @@
 
 from ...utils._plotting import (
     _BinaryClassifierCurveDisplayMixin,
+    _deprecate_y_pred_parameter,
     _despine,
     _validate_style_kwargs,
 )
@@ -383,7 +384,7 @@ def from_estimator(
         <...>
         >>> plt.show()
         """
-        y_pred, pos_label, name = cls._validate_and_get_response_values(
+        y_score, pos_label, name = cls._validate_and_get_response_values(
             estimator,
             X,
             y,
@@ -394,7 +395,7 @@ def from_estimator(
 
         return cls.from_predictions(
             y,
-            y_pred,
+            y_score,
             sample_weight=sample_weight,
             name=name,
             pos_label=pos_label,
@@ -410,7 +411,7 @@ def from_estimator(
     def from_predictions(
         cls,
         y_true,
-        y_pred,
+        y_score=None,
         *,
         sample_weight=None,
         drop_intermediate=False,
@@ -420,6 +421,7 @@ def from_predictions(
         plot_chance_level=False,
         chance_level_kw=None,
         despine=False,
+        y_pred="deprecated",
         **kwargs,
     ):
         """Plot precision-recall curve given binary class predictions.
@@ -434,9 +436,12 @@ def from_predictions(
         y_true : array-like of shape (n_samples,)
             True binary labels.
 
-        y_pred : array-like of shape (n_samples,)
+        y_score : array-like of shape (n_samples,)
             Estimated probabilities or output of decision function.
 
+            .. versionadded:: 1.8
+                `y_pred` has been renamed to `y_score`.
+
         sample_weight : array-like of shape (n_samples,), default=None
             Sample weights.
 
@@ -478,6 +483,13 @@ def from_predictions(
 
             .. versionadded:: 1.6
 
+        y_pred : array-like of shape (n_samples,)
+            Estimated probabilities or output of decision function.
+
+            .. deprecated:: 1.8
+                `y_pred` is deprecated and will be removed in 1.10. Use
+                `y_score` instead.
+
         **kwargs : dict
             Keyword arguments to be passed to matplotlib's `plot`.
 
@@ -514,25 +526,26 @@ def from_predictions(
         >>> clf = LogisticRegression()
         >>> clf.fit(X_train, y_train)
         LogisticRegression()
-        >>> y_pred = clf.predict_proba(X_test)[:, 1]
+        >>> y_score = clf.predict_proba(X_test)[:, 1]
         >>> PrecisionRecallDisplay.from_predictions(
-        ...    y_test, y_pred)
+        ...    y_test, y_score)
         <...>
         >>> plt.show()
         """
+        y_score = _deprecate_y_pred_parameter(y_score, y_pred, "1.8")
         pos_label, name = cls._validate_from_predictions_params(
-            y_true, y_pred, sample_weight=sample_weight, pos_label=pos_label, name=name
+            y_true, y_score, sample_weight=sample_weight, pos_label=pos_label, name=name
         )
 
         precision, recall, _ = precision_recall_curve(
             y_true,
-            y_pred,
+            y_score,
             pos_label=pos_label,
             sample_weight=sample_weight,
             drop_intermediate=drop_intermediate,
         )
         average_precision = average_precision_score(
-            y_true, y_pred, pos_label=pos_label, sample_weight=sample_weight
+            y_true, y_score, pos_label=pos_label, sample_weight=sample_weight
         )
 
         class_count = Counter(y_true)

sklearn/metrics/_plot/roc_curve.py

@@ -2,8 +2,6 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 
-import warnings
-
 import numpy as np
 
 from ...utils import _safe_indexing
@@ -12,6 +10,7 @@
     _check_param_lengths,
     _convert_to_list_leaving_none,
     _deprecate_estimator_name,
+    _deprecate_y_pred_parameter,
     _despine,
     _validate_style_kwargs,
 )
@@ -576,24 +575,7 @@ def from_predictions(
         <...>
         >>> plt.show()
         """
-        # TODO(1.9): remove after the end of the deprecation period of `y_pred`
-        if y_score is not None and not (
-            isinstance(y_pred, str) and y_pred == "deprecated"
-        ):
-            raise ValueError(
-                "`y_pred` and `y_score` cannot be both specified. Please use `y_score`"
-                " only as `y_pred` is deprecated in 1.7 and will be removed in 1.9."
-            )
-        if not (isinstance(y_pred, str) and y_pred == "deprecated"):
-            warnings.warn(
-                (
-                    "y_pred is deprecated in 1.7 and will be removed in 1.9. "
-                    "Please use `y_score` instead."
-                ),
-                FutureWarning,
-            )
-            y_score = y_pred
-
+        y_score = _deprecate_y_pred_parameter(y_score, y_pred, "1.7")
         pos_label_validated, name = cls._validate_from_predictions_params(
             y_true, y_score, sample_weight=sample_weight, pos_label=pos_label, name=name
         )

sklearn/metrics/_plot/tests/test_det_curve_display.py

@@ -37,10 +37,9 @@ def test_det_curve_display(
 
     lr = LogisticRegression()
     lr.fit(X, y)
-    y_pred = getattr(lr, response_method)(X)
-    if y_pred.ndim == 2:
-        y_pred = y_pred[:, 1]
-
+    y_score = getattr(lr, response_method)(X)
+    if y_score.ndim == 2:
+        y_score = y_score[:, 1]
     # safe guard for the binary if/else construction
     assert constructor_name in ("from_estimator", "from_predictions")
 
@@ -54,11 +53,11 @@ def test_det_curve_display(
     if constructor_name == "from_estimator":
         disp = DetCurveDisplay.from_estimator(lr, X, y, **common_kwargs)
     else:
-        disp = DetCurveDisplay.from_predictions(y, y_pred, **common_kwargs)
+        disp = DetCurveDisplay.from_predictions(y, y_score, **common_kwargs)
 
     fpr, fnr, _ = det_curve(
         y,
-        y_pred,
+        y_score,
         sample_weight=sample_weight,
         drop_intermediate=drop_intermediate,
         pos_label=pos_label,
@@ -103,12 +102,30 @@ def test_det_curve_display_default_name(
     X, y = X[y < 2], y[y < 2]
 
     lr = LogisticRegression().fit(X, y)
-    y_pred = lr.predict_proba(X)[:, 1]
+    y_score = lr.predict_proba(X)[:, 1]
 
     if constructor_name == "from_estimator":
         disp = DetCurveDisplay.from_estimator(lr, X, y)
     else:
-        disp = DetCurveDisplay.from_predictions(y, y_pred)
+        disp = DetCurveDisplay.from_predictions(y, y_score)
 
     assert disp.estimator_name == expected_clf_name
     assert disp.line_.get_label() == expected_clf_name
+
+
+# TODO(1.10): remove
+def test_y_score_and_y_pred_specified_error(pyplot):
+    """1. Check that an error is raised when both y_score and y_pred are specified.
+    2. Check that a warning is raised when y_pred is specified.
+    """
+    y_true = np.array([0, 0, 1, 1])
+    y_score = np.array([0.1, 0.4, 0.35, 0.8])
+    y_pred = np.array([0.2, 0.3, 0.5, 0.1])
+
+    with pytest.raises(
+        ValueError, match="`y_pred` and `y_score` cannot be both specified"
+    ):
+        DetCurveDisplay.from_predictions(y_true, y_score=y_score, y_pred=y_pred)
+
+    with pytest.warns(FutureWarning, match="y_pred was deprecated in 1.8"):
+        DetCurveDisplay.from_predictions(y_true, y_pred=y_score)