pytutorial/matplotlib/basics

Basics of matplotlib.pyplot

{:.no_toc}

* TOC {:toc}

The goal

Questions to David Rotermund

pylab is a historic interface and its use is strongly discouraged. The equivalent replacement is matplotlib.pyplot

Simple example with plot

import numpy as np
import matplotlib.pyplot as plt  # type: ignore

f: float = 10
t = np.linspace(0, 1.0, 10000)
y = np.sin(t * 2 * np.pi * f)
z = np.cos(t * 2 * np.pi * f)

plt.figure(1)
plt.plot(t, y, label="Sin")
plt.plot(t, z, label="Cos")
plt.xlabel("t")
plt.ylabel("f(t)")
plt.title("Some Functions")
plt.legend()
plt.savefig("Test.pdf")

plt.show()  # This is optinal in Interactive Cell mode

plt.figure()

matplotlib.pyplot.figure(num=None, figsize=None, dpi=None, *, facecolor=None, edgecolor=None, frameon=True, FigureClass=<class 'matplotlib.figure.Figure'>, clear=False, **kwargs)

Create a new figure, or activate an existing figure.

plt.plot()

matplotlib.pyplot.plot(*args, scalex=True, scaley=True, data=None, **kwargs)

Well, this function definition is not very helpful.

Plot y versus x as lines and/or markers.

plot([x], y, [fmt], *, data=None, **kwargs)
plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

Some examples:

plot(x, y)        # plot x and y using default line style and color
plot(x, y, 'bo')  # plot x and y using blue circle markers
plot(y)           # plot y using x as index array 0..N-1
plot(y, 'r+')     # ditto, but with red plusses
plot(x, y, 'go--', linewidth=2, markersize=12)
plot(x, y, color='green', marker='o', linestyle='dashed',linewidth=2, markersize=12)

Plotting multiple sets of data

The most straight forward way is just to call plot multiple times. Example:

plot(x1, y1, 'bo')
plot(x2, y2, 'go')

By default, each line is assigned a different style specified by a 'style cycle'. The fmt and line property parameters are only necessary if you want explicit deviations from these defaults. Alternatively, you can also change the style cycle using rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'])).

Main parameter

x, y : array-like or scalar The horizontal / vertical coordinates of the data points. x values are optional and default to range(len(y)). Commonly, these parameters are 1D arrays. They can also be scalars, or two-dimensional (in that case, the columns represent separate data sets). These arguments cannot be passed as keywords.

fmt : str, optional A format string, e.g. 'ro' for red circles. See the Notes section for a full description of the format strings. Format strings are just an abbreviation for quickly setting basic line properties. All of these and more can also be controlled by keyword arguments. This argument cannot be passed as keyword.

Format Strings

A format string consists of a part for color, marker and line:

fmt = '[marker][line][color]'

Each of them is optional. If not provided, the value from the style cycle is used. Exception: If line is given, but no marker, the data will be a line without markers.

Other combinations such as [color][marker][line] are also supported, but note that their parsing may be ambiguous.

Markers

character	description
'.'
','
'o'	circle marker
'v'	triangle_down marker
'^'	triangle_up marker
'<'	triangle_left marker
'>'	triangle_right marker
'1'	tri_down marker
'2'	tri_up marker
'3'	tri_left marker
'4'	tri_right marker
'8'	octagon marker
's'	square marker
'p'	pentagon marker
'P'	plus (filled) marker
'*'	star marker
'h'	hexagon1 marker
'H'	hexagon2 marker
'+'	plus marker
'x'	x marker
'X'	x (filled) marker
'D'	diamond marker
'd'	thin_diamond marker
'|'	vline marker
'_'	hline marker

Line Styles

character	description
'-'	solid line style
'--'	dashed line style
'-.'	dash-dot line style
':'	dotted line style

Colors

The supported color abbreviations are the single letter codes

character	color
'b'	blue
'g'	green
'r'	red
'c'	cyan
'm'	magenta
'y'	yellow
'k'	black
'w'	white

and the 'CN' colors that index into the default property cycle.

If the color is the only part of the format string, you can additionally use any matplotlib.colors spec, e.g. full names ('green') or hex strings ('#008000').

Other parameters

there are more parameters

alpha	Set the alpha value used for blending - not supported on all backends.
antialiased or aa	bool
clip_box	BboxBase or None
clip_on	bool
color or c	color
dash_capstyle	CapStyle or {'butt', 'projecting', 'round'}
dash_joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
dashes	sequence of floats (on/off ink in points) or (None, None)
drawstyle or ds	{'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default'
figure	Figure
fillstyle	{'full', 'left', 'right', 'bottom', 'top', 'none'}
gapcolor	color or None
label	object
linestyle or ls	{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw	float
marker	marker style string, Path or MarkerStyle
markeredgecolor or mec	color
markeredgewidth or mew	float
markerfacecolor or mfc	color
markerfacecoloralt or mfcalt	color
markersize or ms	float
rasterized	Force rasterized (bitmap) drawing for vector graphics output.
solid_capstyle	CapStyle or {'butt', 'projecting', 'round'}
solid_joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
url	str
visible	bool

plt.xlabel()

matplotlib.pyplot.xlabel(xlabel, fontdict=None, labelpad=None, *, loc=None, **kwargs)

Set the label for the x-axis.

plt.ylabel()

matplotlib.pyplot.ylabel(ylabel, fontdict=None, labelpad=None, *, loc=None, **kwargs)

Set the label for the y-axis.

plt.title()

matplotlib.pyplot.title(label, fontdict=None, loc=None, pad=None, *, y=None, **kwargs)

Set a title for the Axes.

Set one of the three available Axes titles. The available titles are positioned above the Axes in the center, flush with the left edge, and flush with the right edge.

plt.legend()

matplotlib.pyplot.legend(*args, **kwargs)

Place a legend on the Axes.

legend()
legend(handles, labels)
legend(handles=handles)
legend(labels)

There are parameters. A lot. However, you mainly need loc for locations of the legend.

Location String

loc : str or pair of floats, default: rcParams["legend.loc"] (default: 'best')

Location	Code
'best' (Axes only)	0
'upper right'	1
'upper left'	2
'lower left'	3
'lower right'	4
'right'	5
'center left'	6
'center right'	7
'lower center'	8
'upper center'	9
'center'	10

plt.savefig()

matplotlib.pyplot.savefig(*args, **kwargs)

Save the current figure.

savefig(fname, *, transparent=None, dpi='figure', format=None,
        metadata=None, bbox_inches=None, pad_inches=0.1,
        facecolor='auto', edgecolor='auto', backend=None,
        **kwargs
       )

The available output formats depend on the backend being used.

Note: savefig has to be done before show, otherwise the exported image will be empty.

plt.show()

matplotlib.pyplot.show(*, block=None)

Display all open figures.

Simple example with imshow

import numpy as np
import matplotlib.pyplot as plt  # type: ignore

rng = np.random.default_rng()
data = rng.random((5, 10))

plt.figure(1)
plt.imshow(data, cmap="hot")
plt.colorbar()

plt.xlabel("Parameter 0 -- data: dim0")
plt.ylabel("Parameter 1 -- data: dim1")
plt.title("Some Functions")

plt.show()  # This is optinal in Interactive Cell mode

plt.imshow()

matplotlib.pyplot.imshow(X, cmap=None, norm=None, *, aspect=None, interpolation=None, alpha=None, vmin=None, vmax=None, origin=None, extent=None, interpolation_stage=None, filternorm=True, filterrad=4.0, resample=None, url=None, data=None, **kwargs)

Display data as an image, i.e., on a 2D regular raster.

The input may either be actual RGB(A) data, or 2D scalar data, which will be rendered as a pseudocolor image. For displaying a grayscale image, set up the colormapping using the parameters cmap='gray', vmin=0, vmax=255.

There is a collection of arguments available. Here are the most important ones:

X: array-like or PIL image The image data. Supported array shapes are:

(M, N): an image with scalar data. The values are mapped to colors using normalization and a colormap. See parameters norm, cmap, vmin, vmax.

(M, N, 3): an image with RGB values (0-1 float or 0-255 int).

(M, N, 4): an image with RGBA values (0-1 float or 0-255 int), i.e. including transparency.

The first two dimensions (M, N) define the rows and columns of the image.

Out-of-range RGB(A) values are clipped.

cmap : str or Colormap, default: rcParams["image.cmap"] (default: 'viridis') The Colormap instance or registered colormap name used to map scalar data to colors.

This parameter is ignored if X is RGB(A).

vmin, vmax : float, optional When using scalar data and no explicit norm, vmin and vmax define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data. It is an error to use vmin/vmax when a norm instance is given (but using a str norm name together with vmin/vmax is acceptable).

This parameter is ignored if X is RGB(A).

aspect : {'equal', 'auto'} or float or None, default: None The aspect ratio of the Axes. This parameter is particularly relevant for images since it determines whether data pixels are square.

This parameter is a shortcut for explicitly calling Axes.set_aspect. See there for further details.

'equal': Ensures an aspect ratio of 1. Pixels will be square (unless pixel sizes are explicitly made non-square in data coordinates using extent).

'auto': The Axes is kept fixed and the aspect is adjusted so that the data fit in the Axes. In general, this will result in non-square pixels.

Normally, None (the default) means to use rcParams["image.aspect"] (default: 'equal'). However, if the image uses a transform that does not contain the axes data transform, then None means to not modify the axes aspect at all (in that case, directly call Axes.set_aspect if desired).

interpolation : str, default: rcParams["image.interpolation"] (default: 'antialiased')

plt.colorbar()

Managing Figure and Axes

axes	Add an Axes to the current figure and make it the current Axes.
cla	Clear the current axes.
clf	Clear the current figure.
close	Close a figure window.
delaxes	Remove an Axes (defaulting to the current axes) from its figure.
fignum_exists	Return whether the figure with the given id exists.
figure	Create a new figure, or activate an existing figure.
gca	Get the current Axes.
gcf	Get the current figure.
get_figlabels	Return a list of existing figure labels.
get_fignums	Return a list of existing figure numbers.
sca	Set the current Axes to ax and the current Figure to the parent of ax.
subplot	Add an Axes to the current figure or retrieve an existing Axes.
subplot2grid	Create a subplot at a specific location inside a regular grid.
subplot_mosaic	Build a layout of Axes based on ASCII art or nested lists.
subplots	Create a figure and a set of subplots.
twinx	Make and return a second axes that shares the x-axis.
twiny	Make and return a second axes that shares the y-axis.

Basic

more Basic

plot	Plot y versus x as lines and/or markers.
errorbar	Plot y versus x as lines and/or markers with attached errorbars.
scatter	A scatter plot of y vs.
step	Make a step plot.
loglog	Make a plot with log scaling on both the x- and y-axis.
semilogx	Make a plot with log scaling on the x-axis.
semilogy	Make a plot with log scaling on the y-axis.
bar	Make a bar plot.
barh	Make a horizontal bar plot.
bar_label	Label a bar plot.
pie	Plot a pie chart.
vlines	Plot vertical lines at each x from ymin to ymax.
hlines	Plot horizontal lines at each y from xmin to xmax.
fill	Plot filled polygons.
polar	Make a polar plot.

Spans

Spans

Spectral

Spectral

Binned

more Binned

hist	Compute and plot a histogram.
hist2d	Make a 2D histogram plot.

Contours

clabel	Label a contour plot.
contour	Plot contour lines.
contourf	Plot filled contours.

2D arrays

more 2D arrays

imshow	Display data as an image, i.e., on a 2D regular raster.

Unstructured triangles

Unstructured triangles

Text and annotations

annotate	Annotate the point xy with text text.
text	Add text to the Axes.
figtext	Add text to figure.
table	Add a table to an Axes.
arrow	Add an arrow to the Axes.
figlegend	Place a legend on the figure.
legend	Place a legend on the Axes.

Vector fields

Vector fields

Axis configuration

autoscale	Autoscale the axis view to the data (toggle).
axis	Convenience method to get or set some axis properties.
box	Turn the axes box on or off on the current axes.
grid	Configure the grid lines.
locator_params	Control behavior of major tick locators.
minorticks_off	Remove minor ticks from the Axes.
minorticks_on	Display minor ticks on the Axes.
rgrids	Get or set the radial gridlines on the current polar plot.
thetagrids	Get or set the theta gridlines on the current polar plot.
tick_params	Change the appearance of ticks, tick labels, and gridlines.
ticklabel_format	Configure the ScalarFormatter used by default for linear Axes.
xlabel	Set the label for the x-axis.
xlim	Get or set the x limits of the current axes.
xscale	Set the xaxis' scale.
xticks	Get or set the current tick locations and labels of the x-axis.
ylabel	Set the label for the y-axis.
ylim	Get or set the y-limits of the current axes.
yscale	Set the yaxis' scale.
yticks	Get or set the current tick locations and labels of the y-axis.
title	Set a title for the Axes.

Layout

more Layout

margins	Set or retrieve autoscaling margins.
subplots_adjust	Adjust the subplot layout parameters.
tight_layout	Adjust the padding between and around subplots.

Colormapping

more Colormapping

clim	Set the color limits of the current image.
colorbar	Add a colorbar to a plot.
sci	Set the current image.
get_cmap	Get a colormap instance, defaulting to rc values if name is None.
set_cmap	Set the default colormap, and applies it to the current image if any.
imread	Read an image from a file into an array.
imsave	Colormap and save an array as an image file.

Configuration

more Configuration

rc	Set the current rcParams. group is the grouping for the rc, e.g., for lines.linewidth the group is lines, for axes.facecolor, the group is axes, and so on. Group may also be a list or tuple of group names, e.g., (xtick, ytick). kwargs is a dictionary attribute name/value pairs, e.g.,::.
rcdefaults	Restore the rcParams from Matplotlib's internal default style.

Output

more Output

draw	Redraw the current figure.
ioff	Disable interactive mode.
ion	Enable interactive mode.
pause	Run the GUI event loop for interval seconds.
savefig	Save the current figure.
show	Display all open figures.

Other

more Other

waitforbuttonpress	Blocking call to interact with the figure.