scikit-learn · jeremiedbb · Jun 22, 2022 · Feb 27, 2022 · Mar 2, 2022 · Mar 4, 2022
diff --git a/doc/whats_new/v1.2.rst b/doc/whats_new/v1.2.rst
@@ -114,10 +114,17 @@ Changelog
 :mod:`sklearn.metrics`
 ......................
 
-- |Feature| :func:`class_likelihood_ratios` is added to compute the positive and
+- |Feature| :func:`metrics.class_likelihood_ratios` is added to compute the positive and
   negative likelihood ratios derived from the confusion matrix
   of a binary classification problem. :pr:`22518` by
   :user:`Arturo Amor <ArturoAmorQ>`.
+
+- |Fix| :func:`metrics.ndcg_score` will now trigger a warning when the `y_true`
+  value contains a negative value. Users may still use negative values, but the
+  result may not be between 0 and 1. Starting in v1.4, passing in negative
+  values for `y_true` will raise an error.
+  :pr:`22710` by :user:`Conroy Trinh <trinhcon>` and
+  :pr:`23461` by :user:`Meekail Zain <micky774>`.
 
 :mod:`sklearn.neighbors`
 ........................

diff --git a/sklearn/metrics/_ranking.py b/sklearn/metrics/_ranking.py
@@ -1555,7 +1555,11 @@ def ndcg_score(y_true, y_score, *, k=None, sample_weight=None, ignore_ties=False
     ----------
     y_true : ndarray of shape (n_samples, n_labels)
         True targets of multilabel classification, or true scores of entities
-        to be ranked.
+        to be ranked. Negative values in `y_true` may result in an output
+        that is not between 0 and 1.
+
+        .. versionchanged:: 1.2
+            These negative values are deprecated, and will raise an error in v1.4.
 
     y_score : ndarray of shape (n_samples, n_labels)
         Target scores, can either be probability estimates, confidence values,
@@ -1636,6 +1640,14 @@ def ndcg_score(y_true, y_score, *, k=None, sample_weight=None, ignore_ties=False
     y_true = check_array(y_true, ensure_2d=False)
     y_score = check_array(y_score, ensure_2d=False)
     check_consistent_length(y_true, y_score, sample_weight)
+
+    if y_true.min() < 0:
+        # TODO(1.4): Replace warning w/ ValueError
+        warnings.warn(
+            "ndcg_score should not be used on negative y_true values. ndcg_score will"
+            " raise a ValueError on negative y_true values starting from version 1.4.",
+            FutureWarning,
+        )
     _check_dcg_target_type(y_true)
     gain = _ndcg_sample_scores(y_true, y_score, k=k, ignore_ties=ignore_ties)
     return np.average(gain, weights=sample_weight)

diff --git a/sklearn/metrics/tests/test_ranking.py b/sklearn/metrics/tests/test_ranking.py
@@ -1694,6 +1694,18 @@ def test_ndcg_ignore_ties_with_k():
     )
 
 
+# TODO(1.4): Replace warning w/ ValueError
+def test_ndcg_negative_ndarray_warn():
+    y_true = np.array([[-0.89, -0.53, -0.47, 0.39, 0.56]])
+    y_score = np.array([[0.07, 0.31, 0.75, 0.33, 0.27]])
+    expected_message = (
+        "ndcg_score should not be used on negative y_true values. ndcg_score will raise"
+        " a ValueError on negative y_true values starting from version 1.4."
+    )
+    with pytest.warns(FutureWarning, match=expected_message):
+        assert ndcg_score(y_true, y_score) == pytest.approx(396.0329)
+
+
 def test_ndcg_invariant():
     y_true = np.arange(70).reshape(7, 10)
     y_score = y_true + np.random.RandomState(0).uniform(-0.2, 0.2, size=y_true.shape)