matplotlib.axes.Axes.violin#

Axes.violin(vpstats, positions=None, *, vert=None, orientation='vertical', widths=0.5, showmeans=False, showextrema=True, showmedians=False, side='both', facecolor=None, linecolor=None)[source]#

Draw a violin plot from pre-computed statistics.

Draw a violin plot for each column of vpstats. Each filled area extends to represent the entire data range, with optional lines at the mean, the median, the minimum, the maximum, and the quantiles values.

Parameters:

vpstatslist of dicts

A list of dictionaries containing stats for each violin plot. Required keys are:

• coords: A list of scalars containing the coordinates that the violin's kernel density estimate were evaluated at.

• vals: A list of scalars containing the values of the kernel density estimate at each of the coordinates given in coords.

• mean: The mean value for this violin's dataset.

• median: The median value for this violin's dataset.

• min: The minimum value for this violin's dataset.

• max: The maximum value for this violin's dataset.

Optional keys are:

• quantiles: A list of scalars containing the quantile values for this violin's dataset.

positionsarray-like, default: [1, 2, ..., n]

The positions of the violins; i.e. coordinates on the x-axis for vertical violins (or y-axis for horizontal violins).

vertbool, optional

Deprecated since version 3.10: Use orientation instead.

If this is given during the deprecation period, it overrides the orientation parameter.

If True, plots the violins vertically. If False, plots the violins horizontally.

orientation{'vertical', 'horizontal'}, default: 'vertical'

If 'horizontal', plots the violins horizontally. Otherwise, plots the violins vertically.

Added in version 3.10.

widthsfloat or array-like, default: 0.5

The maximum width of each violin in units of the positions axis. The default is 0.5, which is half available space when using default positions.

showmeansbool, default: False

Whether to show the mean with a line.

showextremabool, default: True

Whether to show extrema with a line.

showmediansbool, default: False

Whether to show the median with a line.

side{'both', 'low', 'high'}, default: 'both'

'both' plots standard violins. 'low'/'high' only plots the side below/above the positions value.

facecolorcolor or list of color, optional

If provided, will set the face color(s) of the violins.

Added in version 3.11.

For backward compatibility, if facecolor is not given, the body will get an Artist-level transparency alpha of 0.3, which will persist if you afterwards change the facecolor, e.g. via result['bodies'][0].set_facecolor('red'). If facecolor is given, there is no Artist-level transparency. To set transparency for facecolor or edgecolor use (color, alpha) tuples.

linecolorcolor or list of color, optional

If provided, will set the line color(s) of the violins (the horizontal and vertical spines and body edges).

Added in version 3.11.

Returns:

dict

A dictionary mapping each component of the violinplot to a list of the corresponding collection instances created. The dictionary has the following keys:

• bodies: A list of the PolyCollection instances containing the filled area of each violin.

• cmeans: A LineCollection instance that marks the mean values of each of the violin's distribution.

• cmins: A LineCollection instance that marks the bottom of each violin's distribution.

• cmaxes: A LineCollection instance that marks the top of each violin's distribution.

• cbars: A LineCollection instance that marks the centers of each violin's distribution.

• cmedians: A LineCollection instance that marks the median values of each of the violin's distribution.

• cquantiles: A LineCollection instance created to identify the quantiles values of each of the violin's distribution.

See also

violinplot

Draw a violin plot from data instead of pre-computed statistics.

cbook.violin_stats

Calculate a vpstats dictionary from data, suitable for passing to violin.

Notes

The following calls are identical

ax.violinplot()

and

from matplotlib.cbook import violin_stats

stats = violin_stats()
ax.violin(stats)

violin_stats gives you more control of the statistical calculations than violinplot.