Section Navigation

matplotlib.pyplot.contour#

matplotlib.pyplot.contour(*args, data=None, **kwargs)[source]#

Plot contour lines.

Call signature:

contour([X, Y,] Z, /, [levels], **kwargs)

The arguments X, Y, Z are positional-only.

contour and contourf draw contour lines and filled contours, respectively. Except as noted, function signatures and return values are the same for both versions.

Parameters:

X, Yarray-like, optional

The coordinates of the values in Z.

X and Y must both be 2D with the same shape as Z (e.g. created via numpy.meshgrid), or they must both be 1-D such that len(X) == N is the number of columns in Z and len(Y) == M is the number of rows in Z.

X and Y must both be ordered monotonically.

If not given, they are assumed to be integer indices, i.e. X = range(N), Y = range(M).

Z(M, N) array-like

The height values over which the contour is drawn. Color-mapping is controlled by cmap, norm, vmin, and vmax.

levelsint or array-like, optional

Determines the number and positions of the contour lines / regions.

If an int n, use MaxNLocator, which tries to automatically choose no more than n+2 "nice" contour level boundaries between the minimum and maximum numeric values of Z. These boundaries define where lines are drawn (for contour) or where filled regions are separated (for contourf).

If not given, a reasonable default is chosen; for linear scales, *n*=7 is the default.

If array-like, draw contour lines at the specified levels. The values must be in increasing order.

If not specified, a reasonable default is automatically chosen. For linear scales, this corresponds to levels=7. For logarithmic scales, LogLocator is used instead.

Returns:

QuadContourSet

Other Parameters:

corner_maskbool, default: rcParams["contour.corner_mask"] (default: True)

Enable/disable corner masking, which only has an effect if Z is a masked array. If False, any quad touching a masked point is masked out. If True, only the triangular corners of quads nearest those points are always masked out, other triangular corners comprising three unmasked points are contoured as usual.

colorscolor or list of color, optional

The colors of the levels, i.e. the lines for contour and the areas for contourf.

The sequence is cycled for the levels in ascending order. If the sequence is shorter than the number of levels, it's repeated.

As a shortcut, a single color may be used in place of one-element lists, i.e. 'red' instead of ['red'] to color all levels with the same color.

Changed in version 3.10: Previously a single color had to be expressed as a string, but now any valid color format may be passed.

By default (value None), the colormap specified by cmap will be used.

alphafloat, default: 1

The alpha blending value, between 0 (transparent) and 1 (opaque).

cmapstr 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 colors is set.

normstr or Normalize, optional

The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1.

If given, this can be one of the following:

An instance of Normalize or one of its subclasses (see Colormap normalization).
A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a list of available scales, call matplotlib.scale.get_scale_names(). In that case, a suitable Normalize subclass is dynamically generated and instantiated.

This parameter is ignored if colors is set.

vmin, vmaxfloat, 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).

If vmin or vmax are not given, the default color scaling is based on levels.

This parameter is ignored if colors is set.

colorizerColorizer or None, default: None

The Colorizer object used to map color to data. If None, a Colorizer object is created from a norm and cmap.

This parameter is ignored if colors is set.

origin{None, 'upper', 'lower', 'image'}, default: None

Determines the orientation and exact position of Z by specifying the position of Z[0, 0]. This is only relevant, if X, Y are not given.

None: Z[0, 0] is at X=0, Y=0 in the lower left corner.
'lower': Z[0, 0] is at X=0.5, Y=0.5 in the lower left corner.
'upper': Z[0, 0] is at X=N+0.5, Y=0.5 in the upper left corner.
'image': Use the value from rcParams["image.origin"] (default: 'upper').

extent(x0, x1, y0, y1), optional

If origin is not None, then extent is interpreted as in imshow: it gives the outer pixel boundaries. In this case, the position of Z[0, 0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of Z[0, 0], and (x1, y1) is the position of Z[-1, -1].

This argument is ignored if X and Y are specified in the call to contour.

locatorticker.Locator subclass, optional

The locator is used to determine the contour levels if they are not given explicitly via levels. Defaults to MaxNLocator.

extend{'neither', 'both', 'min', 'max'}, default: 'neither'

Determines the contourf-coloring of values that are outside the levels range.

If 'neither', values outside the levels range are not colored. If 'min', 'max' or 'both', color the values below, above or below and above the levels range.

Values below min(levels) and above max(levels) are mapped to the under/over values of the Colormap. Note that most colormaps do not have dedicated colors for these by default, so that the over and under values are the edge values of the colormap. You may want to set these values explicitly using Colormap.set_under and Colormap.set_over.

Note

An existing QuadContourSet does not get notified if properties of its colormap are changed. Therefore, an explicit call changed() is needed after modifying the colormap. The explicit call can be left out, if a colorbar is assigned to the QuadContourSet because it internally calls changed().

Example:

x = np.arange(1, 10)
y = x.reshape(-1, 1)
h = x * y

cs = plt.contourf(h, levels=[10, 30, 50],
    colors=['#808080', '#A0A0A0', '#C0C0C0'], extend='both')
cs.cmap.set_over('red')
cs.cmap.set_under('blue')
cs.changed()

xunits, yunitsregistered units, optional

Override axis units by specifying an instance of a matplotlib.units.ConversionInterface.

antialiasedbool, optional

Enable antialiasing, overriding the defaults. For filled contours, the default is False. For line contours, it is taken from rcParams["lines.antialiased"] (default: True).

nchunkint >= 0, optional

If 0, no subdivision of the domain. Specify a positive integer to divide the domain into subdomains of nchunk by nchunk quads. Chunking reduces the maximum length of polygons generated by the contouring algorithm which reduces the rendering workload passed on to the backend and also requires slightly less RAM. It can however introduce rendering artifacts at chunk boundaries depending on the backend, the antialiased flag and value of alpha.

linewidthsfloat or array-like, default: rcParams["contour.linewidth"] (default: None)

Only applies to contour.

The line width of the contour lines.

If a number, all levels will be plotted with this linewidth.

If a sequence, the levels in ascending order will be plotted with the linewidths in the order specified.

If None, this falls back to rcParams["lines.linewidth"] (default: 1.5).

linestyles{None, 'solid', 'dashed', 'dashdot', 'dotted'}, optional

Only applies to contour.

If linestyles is None, the default is 'solid' unless the lines are monochrome. In that case, negative contours will instead take their linestyle from the negative_linestyles argument.

linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary.

negative_linestyles{None, 'solid', 'dashed', 'dashdot', 'dotted'}, optional

Only applies to contour.

If linestyles is None and the lines are monochrome, this argument specifies the line style for negative contours.

If negative_linestyles is None, the default is taken from rcParams["contour.negative_linestyle"] (default: 'dashed').

negative_linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary.

hatcheslist[str], optional

Only applies to contourf.

A list of cross hatch patterns to use on the filled areas. If None, no hatching will be added to the contour.

algorithm{'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional

Which contouring algorithm to use to calculate the contour lines and polygons. The algorithms are implemented in ContourPy, consult the ContourPy documentation for further information.

The default is taken from rcParams["contour.algorithm"] (default: 'mpl2014').

clip_pathPatch or Path or TransformedPath

Set the clip path. See set_clip_path.

Added in version 3.8.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.

rasterizedbool, optional

Only applies to contourf. Rasterize the contour plot when drawing vector graphics. This can speed up rendering and produce smaller files for large data sets. See also Rasterization for vector graphics.

Notes

Note

This is the pyplot wrapper for axes.Axes.contour.

contourf differs from the MATLAB version in that it does not draw the polygon edges. To draw edges, add line contours with calls to contour.
contourf fills intervals that are closed at the top; that is, for boundaries z1 and z2, the filled region is:
```
z1 < Z <= z2
```
except for the lowest interval, which is closed on both sides (i.e. it includes the lowest value).
contour and contourf use a marching squares algorithm to compute contour locations. More information can be found in ContourPy documentation.

Examples using `matplotlib.pyplot.contour`#

[]

Blend transparency with color in 2D images

[]

Contour plot of irregularly spaced data

[]

[]

[]

[]

[]

[]

[]

Interactive functions

matplotlib.pyplot.contour#

Examples using matplotlib.pyplot.contour#

Examples using `matplotlib.pyplot.contour`#