diff --git a/doc/api/next_api_changes/2019-06-29-TH.rst b/doc/api/next_api_changes/2019-06-29-TH.rst new file mode 100644 index 000000000000..29081243e302 --- /dev/null +++ b/doc/api/next_api_changes/2019-06-29-TH.rst @@ -0,0 +1,5 @@ +Deprecations +```````````` + +Passing negative numbers to ``hist(cumulative=...)`` is deprecated. Pass the +string 'reversed' instead. diff --git a/examples/statistics/histogram_cumulative.py b/examples/statistics/histogram_cumulative.py index b027cb3066da..d5e18015d10b 100644 --- a/examples/statistics/histogram_cumulative.py +++ b/examples/statistics/histogram_cumulative.py @@ -59,7 +59,7 @@ ax.plot(bins, y, 'k--', linewidth=1.5, label='Theoretical') # Overlay a reversed cumulative histogram. -ax.hist(x, bins=bins, density=True, histtype='step', cumulative=-1, +ax.hist(x, bins=bins, density=True, histtype='step', cumulative='reversed', label='Reversed emp.') # tidy up the figure diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 30c9d25e8fc0..867dc738c7d0 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -6415,7 +6415,7 @@ def hist(self, x, bins=None, range=None, density=False, weights=None, (or you may alternatively use `~.bar()`). - cumulative : bool or -1, optional + cumulative : bool or 'reversed', optional If ``True``, then a histogram is computed where each bin gives the counts in that bin plus all bins for smaller values. The last bin gives the total number of datapoints. @@ -6423,10 +6423,9 @@ def hist(self, x, bins=None, range=None, density=False, weights=None, If *density* is also ``True`` then the histogram is normalized such that the last bin equals 1. - If *cumulative* is a number less than 0 (e.g., -1), the direction - of accumulation is reversed. In this case, if *density* is also - ``True``, then the histogram is normalized such that the first bin - equals 1. + If *cumulative* is 'reversed', the direction of accumulation is + reversed. In this case, if *density* is also ``True``, then the + histogram is normalized such that the first bin equals 1. Default is ``False`` @@ -6647,7 +6646,14 @@ def hist(self, x, bins=None, range=None, density=False, weights=None, m[:] = (m / db) / tops[-1].sum() if cumulative: slc = slice(None) + if cumulative == 'reversed': + slc = slice(None, None, -1) if isinstance(cumulative, Number) and cumulative < 0: + cbook.warn_deprecated("3.2", + message="Passing negative numbers to " + "hist(cumulative=...) is " + "deprecated. Pass 'reversed' " + "instead.") slc = slice(None, None, -1) if density: