Matplotlib

In this section, we will introduce Matplotlib, the most long-lived Python package for plotting data and images. It is designed to work nicely with NumPy arrays, and natively uses two and three-dimensional arrays to represent images, (gray-scale and RGB, respectively). This section will introduce the basics of plotting and key features of Matplotlib.

There are many tutorials, “cheat sheets”, and other resources for using Matplotlib. Our goal here is to provide a treatment of Matplotlib with slightly deeper aims than simply showing you how to make “a plot that looks like …”. Specifically, our aim is to introduce Matplotib’s object oriented API, instead of its function-based API. Let’s briefly draw a distinction between these two APIs:

import matplotlib.pyplot as plt
# prepare 50 x-coordinates and 50 y-coordinates
x = np.linspace(-np.pi, np.pi, 50)
y = np.sin(x)

# Plot using matplotlib's object-oriented API:
# we figure and axis object: `fig` and `ax`
fig, ax = plt.subplots()
# we then use these objects to draw-on and manipulate our plot
ax.plot(x, y)

# Plot using matplotlib's functional API:
# a single function call produces a plot; convenient but less flexible
plt.plot(x, y)

Although the code that invokes the functional API is simpler, it is far less powerful and flexible than the object-oriented API, which produces figure (fig) and axes (ax) objects that we can leverage to customize our plot. You will likely see tutorials utilize the functional API in their examples, so it is useful to understand the distinction here. Shortly, you will learn how to leverage Matplotlib’s object-oriented API in powerful ways.

Consult the Matplotlib user’s guide, as well as their tutorials for additional information about this plotting library.

Matplotlib is included in the Anaconda distribution of Python packages. The pyplot submodule of Matplotlib contains all of the essential plotting functionality, thus we will always need to import pyplot. It is standard to utilize the abbreviation “plt” when importing the pyplot submodule from Matplotlib:

# import matplotlib's pyplot submodule
import matplotlib.pyplot as plt

There are many tutorials and examples available online, which demonstrate Matplotlib’s wide range of capabilities for visualizing data. Here, we will only distill the essentials needed for understanding how to use Matplotlib effectively for typical data science applications.

Plotting in Jupyter Notebooks

While Matplotlib provides a graphical interface for plots so that we can plot data from the Python shell or IPython, the Jupyter notebook is the ideal environment for creating and refining data visualizations. The command %matplotlib notebook, when executed in a notebook, will instruct Matplotlib to embed its plots within that notebook, rather than opening a separate window for each plot.

# instructs Jupyter to embed plots within a notebook
%matplotlib notebook

It need only be executed once in a given notebook to instruct plots to be embedded within that notebook. This will also allow us to interact with the plots that render within the notebook, enabling panning, zooming, and saving. We will proceed with this section with the assumption that we are embedding our plots in a notebook.

Finally, note that %matplotlib notebook is not a valid line of Python code, rather it is an example of a “magic command” which is reserved to affect the behavior of the IPython console and Jupyter notebook.

Creating Figures and Axes with pyplot.subplots

There are many different wasy to create blank figure and axes objects in Matplotlib. Here, we will introduce the function pyplot.subplots, which creates a figure that contains axes on which data is plotted. We will see that the keyword argument figsize can be used to control the size of the figure, and that the keyword arguments ncols and nrows can be used to specify the grid on which the axes will be laid out within the figure.

In Matplotlib, the Figure object is used to contain one or more sets of Axes objects. Data is plotted within a given set of axes. The subplots function can be used to create a figure along with a specified layout of axes. By default, subplots will create a figure with a single set of axes; calling it will return the figure object and its axes object in a tuple:

import matplotlib.pyplot as plt
%matplotlib notebook

# Creating a figure that contains a single
# set of axes. `plt.subplots()` returns
# the tuple: (Figure-instance, Axes-instance)
fig, ax = plt.subplots()

Executing this code will open a figure with a blank set of axes. We can use the Axes instance, ax, to plot data, add labels and a title to the plot, and add grid lines. The Figure instance, fig, controls higher-level features of the figure, such as the layout of the axes, the alignment of labels, and other factors. fig is perhaps most used for saving figures. Let’s plot a single period of a sine wave and then save it.

Plotting and Saving a Figure

In [2]:
# using subplots to create a figure with a singe set of axes
# plotting points on a sine curve

import numpy as np
import matplotlib.pyplot as plt
%matplotlib notebook


# create a figure and set of axes
fig, ax = plt.subplots()

# prepare 50 x-coordinates and 50 y-coordinates
x = np.linspace(-np.pi, np.pi, 50)
y = np.sin(x)

# Plot data on the axes object.
# Plots corresponding x-y coordinate pairs,
# specified by the x-coordinates in `x`
# and the y-coordinates in `y`
ax.plot(x, y)

# the `fig` object is responsible for saving the
# full figure and all of its axes. Thefollowing
# command will save a png-image of this plot
# to the directory from where this code is executed.
fig.savefig("sinewave_plt.png");  # the semicolon merely suppresses output to the console

The subplots function can be fed the keyword argument figsize to control the size of the figure; this accepts a tuple of the width and height of the figure, in inches. The axes objects will stretch to fill the figure size.

In [3]:
# specify the figure size created by `subplots`
# create a 6-inch x 2-inch figure
fig, ax = plt.subplots(figsize=(6,2))
ax.plot(x, y);

The keyword arguments nrows and ncols instructs the figure to contain nrows x ncols number of axes objects, laid out in a commensurate grid. In this case the second item returned in the tuple by subplots is not a single axes object, but instead a 2-dimensional NumPy array of shape (nrows, ngrids), containing the corresponding axes arguments.

Let’s create a figure with size sets of axes, laid out in a \(2 \times 3\) grid:

In [4]:
# demonstrating wide range of functionality controlled
# by the axes object.

# create a figure with multiple axes
fig, axs = plt.subplots(2, 3, figsize=(8, 3)) # 6 axes on a 2x3 grid
# note that we could also use tuple unpacking for our axes:
# fig, (ax1, ax2, ax3, ax4, ax5, ax6) = plt.subplots(2, 3)


# the domain of x-values on which we evaluate
# our functions
x = np.linspace(0, 4*np.pi, 1000)

# row-0, col-0: plot y = x**2
axs[0, 0].plot(x, x**2, linestyle='--', color='orange')

# row-0, col-1: plot y = sin(x)
axs[0, 1].plot(x, np.sin(x), color='green')

# row-0, col-2:  plot y = cos(x)
axs[0, 2].plot(x, np.cos(x), linestyle=':')

# row-1, col-0:  plot y = exp(x)
axs[1, 0].plot(x, np.exp(x), color='red', linestyle='-.')

# row-1, col-1:  plot y = sqrt(x)
axs[1, 1].plot(x, np.sqrt(x))

# row-1, col-2:  plot y = x
axs[1, 2].plot(x, x, color='purple');

Reading Comprehension: Creating a Basic Plot

Use pyplot.subplots to create a figure with two subplots that are aligned side-by-side (i.e. they reside in two columns). In the left subplot, plot \(f(x) = e^{-x}\) using 100 points on the domain \([0, 1]\). In the right subplot, plot \(f(x) = x^2\) on whatever domain you’d like, using a green line.

The Axes Object

The axes object is used to control the appearance of data within a plot. A quick glance at the official documentation for the axes object reveals that it is nearly “one object to rule them all” in Matplotlib, as it possesses a massive amount of functionality. It permits us to control the type of plotting being performed; the following is list of some of the various types of plots that can be created:

  • Axes.plot: lines with data markers
  • Axes.scatter: a scatter plot of x-y markers, without lines
  • Axes.hist: a histogram
  • Axes.bar: a bar chart
  • Axes.pie: a pie chart
  • Axes.imshow: draw an image within the axes
  • Axes.contour: create a contour plot

Furthermore, the axes object controls the scales of the axes (e.g. log-scaling versus linear-scaling). It permits us to create axis labels, a title, and to affect smaller details like a plot’s grid lines, tick-mark spacing, and many other items. In summary, you will be using the axes object to affect most aspects of your plot. For this reason, it is highly recommended that you familiarize yourself with the functions available to the axes object. We will only be able to demonstrate a fraction of its capabilities here; we will prioritize its most essential features, and will create diverse plots in doing so.

As seen in the previous example, ax.plot creates a plot with line-segments joining the the specified data points. See that, by default, it does not plot markers for each data point being plotted. We can use the marker and linestyle keyword arguments to specify the appearance of the markers for the data point, and the line segments that connect them, respectively. The available marker styles can be found here, and the available line styles can be found here.

For a given Axes instance, ax, ax.plot will plot to that set of axes; Matplotlib will automatically cycle through colors to make distinct each set of data being plotted. We can provide a label for each data set, and use ax.legend() to display the labels.

In [5]:
# plotting multiple curves on the same set of axes

fig, ax = plt.subplots()

x = np.linspace(-2*np.pi, 2*np.pi, 32)

# circles with a dashed line
ax.plot(x, np.sin(x)/(2*x), marker="o", linestyle="--", label='a')

# squares with a dash-dot line
ax.plot(x, np.sin(x)/(3*x), marker="s", linestyle="-.", label='b')

# upward triangles with a dotted line
ax.plot(x, np.sin(x)/(4*x), marker="^", linestyle=":", label='c')

# sideways triangles with no line
ax.plot(x, np.sin(x)/(5*x), marker="<", linestyle="", label='d')

# default: solid line with no markers
ax.plot(x, np.sin(x)/(6*x), label='e')

# add legend of labels to top-right
ax.legend(loc="upper right")

# annotate the axes with labels and a title
ax.set_xlabel("x label")
ax.set_ylabel("y label")
ax.set_title("Title")

# turn on x-y grid lines
ax.grid(True)

Now, we provide a potpourri of different plots that can be created via the axes object. The resulting \(2 \times 3\) grid of plots demonstrates the following:

Plot (0, 0)

  • Using Axes.set_yscale to set the y-axis scale a logarithmic scale.
  • Using LaTeX-formatted equations as labels.

Plot (0, 1)

  • Using Axes.fill_between to shade in the bounds between the error bars for a curve.
  • The alpha keyword arguments allows you to set the transparency level for the shading.
  • Specifying color=C0 allows you to match the color-0 from Matplotlib’s default color cycle.

Plot (0, 2)

  • Use Axes.errorbar to plot a curve with discrete error bars.

Plot (1, 0)

  • Use Axes.scatter to plot markers for two sets of x-y coordinates, without joining the markers with line segments.

Plot (1, 1)

  • Use Axes.hist to create a histogram, with 50 bins, for Gaussian-distributed data.

Plot (1, 2)

  • Use Axes.imshow to plot a matrix (a 2D NumPy array) as an image. The matrice’s entries take on random values, and the lower triangular half of the matrice’s entries are set to 0.
  • The magnitude of the entries are conveyed using Matplotlib’s default viridis colormap.
In [6]:
# demonstrating a variety of plot-types
fig, axs = plt.subplots(nrows=2, ncols=3)

################# Plot (0, 0) ##########################
# Demonstrating setting the y-axis to a log scale
x = np.linspace(0, 4, 1000)
y = x**2
axs[0, 0].plot(x, y, linestyle='--', color='red', label=r'$x^2$')
axs[0, 0].plot(x, np.exp(x), linestyle='--', color='blue', label=r'$e^x$')
axs[0, 0].set_yscale("log")
axs[0, 0].legend()


################# Plot (0, 1) ##########################
# Demonstrating `ax.fill_between`, and `alpha`
x = np.linspace(0, 10, 1000)
y = np.sqrt(x)
err_lower, err_upper = np.random.random((2, 1000))*0.2  # create the error bars
axs[0, 1].plot(x, y)

# fill between: (y - err_lower) and (y + err_upper)
# alpha indicates a meaure of opaqueness to a color: 0.2 makes the
# filled region semi-transparent
axs[0, 1].fill_between(x, y-err_lower, y+err_upper, color='C0', alpha=0.2)


################# Plot (0, 2) ##########################
# Demonstrating an errorbar plot
x = np.arange(10)
y = np.sqrt(x)

# each y has an associated lower and upper error bound,
# separated by row in a 2D array
yerr = np.random.random((2, 10))
axs[0, 2].errorbar(x, y, yerr, color="C2")


################# Plot (1, 0) ##########################
# Demonstrating a scatter plot
x = np.arange(10)
y = np.random.random(10)
axs[1, 0].scatter(x, y, marker='x')
axs[1, 0].scatter(x, 1-y, marker='o')


################# Plot (1, 1) ##########################
# Demonstrating a historgram
# Draw 100 numbers from Gaussian distribution,
# stored in shape-(100,) numpy array.
data = np.random.randn(1000)
# Display the data in a 50-bin histogram.
axs[1, 1].hist(data, bins=50)


################# Plot (1, 2) ##########################
# Plotting the entries of a 2D array as an image.

# random 10x10 array with lower "half" set to 0
matrix = np.triu(np.random.rand(10, 10))
axs[1, 2].imshow(matrix);

The Figure Object (Saving Figures)

Along with the Axes instances produced by plt.subplots, a Figure object is also produced. Like Axes, Figure has a massive amount of functionality associated with it. Its documentation can be found here. One of its essential uses is to save figures via the method Figure.savefig. Various file extensions can be specified with the image’s filename, such as pdf, jpg, png, and eps. The image will be saved to the corresponding format. Additionally, the resolution of the saved figure can be specified in term of “dots per inch” - this is thus controlled by the input argument dpi.

Beyond saving plots, the Figure object can be used to both retrieve and set information about our figure, including the size of the figure in inches, its resolution, and its background color.

In [7]:
fig, ax = plt.subplots(figsize=(3, 3))
x = np.linspace(-np.pi, np.pi, 50)
y = np.sin(x)
ax.plot(x, y)


# saving a figure as a pdf
fig.savefig("sinewave_plt.pdf")

# saving a figure as a 200 dot-per-inch png
fig.savefig("sinewave_plt.png", dpi=200);

Reading Comprehension: Saving a Plot

Plot the sine function with an amplitude of 1, 2, 4, and 8, respectively, all on the same subplot (e.g. \(2\sin{x}\) is the sine function with an amplitude of 2) on the domain \([-\pi, \pi]\). Label the x-axis as "x [radians]". Save this figure as “sine_waves.png”. Go and open this png-file and verify that it looks as you would expect.

Displaying Images

Matplotlib also provides functionality for displaying images. Using the Axes object, we will use its imshow method to display an image. Here, ‘image’ can be anything that “looks like” an image. For example, a 2D NumPy-array can be interpreted as a grayscale image where the rows and columns are pixel locations and the values are intensity. An image can also be \(r \times c \times 3\) array, where \(r\) and \(c\) correspond to rows and columns of pixels, and 3 indicates 3 color channels for red, green, and blue (RGB) pixel values, or \(r \times c \times 4\), where the channels are red, green, blue, and alpha (RGBA) for transparency.

Lets plot some of these. Let’s construct a 50x75x3 RGB image split into three vertical strips. The left strip will be red, the middle strip green, and the right strip blue. We will create a NumPy-array of zeros, and then populate its entries with RGB color values according to this pattern. Our array will store unsigned 8-bit integers (i.e. “uint8”); a uint8 number can store \(2^8 = 256\) distinct values: 0, 1, …, 255. Thus an RGB channel of (255, 0, 0) will be red, (0, 255, 0) is green, and (0, 0, 255) is blue. We could instead provide an array of floats instead of uint8 values, in which case our color values should fall in the domain \([0, 1]\). This is all documented in plt.imshow.

In [8]:
# generate and display an RGB image
# The image has a shape Height=50, Width=75, Color Channels=3
# Channel-0: red
# Channel-1: green
# Channel-2: blue
my_image = np.zeros((50, 75, 3)) # A shape-(50, 75, 3) array

# set the red channel values for columns 0-25
my_image[:, :25, 0] = 255

# set the green channel values for columns 25-50
my_image[:, 25:50, 1] = 255

# set the green channel values for columns 50-75
my_image[:, 50:75, 2] = 255

my_image = my_image.astype('uint8')

fig, ax = plt.subplots()
ax.imshow(my_image);

Now, let’s create a “magnitude” or “grayscale” image, which is an image with only one color channel. Let’s create a 15x25 image whose values ramp up linearly from 0 to 100 along its 25 columns. This ramp will occur identically along each row of pixels. We can choose from matplotlib’s many colormaps for displaying this image. In the top plot, we will use a grayscale. In the bottom plot, we choose the perceptually-uniform “viridis” colormap.

In [9]:
# generate and display a grayscale image
fig, (ax1, ax2) = plt.subplots(nrows=2)

# create a linear ramp from 0-100 along a shape-25 array,
# then broadcast this to a shape-(15, 25) array
my_image = np.broadcast_to(np.linspace(0, 100, 25), (15, 25))
ax1.imshow(my_image, cmap="gray")
ax2.imshow(my_image, cmap="viridis");

Lastly, we note that plt.imsave is available to save your numpy-array as an image file, and plt.imread is available to read an image file and load it as a numpy array (thus imsave and imread are inverses of one another).

Beyond Matplotlib

Although Matplotlib is the most long-lived plotting library for Python, it is not the only player in town, nor is necessarily it the best tool for all variety of visualizations. For instance, Matplotlib is not well-suited for plotting large amounts of data, nor does it facilitate dynamic, interactive plots very well. It is worthwhile to be aware of some of Python’s other plotting libraries, which benefit from a more focused design and leverage more modern plotting technologies.

ToyPlot provides a sleek, minimalist interface that aims to develop beautiful interactive, animated plots that embrace the unique capabilities of electronic publishing and support reproducibility.

Bokeh is an interactive visualization library that targets modern web browsers for presentation. Its goal is to provide elegant, concise construction of versatile graphics, and to extend this capability with high-performance interactivity over very large or streaming datasets.

Plotly has a Python graphing library makes interactive, publication-quality graphs online. It and Bokeh provide similar capabilities, and leverage JavaScript to create elegant interactive visualizations. Plotly and Bokeh both have their respective strengths and weaknesses.

Reading Comprehension Exercise Solutions:

Creating a Basic Plot: Solution

Use pyplot.subplots to create a figure with two subplots that are aligned side-by-side (i.e. they reside in two columns). In the left subplot, plot \(f(x) = e^{-x}\) using 100 points on the domain \([0, 1]\). In the right subplot, plot \(f(x) = x^2\) on whatever domain you’d like, using a green line.

import matplotlib.pyplot as plt
import numpy as np
%matplotlib notebook

fig, ax = plt.subplots(ncols=2)

x_left = np.linspace(0, 1, 100) # 100 points spaced evenly on [0, 1]
ax[0].plot(x_left, np.exp(-x_left))

x_right = np.linspace(-10, 10, 500)
ax[1].plot(x_right, (x_right)**2, color="green")

Saving a Plot: Solution

Plot the sine function with an amplitude of 1, 2, 4, and 8, respectively, all on the same subplot (e.g. \(2\sin{x}\) is the sine function with an amplitude of 2) on the domain \([-\pi, \pi]\). Label the x-axis as "x [radians]". Save this figure as “sine_waves.png”.

fig, ax = plt.subplots()
x = np.linspace(-np.pi, np.pi, 200)

for amp in [1, 2, 4, 8]:
    ax.plot(x, amp * np.sin(x))

ax.set_xlabel("x [radians]")
fig.savefig("sine_waves.png")