Module « matplotlib.pyplot »

Fonction boxplot - module matplotlib.pyplot

Signature de la fonction boxplot

def boxplot(x, notch=None, sym=None, vert=None, whis=None, positions=None, widths=None, patch_artist=None, bootstrap=None, usermedians=None, conf_intervals=None, meanline=None, showmeans=None, showcaps=None, showbox=None, showfliers=None, boxprops=None, labels=None, flierprops=None, medianprops=None, meanprops=None, capprops=None, whiskerprops=None, manage_ticks=True, autorange=False, zorder=None, *, data=None) 

Description

boxplot.__doc__

Make a box and whisker plot.

Make a box and whisker plot for each column of *x* or each
vector in sequence *x*.  The box extends from the lower to
upper quartile values of the data, with a line at the median.
The whiskers extend from the box to show the range of the
data.  Flier points are those past the end of the whiskers.

Parameters
----------
x : Array or a sequence of vectors.
    The input data.

notch : bool, default: False
    Whether to draw a notched box plot (`True`), or a rectangular box
    plot (`False`).  The notches represent the confidence interval (CI)
    around the median.  The documentation for *bootstrap* describes how
    the locations of the notches are computed by default, but their
    locations may also be overridden by setting the *conf_intervals*
    parameter.

    .. note::

        In cases where the values of the CI are less than the
        lower quartile or greater than the upper quartile, the
        notches will extend beyond the box, giving it a
        distinctive "flipped" appearance. This is expected
        behavior and consistent with other statistical
        visualization packages.

sym : str, optional
    The default symbol for flier points.  An empty string ('') hides
    the fliers.  If `None`, then the fliers default to 'b+'.  More
    control is provided by the *flierprops* parameter.

vert : bool, default: True
    If `True`, draws vertical boxes.
    If `False`, draw horizontal boxes.

whis : float or (float, float), default: 1.5
    The position of the whiskers.

    If a float, the lower whisker is at the lowest datum above
    ``Q1 - whis*(Q3-Q1)``, and the upper whisker at the highest datum
    below ``Q3 + whis*(Q3-Q1)``, where Q1 and Q3 are the first and
    third quartiles.  The default value of ``whis = 1.5`` corresponds
    to Tukey's original definition of boxplots.

    If a pair of floats, they indicate the percentiles at which to
    draw the whiskers (e.g., (5, 95)).  In particular, setting this to
    (0, 100) results in whiskers covering the whole range of the data.

    In the edge case where ``Q1 == Q3``, *whis* is automatically set
    to (0, 100) (cover the whole range of the data) if *autorange* is
    True.

    Beyond the whiskers, data are considered outliers and are plotted
    as individual points.

bootstrap : int, optional
    Specifies whether to bootstrap the confidence intervals
    around the median for notched boxplots. If *bootstrap* is
    None, no bootstrapping is performed, and notches are
    calculated using a Gaussian-based asymptotic approximation
    (see McGill, R., Tukey, J.W., and Larsen, W.A., 1978, and
    Kendall and Stuart, 1967). Otherwise, bootstrap specifies
    the number of times to bootstrap the median to determine its
    95% confidence intervals. Values between 1000 and 10000 are
    recommended.

usermedians : 1D array-like, optional
    A 1D array-like of length ``len(x)``.  Each entry that is not
    `None` forces the value of the median for the corresponding
    dataset.  For entries that are `None`, the medians are computed
    by Matplotlib as normal.

conf_intervals : array-like, optional
    A 2D array-like of shape ``(len(x), 2)``.  Each entry that is not
    None forces the location of the corresponding notch (which is
    only drawn if *notch* is `True`).  For entries that are `None`,
    the notches are computed by the method specified by the other
    parameters (e.g., *bootstrap*).

positions : array-like, optional
    The positions of the boxes. The ticks and limits are
    automatically set to match the positions. Defaults to
    ``range(1, N+1)`` where N is the number of boxes to be drawn.

widths : float or array-like
    The widths of the boxes.  The default is 0.5, or ``0.15*(distance
    between extreme positions)``, if that is smaller.

patch_artist : bool, default: False
    If `False` produces boxes with the Line2D artist. Otherwise,
    boxes and drawn with Patch artists.

labels : sequence, optional
    Labels for each dataset (one per dataset).

manage_ticks : bool, default: True
    If True, the tick locations and labels will be adjusted to match
    the boxplot positions.

autorange : bool, default: False
    When `True` and the data are distributed such that the 25th and
    75th percentiles are equal, *whis* is set to (0, 100) such
    that the whisker ends are at the minimum and maximum of the data.

meanline : bool, default: False
    If `True` (and *showmeans* is `True`), will try to render the
    mean as a line spanning the full width of the box according to
    *meanprops* (see below).  Not recommended if *shownotches* is also
    True.  Otherwise, means will be shown as points.

zorder : float, default: ``Line2D.zorder = 2``
    The zorder of the boxplot.

Returns
-------
dict
  A dictionary mapping each component of the boxplot to a list
  of the `.Line2D` instances created. That dictionary has the
  following keys (assuming vertical boxplots):

  - ``boxes``: the main body of the boxplot showing the
    quartiles and the median's confidence intervals if
    enabled.

  - ``medians``: horizontal lines at the median of each box.

  - ``whiskers``: the vertical lines extending to the most
    extreme, non-outlier data points.

  - ``caps``: the horizontal lines at the ends of the
    whiskers.

  - ``fliers``: points representing data that extend beyond
    the whiskers (fliers).

  - ``means``: points or lines representing the means.

Other Parameters
----------------
showcaps : bool, default: True
    Show the caps on the ends of whiskers.
showbox : bool, default: True
    Show the central box.
showfliers : bool, default: True
    Show the outliers beyond the caps.
showmeans : bool, default: False
    Show the arithmetic means.
capprops : dict, default: None
    The style of the caps.
boxprops : dict, default: None
    The style of the box.
whiskerprops : dict, default: None
    The style of the whiskers.
flierprops : dict, default: None
    The style of the fliers.
medianprops : dict, default: None
    The style of the median.
meanprops : dict, default: None
    The style of the mean.

Notes
-----
Box plots provide insight into distribution properties of the data.
However, they can be challenging to interpret for the unfamiliar
reader. The figure below illustrates the different visual features of
a box plot.

.. image:: /_static/boxplot_explanation.png
   :alt: Illustration of box plot features
   :scale: 50 %

The whiskers mark the range of the non-outlier data. The most common
definition of non-outlier is ``[Q1 - 1.5xIQR, Q3 + 1.5xIQR]``, which
is also the default in this function. Other whisker meanings can be
applied via the *whis* parameter.

See `Box plot <https://en.wikipedia.org/wiki/Box_plot>`_ on Wikipedia
for further information.

Violin plots (`~.Axes.violinplot`) add even more detail about the
statistical distribution by plotting the kernel density estimation
(KDE) as an estimation of the probability density function.

.. note::
    In addition to the above described arguments, this function can take
    a *data* keyword argument. If such a *data* argument is given,
    every other argument can also be string ``s``, which is
    interpreted as ``data[s]`` (unless this raises an exception).

    Objects passed as **data** must support item access (``data[s]``) and
    membership test (``s in data``).