matplotlib ¶

Matplotlib is a plotting library for the Python programming language and its numerical mathematics extension, NumPy. It provides an object-oriented API for embedding plots into applications that use general-purpose GUI toolkits, such as Tkinter, wxPython, Qt, or GTK. Matplotlib allows you to create a variety of static, animated, and interactive plots in Python.

With Matplotlib, you can generate various types of plots, including line plots, scatter plots, bar plots, histograms, and more. It is widely used for data visualization and is a popular choice among data scientists, engineers, and researchers for creating high-quality, publication-ready plots.

Matplotlib can be customized extensively, and it also supports LaTeX for mathematical expressions in labels and annotations. Additionally, it integrates well with other libraries like NumPy and pandas, making it a powerful tool for data analysis and visualization in the Python ecosystem.

Key resources:

• Tutorials
• User Guide
• Examples
• API

This tutorial covers some basic usage patterns and best practices to help you get started with Matplotlib.

In [1]:

import matplotlib.pyplot as plt
import numpy as np

import matplotlib as mpl

import matplotlib.pyplot as plt import numpy as np import matplotlib as mpl

Simple line graph ¶

Matplotlib graphs your data on Figures (e.g., windows, Jupyter widgets, etc.), each of which can contain one or more Axes , an area where points can be specified in terms of x-y coordinates (or theta-r in a polar plot, x-y-z in a 3D plot, etc.). The simplest way of creating a Figure with an Axes is using pyplot.subplots . We can then use Axes.plot to draw some data on the Axes:

In [2]:

fig, ax = plt.subplots()  # Create a figure containing a single axes.
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])  # Plot some data on the axes.
plt.show()  # Sometimes you need to put this here to show your plot.

fig, ax = plt.subplots() # Create a figure containing a single axes. ax.plot([1, 2, 3, 4], [1, 4, 2, 3]) # Plot some data on the axes. plt.show() # Sometimes you need to put this here to show your plot.

Parts of a Figure ¶

Here are the components of a Matplotlib Figure.

Figure ¶

The whole figure. The Figure keeps track of all the child Axes , a group of 'special' Artists (titles, figure legends, colorbars, etc), and even nested subfigures.

The easiest way to create a new Figure is with pyplot:

In [3]:

fig = plt.figure()  # an empty figure with no Axes
fig, ax = plt.subplots()  # a figure with a single Axes
fig, axs = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes
# a figure with one axes on the left, and two on the right:
fig, axs = plt.subplot_mosaic([["left", "right_top"], ["left", "right_bottom"]])

fig = plt.figure() # an empty figure with no Axes fig, ax = plt.subplots() # a figure with a single Axes fig, axs = plt.subplots(2, 2) # a figure with a 2x2 grid of Axes # a figure with one axes on the left, and two on the right: fig, axs = plt.subplot_mosaic([["left", "right_top"], ["left", "right_bottom"]])

<Figure size 640x480 with 0 Axes>

It is often convenient to create the Axes together with the Figure, but you can also manually add Axes later on. Note that many Matplotlib backends support zooming and panning on figure windows.

Axes ¶

An Axes is an Artist attached to a Figure that contains a region for plotting data, and usually includes two (or three in the case of 3D) Axis objects (be aware of the difference between Axes and Axis) that provide ticks and tick labels to provide scales for the data in the Axes. Each Axes also has a title (set via set_title()), an x-label (set via set_xlabel()), and a y-label (set via set_ylabel() ).

The Axes class and its member functions are the primary entry point to working with the OOP interface, and have most of the plotting methods defined on them (e.g. ax.plot(), shown above, uses the plot method).

Axis ¶

These objects set the scale and limits and generate ticks (the marks on the Axis) and ticklabels (strings labeling the ticks). The location of the ticks is determined by a Locator object and the ticklabel strings are formatted by a Formatter. The combination of the correct Locator and Formatter gives very fine control over the tick locations and labels.

Input types ¶

Plotting functions expect numpy.array or numpy.ma.masked_array as input, or objects that can be passed to numpy.asarray . Classes that are similar to arrays ('array-like') such as pandas data objects and numpy.matrix may not work as intended. Common convention is to convert these to numpy.array objects prior to plotting.

In [4]:

np.random.seed(19680801)  # seed the random number generator.
data = {"a": np.arange(50), "c": np.random.randint(0, 50, 50), "d": np.random.randn(50)}
data["b"] = data["a"] + 10 * np.random.randn(50)
data["d"] = np.abs(data["d"]) * 100

fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained")
ax.scatter("a", "b", c="c", s="d", data=data)
ax.set_xlabel("entry a")
ax.set_ylabel("entry b")

np.random.seed(19680801) # seed the random number generator. data = {"a": np.arange(50), "c": np.random.randint(0, 50, 50), "d": np.random.randn(50)} data["b"] = data["a"] + 10 * np.random.randn(50) data["d"] = np.abs(data["d"]) * 100 fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained") ax.scatter("a", "b", c="c", s="d", data=data) ax.set_xlabel("entry a") ax.set_ylabel("entry b")

Out[4]:

Text(0, 0.5, 'entry b')

Coding styles ¶

There are essentially two ways to use Matplotlib:

• Explicitly create Figures and Axes, and call methods on them (the "object-oriented (OO) style").
• Rely on pyplot to implicitly create and manage the Figures and Axes, and use pyplot functions for plotting.

Matplotlib's documentation and examples use both the OO and the pyplot styles. In general, we suggest using the OO style, particularly for complicated plots, and functions and scripts that are intended to be reused as part of a larger project. However, the pyplot style can be very convenient for quick interactive work.

Object-oriented ¶

In [5]:

x = np.linspace(0, 2, 100)  # Sample data.

# Note that even in the OO-style, we use `.pyplot.figure` to create the Figure.
fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained")
ax.plot(x, x, label="linear")  # Plot some data on the axes.
ax.plot(x, x**2, label="quadratic")  # Plot more data on the axes...
ax.plot(x, x**3, label="cubic")  # ... and some more.
ax.set_xlabel("x label")  # Add an x-label to the axes.
ax.set_ylabel("y label")  # Add a y-label to the axes.
ax.set_title("Simple Plot")  # Add a title to the axes.
ax.legend()  # Add a legend.

x = np.linspace(0, 2, 100) # Sample data. # Note that even in the OO-style, we use `.pyplot.figure` to create the Figure. fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained") ax.plot(x, x, label="linear") # Plot some data on the axes. ax.plot(x, x**2, label="quadratic") # Plot more data on the axes... ax.plot(x, x**3, label="cubic") # ... and some more. ax.set_xlabel("x label") # Add an x-label to the axes. ax.set_ylabel("y label") # Add a y-label to the axes. ax.set_title("Simple Plot") # Add a title to the axes. ax.legend() # Add a legend.

Out[5]:

<matplotlib.legend.Legend at 0x7f70aa3b2050>

pyplot ¶

In [6]:

x = np.linspace(0, 2, 100)  # Sample data.

plt.figure(figsize=(5, 2.7), layout="constrained")
plt.plot(x, x, label="linear")  # Plot some data on the (implicit) axes.
plt.plot(x, x**2, label="quadratic")  # etc.
plt.plot(x, x**3, label="cubic")
plt.xlabel("x label")
plt.ylabel("y label")
plt.title("Simple Plot")
plt.legend()

x = np.linspace(0, 2, 100) # Sample data. plt.figure(figsize=(5, 2.7), layout="constrained") plt.plot(x, x, label="linear") # Plot some data on the (implicit) axes. plt.plot(x, x**2, label="quadratic") # etc. plt.plot(x, x**3, label="cubic") plt.xlabel("x label") plt.ylabel("y label") plt.title("Simple Plot") plt.legend()

Out[6]:

<matplotlib.legend.Legend at 0x7f70aa185550>

Styling ¶

Most plotting methods have styling options for the Artists, accessible either when a plotting method is called, or from a "setter" on the Artist. In the plot below we manually set the color, linewidth, and linestyle of the Artists created by plot, and we set the linestyle of the second line after the fact with set_linestyle.

In [7]:

data1, data2, data3, data4 = np.random.randn(4, 100)  # make 4 random data sets

data1, data2, data3, data4 = np.random.randn(4, 100) # make 4 random data sets

In [8]:

fig, ax = plt.subplots(figsize=(5, 2.7))
x = np.arange(len(data1))
ax.plot(x, np.cumsum(data1), color="blue", linewidth=3, linestyle="--")
(l,) = ax.plot(x, np.cumsum(data2), color="orange", linewidth=2)
l.set_linestyle(":")

fig, ax = plt.subplots(figsize=(5, 2.7)) x = np.arange(len(data1)) ax.plot(x, np.cumsum(data1), color="blue", linewidth=3, linestyle="--") (l,) = ax.plot(x, np.cumsum(data2), color="orange", linewidth=2) l.set_linestyle(":")

Colors ¶

Matplotlib has a very flexible array of colors that are accepted for most Artists; see allowable color definitions for a list of specifications. Some Artists will take multiple colors. i.e. for a scatter plot, the edge of the markers can be different colors from the interior:

In [9]:

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.scatter(data1, data2, s=50, facecolor="C0", edgecolor="k")

fig, ax = plt.subplots(figsize=(5, 2.7)) ax.scatter(data1, data2, s=50, facecolor="C0", edgecolor="k")

Out[9]:

<matplotlib.collections.PathCollection at 0x7f70aa192d50>

Linewidths, linestyles, and markersizes ¶

Line widths are typically in typographic points (1 pt = 1/72 inch) and available for Artists that have stroked lines. Similarly, stroked lines can have a linestyle. See the linestyles example.

Marker size depends on the method being used. plot specifies markersize in points, and is generally the "diameter" or width of the marker. scatter specifies markersize as approximately proportional to the visual area of the marker. There is an array of markerstyles available as string codes (see markers), or users can define their own MarkerStyle (see Marker reference):

In [10]:

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(data1, "o", label="data1")
ax.plot(data2, "d", label="data2")
ax.plot(data3, "v", label="data3")
ax.plot(data4, "s", label="data4")
ax.legend()

fig, ax = plt.subplots(figsize=(5, 2.7)) ax.plot(data1, "o", label="data1") ax.plot(data2, "d", label="data2") ax.plot(data3, "v", label="data3") ax.plot(data4, "s", label="data4") ax.legend()

Out[10]:

<matplotlib.legend.Legend at 0x7f70aa28aed0>

Labelling plots ¶

Axes labels and text ¶

set_xlabel, set_ylabel, and set_title are used to add text in the indicated locations (see Text in Matplotlib for more discussion). Text can also be directly added to plots using text:

In [11]:

mu, sigma = 115, 15
x = mu + sigma * np.random.randn(10000)
fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained")
# the histogram of the data
n, bins, patches = ax.hist(x, 50, density=True, facecolor="C0", alpha=0.75)

ax.set_xlabel("Length [cm]")
ax.set_ylabel("Probability")
ax.set_title("Aardvark lengths\n (not really)")
ax.text(75, 0.025, r"$\mu=115,\ \sigma=15$")
ax.axis([55, 175, 0, 0.03])
ax.grid(True)

mu, sigma = 115, 15 x = mu + sigma * np.random.randn(10000) fig, ax = plt.subplots(figsize=(5, 2.7), layout="constrained") # the histogram of the data n, bins, patches = ax.hist(x, 50, density=True, facecolor="C0", alpha=0.75) ax.set_xlabel("Length [cm]") ax.set_ylabel("Probability") ax.set_title("Aardvark lengths\n (not really)") ax.text(75, 0.025, r"$\mu=115,\ \sigma=15$") ax.axis([55, 175, 0, 0.03]) ax.grid(True)

Legends ¶

Often we want to identify lines or markers with a Axes.legend:

In [12]:

fig, ax = plt.subplots(figsize=(5, 2.7))
ax.plot(np.arange(len(data1)), data1, label="data1")
ax.plot(np.arange(len(data2)), data2, label="data2")
ax.plot(np.arange(len(data3)), data3, "d", label="data3")
ax.legend()

fig, ax = plt.subplots(figsize=(5, 2.7)) ax.plot(np.arange(len(data1)), data1, label="data1") ax.plot(np.arange(len(data2)), data2, label="data2") ax.plot(np.arange(len(data3)), data3, "d", label="data3") ax.legend()

Out[12]:

<matplotlib.legend.Legend at 0x7f70aa3fdb90>

Color mapped ¶

Often we want to have a third dimension in a plot represented by a colors in a colormap. Matplotlib has a number of plot types that do this:

In [13]:

X, Y = np.meshgrid(np.linspace(-3, 3, 128), np.linspace(-3, 3, 128))
Z = (1 - X / 2 + X**5 + Y**3) * np.exp(-(X**2) - Y**2)

fig, axs = plt.subplots(2, 2, layout="constrained")
pc = axs[0, 0].pcolormesh(X, Y, Z, vmin=-1, vmax=1, cmap="RdBu_r")
fig.colorbar(pc, ax=axs[0, 0])
axs[0, 0].set_title("pcolormesh()")

co = axs[0, 1].contourf(X, Y, Z, levels=np.linspace(-1.25, 1.25, 11))
fig.colorbar(co, ax=axs[0, 1])
axs[0, 1].set_title("contourf()")

pc = axs[1, 0].imshow(
    Z**2 * 100, cmap="plasma", norm=mpl.colors.LogNorm(vmin=0.01, vmax=100)
)
fig.colorbar(pc, ax=axs[1, 0], extend="both")
axs[1, 0].set_title("imshow() with LogNorm()")

pc = axs[1, 1].scatter(data1, data2, c=data3, cmap="RdBu_r")
fig.colorbar(pc, ax=axs[1, 1], extend="both")
axs[1, 1].set_title("scatter()")

X, Y = np.meshgrid(np.linspace(-3, 3, 128), np.linspace(-3, 3, 128)) Z = (1 - X / 2 + X**5 + Y**3) * np.exp(-(X**2) - Y**2) fig, axs = plt.subplots(2, 2, layout="constrained") pc = axs[0, 0].pcolormesh(X, Y, Z, vmin=-1, vmax=1, cmap="RdBu_r") fig.colorbar(pc, ax=axs[0, 0]) axs[0, 0].set_title("pcolormesh()") co = axs[0, 1].contourf(X, Y, Z, levels=np.linspace(-1.25, 1.25, 11)) fig.colorbar(co, ax=axs[0, 1]) axs[0, 1].set_title("contourf()") pc = axs[1, 0].imshow( Z**2 * 100, cmap="plasma", norm=mpl.colors.LogNorm(vmin=0.01, vmax=100) ) fig.colorbar(pc, ax=axs[1, 0], extend="both") axs[1, 0].set_title("imshow() with LogNorm()") pc = axs[1, 1].scatter(data1, data2, c=data3, cmap="RdBu_r") fig.colorbar(pc, ax=axs[1, 1], extend="both") axs[1, 1].set_title("scatter()")

Out[13]:

Text(0.5, 1.0, 'scatter()')