.. _pyplot-tutorial:
***************
Pyplot tutorial
***************
:mod:`matplotlib.pyplot` is a collection of command style functions
that make matplotlib work like MATLAB.
Each ``pyplot`` function makes
some change to a figure: e.g., creates a figure, creates a plotting area
in a figure, plots some lines in a plotting area, decorates the plot
with labels, etc. In :mod:`matplotlib.pyplot` various states are preserved
across function calls, so that it keeps track of things like
the current figure and plotting area, and the plotting
functions are directed to the current axes (please note that "axes" here
and in most places in the documentation refers to the *axes*
`part of a figure `__
and not the strict mathematical term for more than one axis).
.. plot:: pyplots/pyplot_simple.py
:include-source:
You may be wondering why the x-axis ranges from 0-3 and the y-axis
from 1-4. If you provide a single list or array to the
:func:`~matplotlib.pyplot.plot` command, matplotlib assumes it is a
sequence of y values, and automatically generates the x values for
you. Since python ranges start with 0, the default x vector has the
same length as y but starts with 0. Hence the x data are
``[0,1,2,3]``.
:func:`~matplotlib.pyplot.plot` is a versatile command, and will take
an arbitrary number of arguments. For example, to plot x versus y,
you can issue the command::
plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
For every x, y pair of arguments, there is an optional third argument
which is the format string that indicates the color and line type of
the plot. The letters and symbols of the format string are from
MATLAB, and you concatenate a color string with a line style string.
The default format string is 'b-', which is a solid blue line. For
example, to plot the above with red circles, you would issue
.. plot:: pyplots/pyplot_formatstr.py
:include-source:
See the :func:`~matplotlib.pyplot.plot` documentation for a complete
list of line styles and format strings. The
:func:`~matplotlib.pyplot.axis` command in the example above takes a
list of ``[xmin, xmax, ymin, ymax]`` and specifies the viewport of the
axes.
If matplotlib were limited to working with lists, it would be fairly
useless for numeric processing. Generally, you will use `numpy
`_ arrays. In fact, all sequences are
converted to numpy arrays internally. The example below illustrates a
plotting several lines with different format styles in one command
using arrays.
.. plot:: pyplots/pyplot_three.py
:include-source:
.. _controlling-line-properties:
Controlling line properties
===========================
Lines have many attributes that you can set: linewidth, dash style,
antialiased, etc; see :class:`matplotlib.lines.Line2D`. There are
several ways to set line properties
* Use keyword args::
plt.plot(x, y, linewidth=2.0)
* Use the setter methods of a ``Line2D`` instance. ``plot`` returns a list
of ``Line2D`` objects; e.g., ``line1, line2 = plot(x1, y1, x2, y2)``. In the code
below we will suppose that we have only
one line so that the list returned is of length 1. We use tuple unpacking with
``line,`` to get the first element of that list::
line, = plt.plot(x, y, '-')
line.set_antialiased(False) # turn off antialising
* Use the :func:`~matplotlib.pyplot.setp` command. The example below
uses a MATLAB-style command to set multiple properties
on a list of lines. ``setp`` works transparently with a list of objects
or a single object. You can either use python keyword arguments or
MATLAB-style string/value pairs::
lines = plt.plot(x1, y1, x2, y2)
# use keyword args
plt.setp(lines, color='r', linewidth=2.0)
# or MATLAB style string value pairs
plt.setp(lines, 'color', 'r', 'linewidth', 2.0)
Here are the available :class:`~matplotlib.lines.Line2D` properties.
====================== ==================================================
Property Value Type
====================== ==================================================
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
clip_path a Path instance and a Transform instance, a Patch
color or c any matplotlib color
contains the hit testing function
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 matplotlib.figure.Figure instance
label any string
linestyle or ls [ ``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'steps'`` | ...]
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
markevery [ None | integer | (startind, stride) ]
picker used in interactive line selection
pickradius the line pick selection radius
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
====================== ==================================================
To get a list of settable line properties, call the
:func:`~matplotlib.pyplot.setp` function with a line or lines
as argument
.. sourcecode:: ipython
In [69]: lines = plt.plot([1, 2, 3])
In [70]: plt.setp(lines)
alpha: float
animated: [True | False]
antialiased or aa: [True | False]
...snip
.. _multiple-figs-axes:
Working with multiple figures and axes
======================================
MATLAB, and :mod:`~matplotlib.pyplot`, have the concept of the current
figure and the current axes. All plotting commands apply to the
current axes. The function :func:`~matplotlib.pyplot.gca` returns the
current axes (a :class:`matplotlib.axes.Axes` instance), and
:func:`~matplotlib.pyplot.gcf` returns the current figure
(:class:`matplotlib.figure.Figure` instance). Normally, you don't have
to worry about this, because it is all taken care of behind the
scenes. Below is a script to create two subplots.
.. plot:: pyplots/pyplot_two_subplots.py
:include-source:
The :func:`~matplotlib.pyplot.figure` command here is optional because
``figure(1)`` will be created by default, just as a ``subplot(111)``
will be created by default if you don't manually specify any axes. The
:func:`~matplotlib.pyplot.subplot` command specifies ``numrows,
numcols, fignum`` where ``fignum`` ranges from 1 to
``numrows*numcols``. The commas in the ``subplot`` command are
optional if ``numrows*numcols