How to Create Contour Plots in Matplotlib

Use Matplotlib’s contour() to draw lines connecting equal values in a two-dimensional scalar field, or contourf() to fill the regions between those lines. In both cases, NumPy can create the coordinate grid and calculate the values to plot; a colorbar shows how colors correspond to those values.

Use the contour() Method to Obtain Contour Plot in Matplotlib

A contour plot represents a scalar field on a two-dimensional plane. The x and y arrays give horizontal and vertical coordinates, while z contains the scalar value at each coordinate pair. Each contour line connects points where z has the same value. Matplotlib uses the corresponding entries in the three arrays together: x[i, j] and y[i, j] locate a point, and z[i, j] supplies its value. The coordinate grids and value array therefore need compatible two-dimensional shapes.

The example uses numpy.linspace() to make 500 coordinates from -2 through 2 on each axis. np.meshgrid() expands those one-dimensional coordinates into matching two-dimensional arrays, and z = np.sin(x) + np.cos(y) calculates a value at every grid location. See the np.meshgrid() method for more on building coordinate grids.

The following example creates the grid, draws the isolines, adds a colorbar, and opens the figure. The code is included for readers to run; this draft has no attached runtime result.

import matplotlib.pyplot as plot
import numpy as np

x_values = np.linspace(-2, 2, 500)
y_values = np.linspace(-2, 2, 500)
x, y = np.meshgrid(x_values, y_values)
z = np.sin(x) + np.cos(y)

plot.contour(x, y, z)
plot.colorbar()
plot.show()

The first two arguments to contour() are the coordinate grids and the third is the scalar field. The function accepts additional optional arguments, including levels, which controls where contour lines are drawn. When omitted, Matplotlib chooses levels from the data range. plot.colorbar() adds a scale for reading the field values represented by the plot’s colors. It is useful when you need to interpret an isoline or compare values at different locations; the axes still show the x and y coordinates.

Use the contourf() Method in Matplotlib

Use contourf() for a filled contour plot: it colors the regions between contour levels, while contour() draws the contour lines. The inputs have the same roles in either method, so the grid and scalar field from the first example can be reused. A filled plot can make broad value ranges easier to compare, and its colorbar gives the colors a numeric scale. This complete example also sets levels=30 and adds a colorbar. It is provided for readers to run; this draft has no attached runtime result.

import matplotlib.pyplot as plot
import numpy as np

x_values = np.linspace(-2, 2, 500)
y_values = np.linspace(-2, 2, 500)
x, y = np.meshgrid(x_values, y_values)
z = np.sin(x) + np.cos(y)

filled = plot.contourf(x, y, z, levels=30, vmin=-1, vmax=0.5)
plot.colorbar(filled)
plot.show()

levels specifies the contour levels and therefore controls how the field is divided into colored regions. By contrast, vmin and vmax set the color normalization limits; they do not remove values from z or choose contour levels. Values below or above those limits remain represented and map to the colormap’s under or over colors. With the default colormap, those colors are its endpoint colors unless custom under or over colors are set.

In this example, the values from z remain part of the filled contour plot even when they fall outside the -1 to 0.5 color range. Use levels when you want to change the contour divisions, and use vmin or vmax when you want to change how values map onto the color scale.