|
New release
|
|
matplotlib 0.98.3 is a major release which requires python2.4 or 2.5 and numpy 1.1. It contains significant improvements and may require some advanced users to update their code; see migration and API_CHANGES. We are supporting a maintenance branch of the older code available at matplotlib 0.91.4. Basemap users see basemap-readme for upgrade instructions |
|
Donate
|
|
Help support matplotlib development by donating to fund developer sprints and other matplotlib development costs. |
|
|
|
Functions |
| | |
- acorr(*args, **kwargs)
- call signature::
acorr(x, normed=False, detrend=mlab.detrend_none, usevlines=False,
maxlags=None, **kwargs)
Plot the autocorrelation of *x*. If *normed* = *True*,
normalize the data but the autocorrelation at 0-th lag. *x* is
detrended by the *detrend* callable (default no normalization).
Data are plotted as ``plot(lags, c, **kwargs)``
Return value is a tuple (*lags*, *c*, *line*) where:
- *lags* are a length 2*maxlags+1 lag vector
- *c* is the 2*maxlags+1 auto correlation vector
- *line* is a :class:`~matplotlib.lines.Line2D` instance
returned by :meth:`plot`
The default *linestyle* is None and the default *marker* is
``'o'``, though these can be overridden with keyword args.
The cross correlation is performed with :func:`numpy.correlate` with
*mode* = 2.
If *usevlines* is *True*, :meth:`~matplotlib.axes.Axes.vlines`
rather than :meth:`~matplotlib.axes.Axes.plot` is used to draw
vertical lines from the origin to the acorr. Otherwise, the
plot style is determined by the kwargs, which are
:class:`~matplotlib.lines.Line2D` properties. The return
value is a tuple (*lags*, *c*, *linecol*, *b*) where
- *linecol* is the
:class:`~matplotlib.collections.LineCollection`
- *b* is the *x*-axis.
*maxlags* is a positive integer detailing the number of lags
to show. The default value of *None* will return all
``(2*len(x)-1)`` lags.
See the respective :meth:`~matplotlib.axes.Axes.plot` or
:meth:`~matplotlib.axes.Axes.vlines` functions for
documentation on valid kwargs.
**Example:**
:func:`~matplotlib.pyplot.xcorr` above, and
:func:`~matplotlib.pyplot.acorr` below.
**Example:**
.. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py
Additional kwargs: hold = [True|False] overrides default hold state
- annotate(*args, **kwargs)
- call signature::
annotate(s, xy, xytext=None, xycoords='data',
textcoords='data', arrowprops=None, **kwargs)
Keyword arguments:
Annotate the *x*, *y* point *xy* with text *s* at *x*, *y*
location *xytext*. (If *xytext* = *None*, defaults to *xy*,
and if *textcoords* = *None*, defaults to *xycoords*).
*arrowprops*, if not *None*, is a dictionary of line properties
(see :class:`matplotlib.lines.Line2D`) for the arrow that connects
annotation to the point. Valid keys are
========= ===========================================================
Key Description
========= ===========================================================
width the width of the arrow in points
frac the fraction of the arrow length occupied by the head
headwidth the width of the base of the arrow head in points
shrink oftentimes it is convenient to have the arrowtip
and base a bit away from the text and point being
annotated. If *d* is the distance between the text and
annotated point, shrink will shorten the arrow so the tip
and base are shink percent of the distance *d* away from the
endpoints. ie, ``shrink=0.05 is 5%``
? any key for :class:`matplotlib.patches.polygon`
========= ===========================================================
*xycoords* and *textcoords* are strings that indicate the
coordinates of *xy* and *xytext*.
================= ===================================================
Property Description
================= ===================================================
'figure points' points from the lower left corner of the figure
'figure pixels' pixels from the lower left corner of the figure
'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
'axes points' points from lower left corner of axes
'axes pixels' pixels from lower left corner of axes
'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
'data' use the coordinate system of the object being
annotated (default)
'offset points' Specify an offset (in points) from the *xy* value
'polar' you can specify *theta*, *r* for the annotation,
even in cartesian plots. Note that if you
are using a polar axes, you do not need
to specify polar for the coordinate
system since that is the native "data" coordinate
system.
================= ===================================================
If a 'points' or 'pixels' option is specified, values will be
added to the bottom-left and if negative, values will be
subtracted from the top-right. Eg::
# 10 points to the right of the left border of the axes and
# 5 points below the top border
xy=(10,-5), xycoords='axes points'
Additional kwargs are Text properties:
========================= =====================================================================
Property Description
========================= =====================================================================
alpha float
animated [True | False]
axes an axes instance
backgroundcolor any matplotlib color
bbox rectangle prop dict plus key 'pad' which is a pad in points
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
color any matplotlib color
contains unknown
family [ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
figure a :class:`matplotlib.figure.Figure` instance
fontproperties a matplotlib.font_manager.FontProperties instance
horizontalalignment or ha [ 'center' | 'right' | 'left' ]
label any string
linespacing float
lod [True | False]
multialignment ['left' | 'right' | 'center' ]
name or fontname string eg, ['Sans' | 'Courier' | 'Helvetica' ...]
picker [None|float|boolean|callable]
position (x,y)
rotation [ angle in degrees 'vertical' | 'horizontal'
size or fontsize [ size in points | relative size eg 'smaller', 'x-large' ]
style or fontstyle [ 'normal' | 'italic' | 'oblique']
text string or anything printable with '%s' conversion
transform unknown
variant [ 'normal' | 'small-caps' ]
verticalalignment or va [ 'center' | 'top' | 'bottom' | 'baseline' ]
visible [True | False]
weight or fontweight [ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' | 'ultralight']
x float
y float
zorder any number
========================= =====================================================================
- arrow(*args, **kwargs)
- call signature::
arrow(x, y, dx, dy, **kwargs)
Draws arrow on specified axis from (*x*, *y*) to (*x* + *dx*,
*y* + *dy*).
Optional kwargs control the arrow properties:
=========== ===========================================================
Property Description
=========== ===========================================================
aa [True | False] or None for default
alpha float
animated [True | False]
antialiased [True | False] or None for default
axes an axes instance
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
contains unknown
ec mpl color spec, or None for default, or 'none' for no color
edgecolor mpl color spec, or None for default, or 'none' for no color
facecolor mpl color spec, or None for default, or 'none' for no color
fc mpl color spec, or None for default, or 'none' for no color
figure a :class:`matplotlib.figure.Figure` instance
fill [True | False]
hatch unknown
label any string
linestyle ['solid' | 'dashed' | 'dashdot' | 'dotted']
linewidth float or None for default
lod [True | False]
ls ['solid' | 'dashed' | 'dashdot' | 'dotted']
lw float or None for default
picker [None|float|boolean|callable]
transform unknown
visible [True | False]
zorder any number
=========== ===========================================================
**Example:**
.. plot:: ../mpl_examples/pylab_examples/arrow_demo.py
Additional kwargs: hold = [True|False] overrides default hold state
- autumn()
- Set the default colormap to *autumn* and apply to current image if any.
See :func:`colormaps` for more information.
- axes(*args, **kwargs)
- Add an axes at position rect specified by:
- ``axes()`` by itself creates a default full ``subplot(111)`` window axis.
- ``axes(rect, axisbg='w')`` where *rect* = [left, bottom, width,
height] in normalized (0, 1) units. *axisbg* is the background
color for the axis, default white.
- ``axes(h)`` where *h* is an axes instance makes *h* the current
axis. An :class:`~matplotlib.axes.Axes` instance is returned.
======= ============ ================================================
kwarg Accepts Desctiption
======= ============ ================================================
axisbg color the axes background color
frameon [True|False] display the frame?
sharex otherax current axes shares xaxis attribute with otherax
sharey otherax current axes shares yaxis attribute with otherax
polar [True|False] use a polar axes?
======= ============ ================================================
Examples:
* :file:`examples/pylab_examples/axes_demo.py` places custom axes.
* :file:`examples/pylab_examples/shared_axis_demo.py` uses
*sharex* and *sharey*.
- axhline(*args, **kwargs)
- call signature::
axhline(y=0, xmin=0, xmax=1, **kwargs)
Axis Horizontal Line
Draw a horizontal line at *y* from *xmin* to *xmax*. With the
default values of *xmin* = 0 and *xmax* = 1, this line will
always span the horizontal extent of the axes, regardless of
the xlim settings, even if you change them, eg. with the
:meth:`set_xlim` command. That is, the horizontal extent is
in axes coords: 0=left, 0.5=middle, 1.0=right but the *y*
location is in data coordinates.
Return value is the :class:`~matplotlib.lines.Line2D`
instance. kwargs are the same as kwargs to plot, and can be
used to control the line properties. Eg.,
* draw a thick red hline at *y* = 0 that spans the xrange
>>> axhline(linewidth=4, color='r')
* draw a default hline at *y* = 1 that spans the xrange
>>> axhline(y=1)
* draw a default hline at *y* = .5 that spans the the middle half of
the xrange
>>> axhline(y=.5, xmin=0.25, xmax=0.75)
Valid kwargs are :class:`~matplotlib.lines.Line2D` properties:
====================== ====================================================================================================
Property Description
====================== ====================================================================================================
alpha float
animated [True | False]
antialiased or aa [True | False]
axes unknown
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
color or c any matplotlib color
contains unknown
dash_capstyle ['butt' | 'round' | 'projecting']
dash_joinstyle ['miter' | 'round' | 'bevel']
dashes sequence of on/off ink in points
data (np.array xdata, np.array ydata)
figure a :class:`matplotlib.figure.Figure` instance
label any string
linestyle or ls [ '-' | '--' | '-.' | ':' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' | 'None' | ' ' | '' ]
linewidth or lw float value in points
lod [True | False]
marker [ '+' | ',' | '.' | '1' | '2' | '3' | '4'
markeredgecolor or mec any matplotlib color
markeredgewidth or mew float value in points
markerfacecolor or mfc any matplotlib color
markersize or ms float
picker unknown
pickradius unknown
solid_capstyle ['butt' | 'round' | 'projecting']
solid_joinstyle ['miter' | 'round' | 'bevel']
transform a matplotlib.transforms.Transform instance
visible [True | False]
xdata np.array
ydata np.array
zorder any number
====================== ====================================================================================================
See :meth:`axhspan` for example plot and source code
Additional kwargs: hold = [True|False] overrides default hold state
- axhspan(*args, **kwargs)
- call signature::
axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs)
Axis Horizontal Span.
*y* coords are in data units and *x* coords are in axes (relative
0-1) units.
Draw a horizontal span (rectangle) from *ymin* to *ymax*.
With the default values of *xmin* = 0 and *xmax* = 1, this
always span the xrange, regardless of the xlim settings, even
if you change them, eg. with the :meth:`set_xlim` command.
That is, the horizontal extent is in axes coords: 0=left,
0.5=middle, 1.0=right but the *y* location is in data
coordinates.
Return value is a :class:`matplotlib.patches.Polygon`
instance.
Examples:
* draw a gray rectangle from *y* = 0.25-0.75 that spans the
horizontal extent of the axes
>>> axhspan(0.25, 0.75, facecolor='0.5', alpha=0.5)
Valid kwargs are :class:`~matplotlib.patches.Polygon` properties:
=========== ===========================================================
Property Description
=========== ===========================================================
aa [True | False] or None for default
alpha float
animated [True | False]
antialiased [True | False] or None for default
axes an axes instance
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
contains unknown
ec mpl color spec, or None for default, or 'none' for no color
edgecolor mpl color spec, or None for default, or 'none' for no color
facecolor mpl color spec, or None for default, or 'none' for no color
fc mpl color spec, or None for default, or 'none' for no color
figure a :class:`matplotlib.figure.Figure` instance
fill [True | False]
hatch unknown
label any string
linestyle ['solid' | 'dashed' | 'dashdot' | 'dotted']
linewidth float or None for default
lod [True | False]
ls ['solid' | 'dashed' | 'dashdot' | 'dotted']
lw float or None for default
picker [None|float|boolean|callable]
transform unknown
visible [True | False]
zorder any number
=========== ===========================================================
**Example:**
.. plot:: ../mpl_examples/pylab_examples/axhspan_demo.py
Additional kwargs: hold = [True|False] overrides default hold state
- axis(*v, **kwargs)
- Set/Get the axis properties:
>>> axis()
returns the current axes limits ``[xmin, xmax, ymin, ymax]``.
>>> axis(v)
sets the min and max of the x and y axes, with
``v = [xmin, xmax, ymin, ymax]``.
>>> axis('off')
turns off the axis lines and labels.
>>> axis('equal')
changes limits of *x* or *y* axis so that equal increments of *x*
and *y* have the same length; a circle is circular.
>>> axis('scaled')
achieves the same result by changing the dimensions of the plot box instead
of the axis data limits.
>>> axis('tight')
changes *x* and *y* axis limits such that all data is shown. If
all data is already shown, it will move it to the center of the
figure without modifying (*xmax* - *xmin*) or (*ymax* -
*ymin*). Note this is slightly different than in matlab.
>>> axis('image')
is 'scaled' with the axis limits equal to the data limits.
>>> axis('auto')
and
>>> axis('normal')
are deprecated. They restore default behavior; axis limits are automatically
scaled to make the data fit comfortably within the plot box.
if ``len(*v)==0``, you can pass in *xmin*, *xmax*, *ymin*, *ymax*
as kwargs selectively to alter just those limits without changing
the others. See :func:`xlim` and :func:`ylim` for more information
The xmin, xmax, ymin, ymax tuple is returned
- axvline(*args, **kwargs)
- call signature::
axvline(x=0, ymin=0, ymax=1, **kwargs)
Axis Vertical Line
Draw a vertical line at *x* from *ymin* to *ymax*. With the
default values of *ymin* = 0 and *ymax* = 1, this line will
always span the vertical extent of the axes, regardless of the
xlim settings, even if you change them, eg. with the
:meth:`set_xlim` command. That is, the vertical extent is in
axes coords: 0=bottom, 0.5=middle, 1.0=top but the *x* location
is in data coordinates.
Return value is the :class:`~matplotlib.lines.Line2D`
instance. kwargs are the same as kwargs to plot, and can be
used to control the line properties. Eg.,
* draw a thick red vline at *x* = 0 that spans the yrange
>>> axvline(linewidth=4, color='r')
* draw a default vline at *x* = 1 that spans the yrange
>>> axvline(x=1)
* draw a default vline at *x* = .5 that spans the the middle half of
the yrange
>>> axvline(x=.5, ymin=0.25, ymax=0.75)
Valid kwargs are :class:`~matplotlib.lines.Line2D` properties:
====================== ====================================================================================================
Property Description
====================== ====================================================================================================
alpha float
animated [True | False]
antialiased or aa [True | False]
axes unknown
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
color or c any matplotlib color
contains unknown
dash_capstyle ['butt' | 'round' | 'projecting']
dash_joinstyle ['miter' | 'round' | 'bevel']
dashes sequence of on/off ink in points
data (np.array xdata, np.array ydata)
figure a :class:`matplotlib.figure.Figure` instance
label any string
linestyle or ls [ '-' | '--' | '-.' | ':' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' | 'None' | ' ' | '' ]
linewidth or lw float value in points
lod [True | False]
marker [ '+' | ',' | '.' | '1' | '2' | '3' | '4'
markeredgecolor or mec any matplotlib color
markeredgewidth or mew float value in points
markerfacecolor or mfc any matplotlib color
markersize or ms float
picker unknown
pickradius unknown
solid_capstyle ['butt' | 'round' | 'projecting']
solid_joinstyle ['miter' | 'round' | 'bevel']
transform a matplotlib.transforms.Transform instance
visible [True | False]
xdata np.array
ydata np.array
zorder any number
====================== ====================================================================================================
See :meth:`axhspan` for example plot and source code
Additional kwargs: hold = [True|False] overrides default hold state
- axvspan(*args, **kwargs)
- call signature::
axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs)
Axis Vertical Span.
*x* coords are in data units and *y* coords are in axes (relative
0-1) units.
Draw a vertical span (rectangle) from *xmin* to *xmax*. With
the default values of *ymin* = 0 and *ymax* = 1, this always
span the yrange, regardless of the ylim settings, even if you
change them, eg. with the :meth:`set_ylim` command. That is,
the vertical extent is in axes coords: 0=bottom, 0.5=middle,
1.0=top but the *y* location is in data coordinates.
Return value is the :class:`matplotlib.patches.Polygon`
instance.
Examples:
* draw a vertical green translucent rectangle from x=1.25 to 1.55 that
spans the yrange of the axes
>>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
Valid kwargs are :class:`~matplotlib.patches.Polygon`
properties:
=========== ===========================================================
Property Description
=========== ===========================================================
aa [True | False] or None for default
alpha float
animated [True | False]
antialiased [True | False] or None for default
axes an axes instance
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
contains unknown
ec mpl color spec, or None for default, or 'none' for no color
edgecolor mpl color spec, or None for default, or 'none' for no color
facecolor mpl color spec, or None for default, or 'none' for no color
fc mpl color spec, or None for default, or 'none' for no color
figure a :class:`matplotlib.figure.Figure` instance
fill [True | False]
hatch unknown
label any string
linestyle ['solid' | 'dashed' | 'dashdot' | 'dotted']
linewidth float or None for default
lod [True | False]
ls ['solid' | 'dashed' | 'dashdot' | 'dotted']
lw float or None for default
picker [None|float|boolean|callable]
transform unknown
visible [True | False]
zorder any number
=========== ===========================================================
See :meth:`axhspan` for example plot and source code
Additional kwargs: hold = [True|False] overrides default hold state
- bar(*args, **kwargs)
- call signature::
bar(left, height, width=0.8, bottom=0,
color=None, edgecolor=None, linewidth=None,
yerr=None, xerr=None, ecolor=None, capsize=3,
align='edge', orientation='vertical', log=False)
Make a bar plot with rectangles bounded by:
*left*, *left* + *width*, *bottom*, *bottom* + *height*
(left, right, bottom and top edges)
*left*, *height*, *width*, and *bottom* can be either scalars
or sequences
Return value is a list of
:class:`matplotlib.patches.Rectangle` instances.
Required arguments:
======== ===============================================
Argument Description
======== ===============================================
*left* the x coordinates of the left sides of the bars
*height* the heights of the bars
======== ===============================================
Optional keyword arguments:
=============== ==========================================
Keyword Description
=============== ==========================================
*width* the widths of the bars
*bottom* the y coordinates of the bottom edges of
the bars
*color* the colors of the bars
*edgecolor* the colors of the bar edges
*linewidth* width of bar edges; None means use default
linewidth; 0 means don't draw edges.
*xerr* if not None, will be used to generate
errorbars on the bar chart
*yerr* if not None, will be used to generate
errorbars on the bar chart
*ecolor* specifies the color of any errorbar
*capsize* (default 3) determines the length in
points of the error bar caps
*align* 'edge' (default) | 'center'
*orientation* 'vertical' | 'horizontal'
*log* [False|True] False (default) leaves the
orientation axis as-is; True sets it to
log scale
=============== ==========================================
For vertical bars, *align* = 'edge' aligns bars by their left
edges in left, while *align* = 'center' interprets these
values as the *x* coordinates of the bar centers. For
horizontal bars, *align* = 'edge' aligns bars by their bottom
edges in bottom, while *align* = 'center' interprets these
values as the *y* coordinates of the bar centers.
The optional arguments *color*, *edgecolor*, *linewidth*,
*xerr*, and *yerr* can be either scalars or sequences of
length equal to the number of bars. This enables you to use
bar as the basis for stacked bar charts, or candlestick plots.
Other optional kwargs:
=========== ===========================================================
Property Description
=========== ===========================================================
aa [True | False] or None for default
alpha float
animated [True | False]
antialiased [True | False] or None for default
axes an axes instance
clip_box a :class:`matplotlib.transform.Bbox` instance
clip_on [True | False]
clip_path a :class:`~matplotlib.path.Path` instance and a
contains unknown
ec mpl color spec, or None for default, or 'none' for no color
edgecolor mpl color spec, or None for default, or 'none' for no color
facecolor mpl color spec, or None for default, or 'none' for no color
fc mpl color spec, or None for default, or 'none' for no color
figure a :class:`matplotlib.figure.Figure` instance
fill [True | False]
hatch unknown
label any string
linestyle ['solid' | 'dashed' | 'dashdot' | 'dotted']
linewidth float or None for default
lod [True | False]
ls ['solid' | 'dashed' | 'dashdot' | 'dotted']
lw float or None for default
picker [None|float|boolean|callable]
transform unknown
visible [True | False]
zorder any number
=========== ===========================================================
**Example:** A stacked bar chart.
.. plot:: ../mpl_examples/pylab_examples/bar_stacked.py
Additional kwargs: hold = [True|False] overrides default hold state
- barbs(*args, **kwargs)
- Plot a 2-D field of barbs.
call signatures::
barb(U, V, **kw)
barb(U, V, C, **kw)
barb(X, Y, U, V, **kw)
barb(X, Y, U, V, C, **kw)
Arguments:
*X*, *Y*:
The x and y coordinates of the barb locations
(default is head of barb; see *pivot* kwarg)
*U*, *V*:
give the *x* and *y* components of the barb shaft
*C*:
an optional array used to map colors to the barbs
All arguments may be 1-D or 2-D arrays or sequences. If *X* and *Y*
are absent, they will be generated as a uniform grid. If *U* and *V*
are 2-D arrays but *X* and *Y* are 1-D, and if len(*X*) and len(*Y*)
match the column and row dimensions of *U*, then *X* and *Y* will be
expanded with :func:`numpy.meshgrid`.
*U*, *V*, *C* may be masked arrays, but masked *X*, *Y* are not
supported at present.
Keyword arguments:
*length*:
Length of the barb in points; the other parts of the barb
are scaled against this.
Default is 9
*pivot*: [ 'tip' | 'middle' ]
The part of the arrow that is at the grid point; the arrow
| |
