Merge pull request #21645 from seberg/histogram-remove-normed

DEP: Remove `normed=` keyword argument from histograms

6 files changed, 20 insertions, 131 deletions

diff --git a/numpy/lib/histograms.py b/numpy/lib/histograms.py
index 98182f1c4..f7feb2531 100644
--- a/numpy/lib/histograms.py
+++ b/numpy/lib/histograms.py
@@ -671,13 +671,12 @@ def histogram_bin_edges(a, bins=10, range=None, weights=None):
 
 
 def _histogram_dispatcher(
-        a, bins=None, range=None, normed=None, weights=None, density=None):
+        a, bins=None, range=None, density=None, weights=None):
     return (a, bins, weights)
 
 
 @array_function_dispatch(_histogram_dispatcher)
-def histogram(a, bins=10, range=None, normed=None, weights=None,
-              density=None):
+def histogram(a, bins=10, range=None, density=None, weights=None):
     r"""
     Compute the histogram of a dataset.
 
@@ -704,16 +703,6 @@ def histogram(a, bins=10, range=None, normed=None, weights=None,
         computation as well. While bin width is computed to be optimal
         based on the actual data within `range`, the bin count will fill
         the entire range including portions containing no data.
-    normed : bool, optional
-
-        .. deprecated:: 1.6.0
-
-        This is equivalent to the `density` argument, but produces incorrect
-        results for unequal bin widths. It should not be used.
-
-        .. versionchanged:: 1.15.0
-            DeprecationWarnings are actually emitted.
-
     weights : array_like, optional
         An array of weights, of the same shape as `a`.  Each value in
         `a` only contributes its associated weight towards the bin count
@@ -728,8 +717,6 @@ def histogram(a, bins=10, range=None, normed=None, weights=None,
         histogram values will not be equal to 1 unless bins of unity
         width are chosen; it is not a probability *mass* function.
 
-        Overrides the ``normed`` keyword if given.
-
     Returns
     -------
     hist : array
@@ -891,46 +878,15 @@ def histogram(a, bins=10, range=None, normed=None, weights=None,
 
         n = np.diff(cum_n)
 
-    # density overrides the normed keyword
-    if density is not None:
-        if normed is not None:
-            # 2018-06-13, numpy 1.15.0 (this was not noisily deprecated in 1.6)
-            warnings.warn(
-                    "The normed argument is ignored when density is provided. "
-                    "In future passing both will result in an error.",
-                    DeprecationWarning, stacklevel=3)
-        normed = None
-
     if density:
         db = np.array(np.diff(bin_edges), float)
         return n/db/n.sum(), bin_edges
-    elif normed:
-        # 2018-06-13, numpy 1.15.0 (this was not noisily deprecated in 1.6)
-        warnings.warn(
-                "Passing `normed=True` on non-uniform bins has always been "
-                "broken, and computes neither the probability density "
-                "function nor the probability mass function. "
-                "The result is only correct if the bins are uniform, when "
-                "density=True will produce the same result anyway. "
-                "The argument will be removed in a future version of "
-                "numpy.",
-                np.VisibleDeprecationWarning, stacklevel=3)
-
-        # this normalization is incorrect, but
-        db = np.array(np.diff(bin_edges), float)
-        return n/(n*db).sum(), bin_edges
-    else:
-        if normed is not None:
-            # 2018-06-13, numpy 1.15.0 (this was not noisily deprecated in 1.6)
-            warnings.warn(
-                    "Passing normed=False is deprecated, and has no effect. "
-                    "Consider passing the density argument instead.",
-                    DeprecationWarning, stacklevel=3)
-        return n, bin_edges
+
+    return n, bin_edges
 
 
-def _histogramdd_dispatcher(sample, bins=None, range=None, normed=None,
-                            weights=None, density=None):
+def _histogramdd_dispatcher(sample, bins=None, range=None, density=None,
+                            weights=None):
     if hasattr(sample, 'shape'):  # same condition as used in histogramdd
         yield sample
     else:
@@ -941,8 +897,7 @@ def _histogramdd_dispatcher(sample, bins=None, range=None, normed=None,
 
 
 @array_function_dispatch(_histogramdd_dispatcher)
-def histogramdd(sample, bins=10, range=None, normed=None, weights=None,
-                density=None):
+def histogramdd(sample, bins=10, range=None, density=None, weights=None):
     """
     Compute the multidimensional histogram of some data.
 
@@ -979,20 +934,16 @@ def histogramdd(sample, bins=10, range=None, normed=None, weights=None,
         If False, the default, returns the number of samples in each bin.
         If True, returns the probability *density* function at the bin,
         ``bin_count / sample_count / bin_volume``.
-    normed : bool, optional
-        An alias for the density argument that behaves identically. To avoid
-        confusion with the broken normed argument to `histogram`, `density`
-        should be preferred.
     weights : (N,) array_like, optional
         An array of values `w_i` weighing each sample `(x_i, y_i, z_i, ...)`.
-        Weights are normalized to 1 if normed is True. If normed is False,
+        Weights are normalized to 1 if density is True. If density is False,
         the values of the returned histogram are equal to the sum of the
         weights belonging to the samples falling into each bin.
 
     Returns
     -------
     H : ndarray
-        The multidimensional histogram of sample x. See normed and weights
+        The multidimensional histogram of sample x. See density and weights
         for the different possible semantics.
     edges : list
         A list of D arrays describing the bin edges for each dimension.
@@ -1104,16 +1055,6 @@ def histogramdd(sample, bins=10, range=None, normed=None, weights=None,
     core = D*(slice(1, -1),)
     hist = hist[core]
 
-    # handle the aliasing normed argument
-    if normed is None:
-        if density is None:
-            density = False
-    elif density is None:
-        # an explicit normed argument was passed, alias it to the new name
-        density = normed
-    else:
-        raise TypeError("Cannot specify both 'normed' and 'density'")
-
     if density:
         # calculate the probability density function
         s = hist.sum()
diff --git a/numpy/lib/histograms.pyi b/numpy/lib/histograms.pyi
index 27b9dbcfb..ce02718ad 100644
--- a/numpy/lib/histograms.pyi
+++ b/numpy/lib/histograms.pyi
@@ -34,16 +34,14 @@ def histogram(
     a: ArrayLike,
     bins: _BinKind | SupportsIndex | ArrayLike = ...,
     range: None | tuple[float, float] = ...,
-    normed: None = ...,
-    weights: None | ArrayLike = ...,
     density: bool = ...,
+    weights: None | ArrayLike = ...,
 ) -> tuple[NDArray[Any], NDArray[Any]]: ...
 
 def histogramdd(
     sample: ArrayLike,
     bins: SupportsIndex | ArrayLike = ...,
     range: Sequence[tuple[float, float]] = ...,
-    normed: None | bool = ...,
-    weights: None | ArrayLike = ...,
     density: None | bool = ...,
+    weights: None | ArrayLike = ...,
 ) -> tuple[NDArray[Any], list[NDArray[Any]]]: ...
diff --git a/numpy/lib/tests/test_histograms.py b/numpy/lib/tests/test_histograms.py
index fc16b7396..89ee1b256 100644
--- a/numpy/lib/tests/test_histograms.py
+++ b/numpy/lib/tests/test_histograms.py
@@ -38,30 +38,6 @@ class TestHistogram:
         assert_equal(h, np.array([2]))
         assert_allclose(e, np.array([1., 2.]))
 
-    def test_normed(self):
-        sup = suppress_warnings()
-        with sup:
-            rec = sup.record(np.VisibleDeprecationWarning, '.*normed.*')
-            # Check that the integral of the density equals 1.
-            n = 100
-            v = np.random.rand(n)
-            a, b = histogram(v, normed=True)
-            area = np.sum(a * np.diff(b))
-            assert_almost_equal(area, 1)
-            assert_equal(len(rec), 1)
-
-        sup = suppress_warnings()
-        with sup:
-            rec = sup.record(np.VisibleDeprecationWarning, '.*normed.*')
-            # Check with non-constant bin widths (buggy but backwards
-            # compatible)
-            v = np.arange(10)
-            bins = [0, 1, 5, 9, 10]
-            a, b = histogram(v, bins, normed=True)
-            area = np.sum(a * np.diff(b))
-            assert_almost_equal(area, 1)
-            assert_equal(len(rec), 1)
-
     def test_density(self):
         # Check that the integral of the density equals 1.
         n = 100
@@ -819,20 +795,3 @@ class TestHistogramdd:
         hist_dd, edges_dd = histogramdd((v,), (bins,), density=True)
         assert_equal(hist, hist_dd)
         assert_equal(edges, edges_dd[0])
-
-    def test_density_via_normed(self):
-        # normed should simply alias to density argument
-        v = np.arange(10)
-        bins = np.array([0, 1, 3, 6, 10])
-        hist, edges = histogram(v, bins, density=True)
-        hist_dd, edges_dd = histogramdd((v,), (bins,), normed=True)
-        assert_equal(hist, hist_dd)
-        assert_equal(edges, edges_dd[0])
-
-    def test_density_normed_redundancy(self):
-        v = np.arange(10)
-        bins = np.array([0, 1, 3, 6, 10])
-        with assert_raises_regex(TypeError, "Cannot specify both"):
-            hist_dd, edges_dd = histogramdd((v,), (bins,),
-                                            density=True,
-                                            normed=True)
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 3d47abbfb..654ee4cf5 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -634,8 +634,8 @@ def vander(x, N=None, increasing=False):
     return v
 
 
-def _histogram2d_dispatcher(x, y, bins=None, range=None, normed=None,
-                            weights=None, density=None):
+def _histogram2d_dispatcher(x, y, bins=None, range=None, density=None,
+                            weights=None):
     yield x
     yield y
 
@@ -653,8 +653,7 @@ def _histogram2d_dispatcher(x, y, bins=None, range=None, normed=None,
 
 
 @array_function_dispatch(_histogram2d_dispatcher)
-def histogram2d(x, y, bins=10, range=None, normed=None, weights=None,
-                density=None):
+def histogram2d(x, y, bins=10, range=None, density=None, weights=None):
     """
     Compute the bi-dimensional histogram of two data samples.
 
@@ -688,13 +687,9 @@ def histogram2d(x, y, bins=10, range=None, normed=None, weights=None,
         If False, the default, returns the number of samples in each bin.
         If True, returns the probability *density* function at the bin,
         ``bin_count / sample_count / bin_area``.
-    normed : bool, optional
-        An alias for the density argument that behaves identically. To avoid
-        confusion with the broken normed argument to `histogram`, `density`
-        should be preferred.
     weights : array_like, shape(N,), optional
         An array of values ``w_i`` weighing each sample ``(x_i, y_i)``.
-        Weights are normalized to 1 if `normed` is True. If `normed` is
+        Weights are normalized to 1 if `density` is True. If `density` is
         False, the values of the returned histogram are equal to the sum of
         the weights belonging to the samples falling into each bin.
 
@@ -716,7 +711,7 @@ def histogram2d(x, y, bins=10, range=None, normed=None, weights=None,
 
     Notes
     -----
-    When `normed` is True, then the returned histogram is the sample
+    When `density` is True, then the returned histogram is the sample
     density, defined such that the sum over bins of the product
     ``bin_value * bin_area`` is 1.
 
@@ -822,7 +817,7 @@ def histogram2d(x, y, bins=10, range=None, normed=None, weights=None,
     if N != 1 and N != 2:
         xedges = yedges = asarray(bins)
         bins = [xedges, yedges]
-    hist, edges = histogramdd([x, y], bins, range, normed, weights, density)
+    hist, edges = histogramdd([x, y], bins, range, density, weights)
     return hist, edges[0], edges[1]
 
 
diff --git a/numpy/lib/twodim_base.pyi b/numpy/lib/twodim_base.pyi
index 120abb7e0..1b3b94bd5 100644
--- a/numpy/lib/twodim_base.pyi
+++ b/numpy/lib/twodim_base.pyi
@@ -166,9 +166,8 @@ def histogram2d(  # type: ignore[misc]
     y: _ArrayLikeFloat_co,
     bins: int | Sequence[int] = ...,
     range: None | _ArrayLikeFloat_co = ...,
-    normed: None | bool = ...,
-    weights: None | _ArrayLikeFloat_co = ...,
     density: None | bool = ...,
+    weights: None | _ArrayLikeFloat_co = ...,
 ) -> tuple[
     NDArray[float64],
     NDArray[floating[Any]],
@@ -180,9 +179,8 @@ def histogram2d(
     y: _ArrayLikeComplex_co,
     bins: int | Sequence[int] = ...,
     range: None | _ArrayLikeFloat_co = ...,
-    normed: None | bool = ...,
-    weights: None | _ArrayLikeFloat_co = ...,
     density: None | bool = ...,
+    weights: None | _ArrayLikeFloat_co = ...,
 ) -> tuple[
     NDArray[float64],
     NDArray[complexfloating[Any, Any]],
@@ -194,9 +192,8 @@ def histogram2d(
     y: _ArrayLikeComplex_co,
     bins: Sequence[_ArrayLikeInt_co],
     range: None | _ArrayLikeFloat_co = ...,
-    normed: None | bool = ...,
-    weights: None | _ArrayLikeFloat_co = ...,
     density: None | bool = ...,
+    weights: None | _ArrayLikeFloat_co = ...,
 ) -> tuple[
     NDArray[float64],
     NDArray[Any],
diff --git a/numpy/typing/tests/data/fail/histograms.pyi b/numpy/typing/tests/data/fail/histograms.pyi
index ad151488d..22499d391 100644
--- a/numpy/typing/tests/data/fail/histograms.pyi
+++ b/numpy/typing/tests/data/fail/histograms.pyi
@@ -7,7 +7,6 @@ AR_f8: npt.NDArray[np.float64]
 np.histogram_bin_edges(AR_i8, range=(0, 1, 2))  # E: incompatible type
 
 np.histogram(AR_i8, range=(0, 1, 2))  # E: incompatible type
-np.histogram(AR_i8, normed=True)  # E: incompatible type
 
 np.histogramdd(AR_i8, range=(0, 1))  # E: incompatible type
 np.histogramdd(AR_i8, range=[(0, 1, 2)])  # E: incompatible type