diff --git a/doc/users/next_whats_new/2018-10-11-AL.rst b/doc/users/next_whats_new/2018-10-11-AL.rst new file mode 100644 index 000000000000..9bf7c010f53d --- /dev/null +++ b/doc/users/next_whats_new/2018-10-11-AL.rst @@ -0,0 +1,7 @@ +Introduction of :rc:`hist.histtype` +``````````````````````````````````` + +The default value of the ``histtype`` argument to `Axes.hist()` can now be +controlled using :rc:`hist.histtype`. For large numbers of bins, setting +this value to 'step' or 'stepfilled' can result in significant performance +improvements over 'bar', the current default. diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 937673b39f13..f6a55a3f1ec5 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -6259,7 +6259,7 @@ def table(self, **kwargs): @_preprocess_data(replace_names=["x", 'weights'], label_namer="x") def hist(self, x, bins=None, range=None, density=None, weights=None, - cumulative=False, bottom=None, histtype='bar', align='mid', + cumulative=False, bottom=None, histtype=None, align='mid', orientation='vertical', rwidth=None, log=False, color=None, label=None, stacked=False, normed=None, **kwargs): @@ -6319,7 +6319,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, is based on the specified bin range instead of the range of x. - Default is ``None`` + Default is ``None``. density : bool, optional If ``True``, the first element of the return tuple will @@ -6343,7 +6343,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, the weights are normalized, so that the integral of the density over the range remains 1. - Default is ``None`` + Default is ``None``. cumulative : bool, optional If ``True``, then a histogram is computed where each bin gives the @@ -6355,7 +6355,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, In this case, if *normed* and/or *density* is also ``True``, then the histogram is normalized such that the first bin equals 1. - Default is ``False`` + Default is ``False``. bottom : array_like, scalar, or None Location of the bottom baseline of each bin. If a scalar, @@ -6363,35 +6363,31 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, If an array, each bin is shifted independently and the length of bottom must match the number of bins. If None, defaults to 0. - Default is ``None`` + Default is ``None``. histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional The type of histogram to draw. - - 'bar' is a traditional bar-type histogram. If multiple data - are given the bars are arranged side by side. + - 'bar' is a traditional bar-type histogram. If multiple data are + given the bars are arranged side by side. + - 'barstacked' is a bar-type histogram where multiple data are + stacked on top of each other. + - 'step' generates a lineplot that is by default unfilled. + - 'stepfilled' generates a lineplot that is by default filled. - - 'barstacked' is a bar-type histogram where multiple - data are stacked on top of each other. + For large numbers of bins, 'step' and 'stepfilled' can be + significantly faster than 'bar' and 'barstacked'. - - 'step' generates a lineplot that is by default - unfilled. - - - 'stepfilled' generates a lineplot that is by default - filled. - - Default is 'bar' + Default is taken from :rc:`hist.histtype`. align : {'left', 'mid', 'right'}, optional Controls how the histogram is plotted. - - 'left': bars are centered on the left bin edges. - - - 'mid': bars are centered between the bin edges. - - - 'right': bars are centered on the right bin edges. + - 'left': bars are centered on the left bin edges. + - 'mid': bars are centered between the bin edges. + - 'right': bars are centered on the right bin edges. - Default is 'mid' + Default is 'mid'. orientation : {'horizontal', 'vertical'}, optional If 'horizontal', `~matplotlib.pyplot.barh` will be used for @@ -6403,7 +6399,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, Ignored if *histtype* is 'step' or 'stepfilled'. - Default is ``None`` + Default is ``None``. log : bool, optional If ``True``, the histogram axis will be set to a log scale. If @@ -6411,27 +6407,27 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, filtered out and only the non-empty ``(n, bins, patches)`` will be returned. - Default is ``False`` + Default is ``False``. color : color or array_like of colors or None, optional Color spec or sequence of color specs, one per dataset. Default (``None``) uses the standard line color sequence. - Default is ``None`` + Default is ``None``. label : str or None, optional String, or sequence of strings to match multiple datasets. Bar charts yield multiple patches per dataset, but only the first gets the label, so that the legend command will work as expected. - default is ``None`` + Default is ``None``. stacked : bool, optional - If ``True``, multiple data are stacked on top of each other If + If ``True``, multiple data are stacked on top of each other. If ``False`` multiple data are arranged side by side if histtype is 'bar' or on top of each other if histtype is 'step' - Default is ``False`` + Default is ``False``. normed : bool, optional Deprecated; use the density keyword argument instead. @@ -6478,6 +6474,8 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, if bins is None: bins = rcParams['hist.bins'] + if histtype is None: + histtype = rcParams['hist.histtype'] # Validate string inputs here so we don't have to clutter # subsequent code. diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 6ceced49285c..2ae018c7e3a5 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -2625,7 +2625,7 @@ def hexbin( @docstring.copy_dedent(Axes.hist) def hist( x, bins=None, range=None, density=None, weights=None, - cumulative=False, bottom=None, histtype='bar', align='mid', + cumulative=False, bottom=None, histtype=None, align='mid', orientation='vertical', rwidth=None, log=False, color=None, label=None, stacked=False, normed=None, *, data=None, **kwargs): diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py index 4933bd0bd8ea..c35862663b6a 100644 --- a/lib/matplotlib/rcsetup.py +++ b/lib/matplotlib/rcsetup.py @@ -1034,6 +1034,10 @@ def _validate_linestyle(ls): ## Histogram properties 'hist.bins': [10, validate_hist_bins], + 'hist.histtype': [ + 'bar', + ValidateInStrings( + 'histtype', ['bar', 'barstacked', 'step', 'stepfilled'])], ## Boxplot properties 'boxplot.notch': [False, validate_bool], diff --git a/matplotlibrc.template b/matplotlibrc.template index 9ce42e460f58..fac7c4538393 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -481,6 +481,7 @@ #hist.bins : 10 ## The default number of histogram bins. ## If Numpy 1.11 or later is ## installed, may also be `auto` +#hist.histtype : bar ## The default histtype. #### SCATTER PLOTS #scatter.marker : o ## The default marker type for scatter plots.