8000 Merge pull request #5343 from phobson/bxp-equal-quartiles · matplotlib/matplotlib@455cb92 · GitHub
[go: up one dir, main page]
Skip to content

Commit 455cb92

Browse files< 8000 /div>
jenshnielsenjenshnielsen
committed
Merge pull request #5343 from phobson/bxp-equal-quartiles
Boxplot stats w/ equal quartiles
2 parents 8afb493 + 6fe8a72 commit 455cb92

File tree

9 files changed

+214
-542
lines changed

9 files changed

+214
-542
lines changed

‎doc/api/api_changes/2016-03-13-PMH.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Changed default ``autorange`` behavior in boxplots
2+
``````````````````````````````````````````````````
3+
4+
Prior to v1.5.2, the whiskers of boxplots would extend to the mininum
5+
and maximum values if the quartiles were all equal (i.e., Q1 = median
6+
= Q3). This behavior has been disabled by default to restore consistency
7+
with other plotting packages.
8+
9+
To restore the old behavior, simply set ``autorange=True`` when
10+
calling ``plt.boxplot``.

‎lib/matplotlib/axes/_axes.py

Lines changed: 139 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -3050,9 +3050,10 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
30503050
positions=None, widths=None, patch_artist=None,
30513051
bootstrap=None, usermedians=None, conf_intervals=None,
30523052
meanline=None, showmeans=None, showcaps=None,
3053-
showbox=None, showfliers=None, boxprops=None, labels=None,
3054-
flierprops=None, medianprops=None, meanprops=None,
3055-
capprops=None, whiskerprops=None, manage_xticks=True):
3053+
showbox=None, showfliers=None, boxprops=None,
3054+
labels=None, flierprops=None, medianprops=None,
3055+
meanprops=None, capprops=None, whiskerprops=None,
3056+
manage_xticks=True, autorange=False):
30563057
"""
30573058
Make a box and whisker plot.
30583059
@@ -3062,161 +3063,167 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
30623063
positions=None, widths=None, patch_artist=False,
30633064
bootstrap=None, usermedians=None, conf_intervals=None,
30643065
meanline=False, showmeans=False, showcaps=True,
3065-
showbox=True, showfliers=True, boxprops=None, labels=None,
3066-
flierprops=None, medianprops=None, meanprops=None,
3067-
capprops=None, whiskerprops=None, manage_xticks=True):
3066+
showbox=True, showfliers=True, boxprops=None,
3067+
labels=None, flierprops=None, medianprops=None,
3068+
meanprops=None, capprops=None, whiskerprops=None,
3069+
manage_xticks=True, autorange=False):
30683070
3069-
Make a box and whisker plot for each column of *x* or each
3070-
vector in sequence *x*. The box extends from the lower to
3071+
Make a box and whisker plot for each column of ``x`` or each
3072+
vector in sequence ``x``. The box extends from the lower to
30713073
upper quartile values of the data, with a line at the median.
30723074
The whiskers extend from the box to show the range of the
30733075
data. Flier points are those past the end of the whiskers.
30743076
30753077
Parameters
30763078
----------
30773079
x : Array or a sequence of vectors.
3078-
The input data.
3079-
3080-
notch : bool, default = False
3081-
If False, produces a rectangular box plot.
3082-
If True, will produce a notched box plot
3083-
3084-
sym : str or None, default = None
3085-
The default symbol for flier points.
3086-
Enter an empty string ('') if you don't want to show fliers.
3087-
If `None`, then the fliers default to 'b+' If you want more
3088-
control use the flierprops kwarg.
3089-
3090-
vert : bool, default = True
3091-
If True (default), makes the boxes vertical.
3092-
If False, makes horizontal boxes.
3093-
3094-
whis : float, sequence (default = 1.5) or string
3095-
As a float, determines the reach of the whiskers past the first
3096-
and third quartiles (e.g., Q3 + whis*IQR, IQR = interquartile
3097-
range, Q3-Q1). Beyond the whiskers, data are considered outliers
3098-
and are plotted as individual points. Set this to an unreasonably
3099-
high value to force the whiskers to show the min and max values.
3100-
Alternatively, set this to an ascending sequence of percentile
3101-
(e.g., [5, 95]) to set the whiskers at specific percentiles of
3102-
the data. Finally, *whis* can be the string 'range' to force the
3103-
whiskers to the min and max of the data. In the edge case that
3104-
the 25th and 75th percentiles are equivalent, *whis* will be
3105-
automatically set to 'range'.
3106-
3107-
bootstrap : None (default) or integer
3108-
Specifies whether to bootstrap the confidence intervals
3109-
around the median for notched boxplots. If bootstrap==None,
3110-
no bootstrapping is performed, and notches are calculated
3111-
using a Gaussian-based asymptotic approximation (see McGill, R.,
3112-
Tukey, J.W., and Larsen, W.A., 1978, and Kendall and Stuart,
3113-
1967). Otherwise, bootstrap specifies the number of times to
3114-
bootstrap the median to determine it's 95% confidence intervals.
3115-
Values between 1000 and 10000 are recommended.
3116-
3117-
usermedians : array-like or None (default)
3118-
An array or sequence whose first dimension (or length) is
3119-
compatible with *x*. This overrides the medians computed by
3120-
matplotlib for each element of *usermedians* that is not None.
3121-
When an element of *usermedians* == None, the median will be
3122-
computed by matplotlib as normal.
3123-
3124-
conf_intervals : array-like or None (default)
3125-
Array or sequence whose first dimension (or length) is compatible
3126-
with *x* and whose second dimension is 2. When the current element
3127-
of *conf_intervals* is not None, the notch locations computed by
3128-
matplotlib are overridden (assuming notch is True). When an
3129-
element of *conf_intervals* is None, boxplot compute notches the
3130-
method specified by the other kwargs (e.g., *bootstrap*).
3131-
3132-
positions : array-like, default = [1, 2, ..., n]
3133-
Sets the positions of the boxes. The ticks and limits
3134-
are automatically set to match the positions.
3135-
3136-
widths : array-like, default = 0.5
3137-
Either a scalar or a vector and sets the width of each box. The
3138-
default is 0.5, or ``0.15*(distance between extreme positions)``
3139-
if that is smaller.
3140-
3141-
labels : sequence or None (default)
3142-
Labels for each dataset. Length must be compatible with
3143-
dimensions of *x*
3144-
3145-
patch_artist : bool, default = False
3146-
If False produces boxes with the Line2D artist
3147-
If True produces boxes with the Patch artist
3148-
3149-
showmeans : bool, default = False
3150-
If True, will toggle on the rendering of the means
3151-
3152-
showcaps : bool, default = True
3153-
If True, will toggle on the rendering of the caps
3154-
3155-
showbox : bool, default = True
3156-
If True, will toggle on the rendering of the box
3157-
3158-
showfliers : bool, default = True
3159-
If True, will toggle on the rendering of the fliers
3160-
3161-
boxprops : dict or None (default)
3162-
If provided, will set the plotting style of the boxes
3163-
3164-
whiskerprops : dict or None (default)
3165-
If provided, will set the plotting style of the whiskers
3080+
The input data.
3081+
3082+
notch : bool, optional (False)
3083+
If `True`, will produce a notched box plot. Otherwise, a
3084+
rectangular boxplot is produced.
3085+
3086+
sym : str, optional
3087+
The default symbol for flier points. Enter an empty string
3088+
('') if you don't want to show fliers. If `None`, then the
3089+
fliers default to 'b+' If you want more control use the
3090+
flierprops kwarg.
3091+
3092+
vert : bool, optional (True)
3093+
If `True` (default), makes the boxes vertical. If `False`,
3094+
everything is drawn horizontally.
3095+
3096+
whis : float, sequence, or string (default = 1.5)
3097+
As a float, determines the reach of the whiskers past the
3098+
first and third quartiles (e.g., Q3 + whis*IQR,
3099+
IQR = interquartile range, Q3-Q1). Beyond the whiskers, data
3100+
are considered outliers and are plotted as individual
3101+
points. Set this to an unreasonably high value to force the
3102+
whiskers to show the min and max values. Alternatively, set
3103+
this to an ascending sequence of percentile (e.g., [5, 95])
3104+
to set the whiskers at specific percentiles of the data.
3105+
Finally, ``whis`` can be the string ``'range'`` to force the
3106+
whiskers to the min and max of the data.
3107+
3108+
bootstrap : int, optional
3109+
Specifies whether to bootstrap the confidence intervals
3110+
around the median for notched boxplots. If `bootstrap` is None,
3111+
no bootstrapping is performed, and notches are calculated
3112+
using a Gaussian-based asymptotic approximation (see McGill,
3113+
R., Tukey, J.W., and Larsen, W.A., 1978, and Kendall and
3114+
Stuart, 1967). Otherwise, bootstrap specifies the number of
3115+
times to bootstrap the median to determine its 95%
3116+
confidence intervals. Values between 1000 and 10000 are
3117+
recommended.
3118+
3119+
usermedians : array-like, optional
3120+
An array or sequence whose first dimension (or length) is
3121+
compatible with ``x``. This overrides the medians computed
3122+
by matplotlib for each element of ``usermedians`` that is not
3123+
`None`. When an element of ``usermedians`` is None, the median
3124+
will be computed by matplotlib as normal.
3125+
3126+
conf_intervals : array-like, optional
3127+
Array or sequence whose first dimension (or length) is
3128+
compatible with ``x`` and whose second dimension is 2. When
3129+
the an element of ``conf_intervals`` is not None, the
3130+
notch locations computed by matplotlib are overridden
3131+
(provided ``notch`` is `True`). When an element of
3132+
``conf_intervals`` is `None`, the notches are computed by the
3133+
method specified by the other kwargs (e.g., ``bootstrap``).
3134+
3135+
positions : array-like, optional
3136+
Sets the positions of the boxes. The ticks and limits are
3137+
automatically set to match the positions. Defaults to
3138+
`range(1, N+1)` where N is the number of boxes to be drawn.
3139+
3140+
widths : scalar or array-like
3141+
Sets the width of each box either with a scalar or a
3142+
sequence. The default is 0.5, or ``0.15*(distance between
3143+
extreme positions)``, if that is smaller.
3144+
3145+
patch_artist : bool, optional (False)
3146+
If `False` produces boxes with the Line2D artist. Otherwise,
3147+
boxes and drawn with Patch artists.
3148+
3149+
labels : sequence, optional
3150+
Labels for each dataset. Length must be compatible with
3151+
dimensions of ``x``.
3152+
3153+
manage_xticks : bool, optional (True)
3154+
If the function should adjust the xlim and xtick locations.
31663155
3167-
capprops : dict or None (default)
3168-
If provided, will set the plotting style of the caps
3156+
autorange : bool, optional (False)
3157+
When `True` and the data are distributed such that the 25th and
3158+
75th percentiles are equal, ``whis`` is set to ``'range'`` such
3159+
that the whisker ends are at the minimum and maximum of the
3160+
data.
3161+
3162+
meanline : bool, optional (False)
3163+
If `True` (and ``showmeans`` is `True`), will try to render
3164+
the mean as a line spanning the full width of the box
3165+
according to ``meanprops`` (see below). Not recommended if
3166+
``shownotches`` is also True. Otherwise, means will be shown
3167+
as points.
3168+
3169+
Additional Options
3170+
---------------------
3171+
The following boolean options toggle the drawing of individual
3172+
components of the boxplots:
3173+
- showcaps: the caps on the ends of whiskers
3174+
(default is True)
3175+
- showbox: the central box (default is True)
3176+
- showfliers: the outliers beyond the caps (default is True)
3177+
- showmeans: the arithmetic means (default is False)
3178+
3179+
The remaining options can accept dictionaries that specify the
3180+
style of the individual artists:
3181+
- capprops
3182+
- boxprops
3183+
- whiskerprops
3184+
- flierprops
3185+
- medianprops
3186+
- meanprops
31693187
3170-
flierprops : dict or None (default)
3171-
If provided, will set the plotting style of the fliers
3188+
Returns
3189+
-------
3190+
result : dict
3191+
A dictionary mapping each component of the boxplot to a list
3192+
of the :class:`matplotlib.lines.Line2D` instances
3193+
created. That dictionary has the following keys (assuming
3194+
vertical boxplots):
31723195
3173-
medianprops : dict or None (default)
3174-
If provided, will set the plotting style of the medians
3196+
- ``boxes``: the main body of the boxplot showing the
3197+
quartiles and the median's confidence intervals if
3198+
enabled.
31753199
3176-
meanprops : dict or None (default)
3177-
If provided, will set the plotting style of the means
3200+
- ``medians``: horizontal lines at the median of each box.
31783201
3179-
meanline : bool, default = False
3180-
If True (and *showmeans* is True), will try to render the mean
3181-
as a line spanning the full width of the box according to
3182-
*meanprops*. Not recommended if *shownotches* is also True.
3183-
Otherwise, means will be shown as points.
3202+
- ``whiskers``: the vertical lines extending to the most
3203+
extreme, non-outlier data points.
31843204
3185-
manage_xticks : bool, default = True
3186-
If the function should adjust the xlim and xtick locations.
3205+
- ``caps``: the horizontal lines at the ends of the
3206+
whiskers.
31873207
3188-
Returns
3189-
-------
3208+
- ``fliers``: points representing data that extend beyond
3209+
the whiskers (fliers).
31903210
3191-
result : dict
3192-
A dictionary mapping each component of the boxplot
3193-
to a list of the :class:`matplotlib.lines.Line2D`
3194-
instances created. That dictionary has the following keys
3195-
(assuming vertical boxplots):
3196-
3197-
- boxes: the main body of the boxplot showing the quartiles
3198-
and the median's confidence intervals if enabled.
3199-
- medians: horizonal lines at the median of each box.
3200-
- whiskers: the vertical lines extending to the most extreme,
3201-
n-outlier data points.
3202-
- caps: the horizontal lines at the ends of the whiskers.
3203-
- fliers: points representing data that extend beyond the
3204-
whiskers (outliers).
3205-
- means: points or lines representing the means.
3211+
- ``means``: points or lines representing the means.
32063212
32073213
Examples
32083214
--------
3209-
32103215
.. plot:: mpl_examples/statistics/boxplot_demo.py
3216+
32113217
"""
3218+
32123219
# If defined in matplotlibrc, apply the value from rc file
32133220
# Overridden if argument is passed
32143221
if whis is None:
32153222
whis = rcParams['boxplot.whiskers']
32163223
if bootstrap is None:
32173224
bootstrap = rcParams['boxplot.bootstrap']
32183225
bxpstats = cbook.boxplot_stats(x, whis=whis, bootstrap=bootstrap,
3219-
labels=labels)
3226+
labels=labels, autorange=autorange)
32203227
if notch is None:
32213228
notch = rcParams['boxplot.notch']
32223229
if vert is None:
@@ -3462,10 +3469,10 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
34623469
quartiles and the median's confidence intervals if
34633470
enabled.
34643471
3465-
- ``medians``: horizonal lines at the median of each box.
3472+
- ``medians``: horizontal lines at the median of each box.
34663473
34673474
- ``whiskers``: the vertical lines extending to the most
3468-
extreme, n-outlier data points.
3475+
extreme, non-outlier data points.
34693476
34703477
- ``caps``: the horizontal lines at the ends of the
34713478
whiskers.

0 commit comments

Comments
 (0)
0