For this recipe, we want to fire up IPython:

$ ipython

After this, we need to import the plotting functions right away:

from matplotlib.pylab import *

Start experimenting with various properties of axes. Just calling an empty axis() function will return the default values for the axis:

In [1]: axis()
Out[1]: (0.0, 1.0, 0.0, 1.0)

Note that if you are in interactive mode and are using a windowing backend, a figure with an empty axis will be displayed.

Here the values represent xmin, xmax, ymin, and ymax respectively. Similarly, we can set values for the x and y axes:

In [2]: l = [-1, 1, -10, 10]

In [3]: axis(l)
Out[3]: [-1, 1, -10, 10]

Again, if you are in an interactive mode, this will update the same figure. Furthermore, we can also update any value separately using keyword arguments (**kwargs), setting just xmax to a certain value.

If we don't use axis() or other settings, matplotlib will automatically use minimum values that allow us to see all data points on one plot. If we set axis() limits to be less than the maximum values in a dataset, matplotlib will do as told and we will not see all points on the figure. This can be a source of confusion or even error, where we think we see everything we drew. One way to avoid this is to call autoscale() (matplotlib.pyplot.autoscale()), which will compute the optimal size of the axes to fit the data to be displayed.

If we want to add new axes to the same figure, we can use matplotlib.pyplot.axes(). We usually want to add some properties to this default call; for example, rect—which can have the attributes left, bottom, width, and height in normalized units (0, 1)—and maybe axisbg, which specifies the background color of axes.

There are also other properties that we can set for added axes such as sharex/sharey, which accepts values for other instances of axes and share the current axis (x/y) with other axes. Or parameter polar that defines whether we want to use polar axes.

Adding new axes can be useful; for example, to combine multiple charts on one figure if there is a need to tightly couple different views on the same data to illustrate its properties.

If we want to add just one line to the current figure, we can use matplotlib.pyplot.axhline() or matplotlib.pyplot.axvline(). The functions axhilne() and axvline() will draw horizontal and vertical lines across axes for given x and y data values respectively. They share similar parameters, the most important ones being y position, xmin, and xmax for axhline() and x position, ymin, and ymax for axvline().

Let's see how it looks as a figure, continuing in the same IPython session:

In [3]: axhline()
Out[3]: <matplotlib.lines.Line2D at 0x414ecd0>

In [4]: axvline()
Out[4]: <matplotlib.lines.Line2D at 0x4152490>

In [5]: axhline(4)
Out[5]: <matplotlib.lines.Line2D at 0x4152850>

We should have a figure like the following plot:

Here we see that just calling these functions without parameters makes them take default values and draw a horizontal line for y=0 (axhline()) and a vertical line for x=0 (axvline()).

Similar to these are two related functions that allow us to add a horizontal span (rectangle) across the axes. These are matplotlib.pyplot.axhspan() and matplotlib.pyplot.axspan(). The function axhspan() has ymin and ymax as required parameters that define how wide the horizontal span is. Analogous to this, axvspan() has xmin and xmax to define the width of the vertical span.

Having a grid in a figure is turned off by default, but it can easily be switched on and customized. A default call to matplotlib.pyplot.grid() will toggle the grid's visibility. Other parameters for control are as shown here:

Axes are usually controlled via matplotlib.pyplot.axis(). Internally, axes are represented by several Python classes, the parent one is matplotlib.axes.Axes, which contains most methods to manipulate axes. A single axis is represented by the matplotlib.axis.Axis class, where the x axis uses matplotlib.axis.XAxis and the y axis uses the matplotlib.axis.YAxis class.

We don't need to use these to perform our recipe, but it is important to know where to look if more advanced axis control interests us and when we hit the limits of what is available via the matplotlib.pyplot namespace.