diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index aae423b65cc3..dfa0ab608aaf 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -6780,8 +6780,8 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, return tops, bins, cbook.silent_list('Lists of Patches', patches) @_preprocess_data(replace_names=["x", "y", "weights"], label_namer=None) - def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None, - cmin=None, cmax=None, **kwargs): + def hist2d(self, x, y, bins=10, range=None, density=None, weights=None, + cmin=None, cmax=None, normed=None, **kwargs): """ Make a 2D histogram plot. @@ -6814,8 +6814,14 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None, xmax], [ymin, ymax]]``. All values outside of this range will be considered outliers and not tallied in the histogram. - normed : bool, optional, default: False - Normalize histogram. + density : boolean, optional + If False, the default, plots and returns the number of samples + in each bin. If True, returns the probability *density* + function at the bin, ``bin_count / sample_count / bin_area``. + Default is ``None`` for both *normed* and *density*. If either is + set, then that value will be used. If neither are set, then the + args will be treated as ``False``. + If both *density* and *normed* are set an error is raised. weights : array_like, shape (n, ), optional, default: None An array of values w_i weighing each sample (x_i, y_i). @@ -6830,6 +6836,12 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None, to none before passing to imshow) and these count values in the return value count histogram will also be set to nan upon return + normed : bool, optional, default: None + Deprecated; use the density keyword argument instead. + Numpy 1.15 introduced a 'density' kwarg to ``hist2d``. Even though + Numpy 1.15 isn't required, 'density' kwarg is introduced + and passed as 'normed' to ``hist2d``. + Returns ------- h : 2D array @@ -6873,8 +6885,17 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None, `.colors.PowerNorm`. """ + if density is not None and normed is not None: + raise ValueError("kwargs 'density' and 'normed' cannot be used " + "simultaneously. Please only use 'density', " + "since 'normed' is deprecated.") + if normed is not None: + cbook.warn_deprecated("3.1", name="'normed'", obj_type="kwarg", + alternative="'density") + + density = bool(density) or bool(normed) h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range, - normed=normed, weights=weights) + normed=density, weights=weights) if cmin is not None: h[h < cmin] = None diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 6ceced49285c..f017ed540cd3 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -2640,12 +2640,12 @@ def hist( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.hist2d) def hist2d( - x, y, bins=10, range=None, normed=False, weights=None, - cmin=None, cmax=None, *, data=None, **kwargs): + x, y, bins=10, range=None, density=None, weights=None, + cmin=None, cmax=None, normed=None, *, data=None, **kwargs): __ret = gca().hist2d( - x, y, bins=bins, range=range, normed=normed, weights=weights, - cmin=cmin, cmax=cmax, **({"data": data} if data is not None - else {}), **kwargs) + x, y, bins=bins, range=range, density=density, + weights=weights, cmin=cmin, cmax=cmax, normed=normed, + **({"data": data} if data is not None else {}), **kwargs) sci(__ret[-1]) return __ret diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py index b4879e3b208a..35d52fb3a94f 100644 --- a/lib/matplotlib/tests/test_axes.py +++ b/lib/matplotlib/tests/test_axes.py @@ -1672,6 +1672,30 @@ def test_hist2d(): ax.hist2d("x", "y", bins=10, data=data, rasterized=True) +@pytest.mark.parametrize('density', [False, True]) +def test_hist2d_density(density): + # Test density kwarg + x = np.random.randn(100)*2+5 + y = np.random.randn(100)-2 + fig = plt.figure() + ax = fig.add_subplot(111) + ax.hist2d(x, y, bins=10, rasterized=True, density=density) + + +@pytest.mark.parametrize('normed', [False, True]) +@pytest.mark.parametrize('density', [False, True]) +def test_hist2d_normed_density(density, normed): + # Normed and density should not be used simultaneously + x = np.random.randn(100)*2+5 + y = np.random.randn(100)-2 + fig = plt.figure() + ax = fig.add_subplot(111) + # test that kwargs normed and density cannot be set both. + with pytest.raises(ValueError, match="kwargs 'density' and 'normed'"): + ax.hist2d(x, y, bins=10, rasterized=True, + density=density, normed=normed) + + @image_comparison(baseline_images=['hist2d_transpose'], remove_text=True, style='mpl20') def test_hist2d_transpose():