Version 3.0.2
matplotlib
Fork me on GitHub

Table of Contents

matplotlib.pyplot.errorbar

matplotlib.pyplot.errorbar(x, y, yerr=None, xerr=None, fmt='', ecolor=None, elinewidth=None, capsize=None, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False, errorevery=1, capthick=None, *, data=None, **kwargs)[source]

Plot y versus x as lines and/or markers with attached errorbars.

x, y define the data locations, xerr, yerr define the errorbar sizes. By default, this draws the data markers/lines as well the errorbars. Use fmt='none' to draw errorbars without any data markers.

Parameters:
x, y : scalar or array-like

The data positions.

xerr, yerr : scalar or array-like, shape(N,) or shape(2,N), optional

The errorbar sizes:

  • scalar: Symmetric +/- values for all data points.
  • shape(N,): Symmetric +/-values for each data point.
  • shape(2,N): Separate - and + values for each bar. First row
    contains the lower errors, the second row contains the upper errors.
  • None: No errorbar.

Note that all error arrays should have positive values.

See Different ways of specifying error bars for an example on the usage of xerr and yerr.

fmt : plot format string, optional, default: ''

The format for the data points / data lines. See plot for details.

Use 'none' (case insensitive) to plot errorbars without any data markers.

ecolor : mpl color, optional, default: None

A matplotlib color arg which gives the color the errorbar lines. If None, use the color of the line connecting the markers.

elinewidth : scalar, optional, default: None

The linewidth of the errorbar lines. If None, the linewidth of the current style is used.

capsize : scalar, optional, default: None

The length of the error bar caps in points. If None, it will take the value from rcParams["errorbar.capsize"].

capthick : scalar, optional, default: None

An alias to the keyword argument markeredgewidth (a.k.a. mew). This setting is a more sensible name for the property that controls the thickness of the error bar cap in points. For backwards compatibility, if mew or markeredgewidth are given, then they will over-ride capthick. This may change in future releases.

barsabove : bool, optional, default: False

If True, will plot the errorbars above the plot symbols. Default is below.

lolims, uplims, xlolims, xuplims : bool, optional, default: None

These arguments can be used to indicate that a value gives only upper/lower limits. In that case a caret symbol is used to indicate this. lims-arguments may be of the same type as xerr and yerr. To use limits with inverted axes, set_xlim() or set_ylim() must be called before errorbar().

errorevery : positive integer, optional, default: 1

Subsamples the errorbars. e.g., if errorevery=5, errorbars for every 5-th datapoint will be plotted. The data plot itself still shows all data points.

Returns:
container : ErrorbarContainer

The container contains:

  • plotline: Line2D instance of x, y plot markers and/or line.
  • caplines: A tuple of Line2D instances of the error bar caps.
  • barlinecols: A tuple of LineCollection with the horizontal and vertical error ranges.
Other Parameters:
**kwargs :

All other keyword arguments are passed on to the plot command for the markers. For example, this code makes big red squares with thick green edges:

x,y,yerr = rand(3,10)
errorbar(x, y, yerr, marker='s', mfc='red',
         mec='green', ms=20, mew=4)

where mfc, mec, ms and mew are aliases for the longer property names, markerfacecolor, markeredgecolor, markersize and markeredgewidth.

Valid kwargs for the marker properties are Lines2D properties:

Property Description
agg_filter a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha float
animated bool
antialiased bool
clip_box Bbox
clip_on bool
clip_path [(Path, Transform) | Patch | None]
color color
contains callable
dash_capstyle {'butt', 'round', 'projecting'}
dash_joinstyle {'miter', 'round', 'bevel'}
dashes sequence of floats (on/off ink in points) or (None, None)
drawstyle {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}
figure Figure
fillstyle {'full', 'left', 'right', 'bottom', 'top', 'none'}
gid str
in_layout bool
label object
linestyle {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth float
marker unknown
markeredgecolor color
markeredgewidth float
markerfacecolor color
markerfacecoloralt color
markersize float
markevery unknown
path_effects AbstractPathEffect
picker float or callable[[Artist, Event], Tuple[bool, dict]]
pickradius float
rasterized bool or None
sketch_params (scale: float, length: float, randomness: float)
snap bool or None
solid_capstyle {'butt', 'round', 'projecting'}
solid_joinstyle {'miter', 'round', 'bevel'}
transform matplotlib.transforms.Transform
url str
visible bool
xdata 1D array
ydata 1D array
zorder float

Notes

Note

In addition to the above described arguments, this function can take a data keyword argument. If such a data argument is given, the following arguments are replaced by data[<arg>]:

  • All arguments with the following names: 'x', 'xerr', 'y', 'yerr'.

Objects passed as data must support item access (data[<arg>]) and membership test (<arg> in data).

Examples using matplotlib.pyplot.errorbar