Getting started with matplotlib

This is a quick introduction into generating figures with python and the matplotlib package. Use it for hints (and links) on the most important commands. Check then their documentation for further details.

Import the matplotlib package:

import matplotlib.pyplot as plt

and generate some time series data for plotting:

import numpy as np
t = np.arange(0.0, 1.0, 0.01) # one second with time step 0.01
x = np.sin(2.0*np.pi*10.0*t)  # 10Hz sine wave

Then a quick way to plot this is

plt.plot(t, x)
plt.show()

Do not forget the show()!

This command displays the plot in a new window and let you interact with it (zooming and panning). By the way, these features have short keys: press o for zooming or p for panning. backspace brings you back. f is fullscreen mode.

This is great for quickly checking data in your code. For properly annotating a plot and for producing nice figures we use the object-oriented interface of matplotlib (see the object-oriented API and the lifecycle of a plot). This is described in the following:

Single plot in a figure

Generate a figure and an axes using the plt.subplots() function:

fig, ax = plt.subplots()

Then ax is a single matplotlib axes. This is a plot, a coordinate system, in which you can draw and annotate your data:

ax.plot(t, x)
ax.set_xlim(0, 0.2)
ax.set_xlabel('Time [s]')
ax.set_ylabel('Voltage [mV]')

Plot commands

A nice overview on available plot types is given here. See the matplotlib.axes API for a (long) list of member functions, including various types of plots and annotations.

Here is a selection of often used plot commands:

Setting colors, lines, and markers

Further key-word arguments to the plot commands allow to change colors, lines, and markers. In the following some of the more commonly used ones are listed.

Lines:

  • color or c: color specification, e.g. 'red', '#DD0000', or 'C3' (forth color of color cycle), see specifying colors.
  • linewidth or lw: width of connecting lines.
  • linestyle or ls: solid, dashed, or dotted: '-', '--', '-.', ':', ''.

Markers:

  • marker: the marker symbol, e.g. '.', 'o', 'v', 's', 'D', 'p', 'h', 'x', '+', '*', etc. see matplotlib.markers for a table.
  • markersize or ms: size of the marker symbol.
  • markerfacecolor or mfc: fill color of the marker, e.g. 'green' or '#00CC00'
  • markeredgecolor or mec: color of the outline of the marker, e.g. 'blue' or '#0000DD'
  • markeredgewidth or mew: width of the marker outline.

Other:

  • label: a label for the legend (see below).
  • clip_on: set to False if you do not want, for example, marker symbols to be clipped.
  • zorder: some number specifying the order in which elements are drawn into the plot. Higher numbers are drawn on top of lower numbers.

Logarithmic axis

For a logarithmic x-axis use ax.set_xscale():

ax.set_xlim(0.01, 1.0)
ax.set_xscale('log')

Likewise for the y-axis.

Make sure the data range starts at positive (non-zero) values using ax.set_xlim() and ax.set_ylim().

Legend

When you plot several data sets into an axes, you might want to add a legend to your plot. Pass a label to the plot commands and then call legend():

ax.plot(t, x, label='one')
ax.plot(t, 1.5*x, label='two')
ax.plot(t, 2.2*x, label='three')
ax.legend(loc='upper right')

Annotation

You can place some text somewhere in (or outside) your plot using the text() function:

ax.text(12.7, 8.2, 'a note')

The first two arguments are the x- and y-coordinate of the text in data coordinates.

Very useful is to specify the position of the text in relative axes coordinates:

ax.text(0.9, 0.9, 'another note', ha='right', transform=ax.transAxes)

This text is placed right aligned (ha='right') in the top right corner.

Save figure to a file

fig is a matplotlib figure. In this example it holds just one axes, but it can have many more (see next section). Each window you get with plt.show() contains a matplotlib figure. And you can save a matplotlib figure to a file using the savefig() function:

fig.savefig('myplot.pdf')

You can save the figure into pdf, svg, png, jpg and tex files. Just supply the right file extension.

If you also want to display your figure on screen, then call plt.show() after fig.savefig(), because on exit (closing the window), plt.show() destroys the figure.

Multiple plots in a figure

The simplest scenario is having a grid of subplots. The following example generates two rows and three columns of axes (=subplots) using the subplots() function:

fig, axs = plt.subplots(2, 3)

Now, axs is a 2-dimensional numpy array holding the six axes that we use like this:

axs[0,0].plot(t, x)    # top left plot
axs[1,2].plot(t, 2*x)  # bottom right plot

Alternatively to indexing the axes by both a row and a column index, you can flatten the axes array:

for k, ax in enumarate(axs.flat):
    ax.plot(x, k*y, label=f'{k}')

A single row or column of subplots can also be initialized like this:

fig, (ax1, ax2) = plt.subplots(1, 2)

With the sharex and sharey key words, you can tie the respective axis of the subplots together, such that is you zoom into one subplot, the other ones get zoomed as well:

fig, axs = plt.subplots(2, 3, sharex=True, sharey=True)

A very useful and less well known feature is that the relative widths and heights of the columns and rows of a grid of subplots can be specified like this:

fig, axs = plt.subplots(2, 3, gridspec_kw=dict(width_ratios=[3, 1, 1], height_ratios=[4, 1]))

The width_ratios and height_ratios give for each column/row a relative width/height.

For more details on how to layout subplots you definitely want to read the Arranging multiple Axes in a Figure tutorial and the GridSpec tutorial. Also check out the subplot_mosaic() function.

Customizing figure layout

First of all, you want to specify the size of your figure. Make each figure as large as you want it to be in your manuscript or presentation to ensure that the plot labels of all your figures have the same font size (no scaling of the figures in the manuscript or presentation).

fig, axs = plt.subplots(2, 3, figsize=(8, 5))  # in inch!

Unfortunately, the figsize argument takes the width and the height of the figure measured in inches. Hey - we are doing science here and want SI units! To specify your figure size in centimeters you need to divide by 2.54 cm/inch:

fig, axs = plt.subplots(2, 3, figsize=(12/2.54, 8/2.54))  # in cm

Second, you want your plots to nicely fill the figure (no extra whitespace at the borders). For this use

fig.subplots_adjust(left=0.2, right=0.95, top=0.95, bottom=0.1)

These are fractions of the full figure size. right and top are absolute coordinates, not the width and the height of the subplots. Adapt them as needed. After a while you get a feeling for good values and adjusting them gets easy.

Third, adjust the whitespace between the subplots. Don't let your urge to give each subplot as much space as possible win. Figures usually look much better with quite a lot of whitespace between them:

fig.subplots_adjust(wspace=0.5, hspace=0.4)

Both wspace and hspace specify the amount of whitespace relative to the average width/height of the subplots. hspace stands for "height" not "horizontal".

Customizing figure design

Label fonts, default colors, etc. can be customized globally for all your plots via rcParams. This is a must-read!

For example, to set the standard font size to 11pt and have somewhat smaller tick labels you may call

plt.rcParams['font.size'] = 11
plt.rcParams['xtick.labelsize'] = 'small'
plt.rcParams['ytick.labelsize'] = 'small'

before you create any figures and axes.

Further reading and cheat sheets

Figure guidelines

Continue reading with some figure guidelines.