API Remove sklearn.metrics.manhattan_distances option sum_over_features (#24630)

rusdes · web-flow · commit 7cf938c78ff0 · 2022-10-14T16:05:29.000+02:00
diff --git a/doc/whats_new/v1.2.rst b/doc/whats_new/v1.2.rst
@@ -428,6 +428,10 @@ Changelog
   (`average="micro"`) for the One-vs-Rest multiclass case (`multi_class="ovr"`).
   :pr:`24338` by :user:`Arturo Amor <ArturoAmorQ>`.
 
+- |API| The parameter `sum_over_features` of :func:`metrics.pairwise.manhattan_distances` is deprecated
+  and will be removed in 1.4.
+  :pr:`24630` by :user:`Rushil Desai <rusdes>`.
+
 :mod:`sklearn.model_selection`
 ..............................
 
diff --git a/sklearn/metrics/pairwise.py b/sklearn/metrics/pairwise.py
@@ -873,7 +873,7 @@ def haversine_distances(X, Y=None):
     return DistanceMetric.get_metric("haversine").pairwise(X, Y)
 
 
-def manhattan_distances(X, Y=None, *, sum_over_features=True):
+def manhattan_distances(X, Y=None, *, sum_over_features="deprecated"):
     """Compute the L1 distances between the vectors in X and Y.
 
     With sum_over_features equal to False it returns the componentwise
@@ -895,6 +895,10 @@ def manhattan_distances(X, Y=None, *, sum_over_features=True):
         else it returns the componentwise L1 pairwise-distances.
         Not supported for sparse matrix inputs.
 
+        .. deprecated:: 1.2
+            ``sum_over_features`` was deprecated in version 1.2 and will be removed in
+            1.4.
+
     Returns
     -------
     D : ndarray of shape (n_samples_X * n_samples_Y, n_features) or \
@@ -924,13 +928,17 @@ def manhattan_distances(X, Y=None, *, sum_over_features=True):
          [[1, 2], [0, 3]])
     array([[0., 2.],
            [4., 4.]])
-    >>> import numpy as np
-    >>> X = np.ones((1, 2))
-    >>> y = np.full((2, 2), 2.)
-    >>> manhattan_distances(X, y, sum_over_features=False)
-    array([[1., 1.],
-           [1., 1.]])
     """
+    # TODO(1.4): remove sum_over_features
+    if sum_over_features != "deprecated":
+        warnings.warn(
+            "`sum_over_features` is deprecated in version 1.2 and will be"
+            " removed in version 1.4.",
+            FutureWarning,
+        )
+    else:
+        sum_over_features = True
+
     X, Y = check_pairwise_arrays(X, Y)
 
     if issparse(X) or issparse(Y):
diff --git a/sklearn/metrics/tests/test_pairwise.py b/sklearn/metrics/tests/test_pairwise.py
@@ -196,6 +196,23 @@ def test_pairwise_distances(global_dtype):
         pairwise_distances(X, Y, metric="blah")
 
 
+# TODO(1.4): Remove test when `sum_over_features` parameter is removed
+@pytest.mark.parametrize("sum_over_features", [True, False])
+def test_manhattan_distances_deprecated_sum_over_features(sum_over_features):
+    # Check that future warning is raised when user
+    # enters `sum_over_features` argument.
+    X = [[1, 2], [3, 4]]
+    Y = [[1, 2], [0, 3]]
+    with pytest.warns(
+        FutureWarning,
+        match=(
+            "`sum_over_features` is deprecated in version 1.2 and will be"
+            " removed in version 1.4."
+        ),
+    ):
+        manhattan_distances(X, Y, sum_over_features=sum_over_features)
+
+
 @pytest.mark.parametrize("metric", PAIRWISE_BOOLEAN_FUNCTIONS)
 def test_pairwise_boolean_distance(metric):
     # test that we convert to boolean arrays for boolean distances
