matplotlib 3.5.1

NotesOther ParametersParametersReturnsBackRef
contourf(*args, data=None, **kwargs)

Call signature:

contourf([X, Y,] Z, [levels], **kwargs)

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

Notes

  1. :None:None:`.contourf` differs from the MATLAB version in that it does not draw the polygon edges. To draw edges, add line contours with calls to :None:None:`.contour`.

  2. :None:None:`.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).

  3. :None:None:`.contour` and :None:None:`.contourf` use a marching squares algorithm to compute contour locations. More information can be found in the source src/_contour.h .

Other Parameters

corner_mask : bool, default: :rc:`contour.corner_mask`

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.

colors : color string or sequence of colors, optional

The colors of the levels, i.e. the lines for :None:None:`.contour` and the areas for :None:None:`.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, single color strings may be used in place of one-element lists, i.e. 'red' instead of ['red'] to color all levels with the same color. This shortcut does only work for color strings, not for other ways of specifying colors.

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

alpha : float, default: 1

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

cmap : str or `.Colormap`, default: :rc:`image.cmap`

A .Colormap instance or registered colormap name. The colormap maps the level values to colors.

If both colors and cmap are given, an error is raised.

norm : `~matplotlib.colors.Normalize`, optional

If a colormap is used, the .Normalize instance scales the level values to the canonical colormap range [0, 1] for mapping to colors. If not given, the default linear scaling is used.

vmin, vmax : float, optional

If not None, either or both of these values will be supplied to the .Normalize instance, overriding the default color scaling based on levels.

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 image.origin .

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

If origin is not None, then extent is interpreted as in :None:None:`.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.

locator : ticker.Locator subclass, optional

The locator is used to determine the contour levels if they are not given explicitly via levels. Defaults to ~.ticker.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 :None:None:`.QuadContourSet` does not get notified if properties of its colormap are changed. Therefore, an explicit call :None:None:`.QuadContourSet.changed()` is needed after modifying the colormap. The explicit call can be left out, if a colorbar is assigned to the :None:None:`.QuadContourSet` because it internally calls :None:None:`.QuadContourSet.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, yunits : registered units, optional

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

antialiased : bool, optional

Enable antialiasing, overriding the defaults. For filled contours, the default is True. For line contours, it is taken from lines.antialiased .

nchunk : int >= 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.

linewidths : float or array-like, default: :rc:`contour.linewidth`

Only applies to :None:None:`.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 lines.linewidth .

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

Only applies to :None:None:`.contour`.

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

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.

hatches : list[str], optional

Only applies to :None:None:`.contourf`.

A list of cross hatch patterns to use on the filled areas. If None, no hatching will be added to the contour. Hatching is supported in the PostScript, PDF, SVG and Agg backends only.

data : indexable object, optional

If given, all parameters also accept a string s , which is interpreted as data[s] (unless this raises an exception).

Parameters

X, Y : array-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.

levels : int or array-like, optional

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

If an int n, use ~matplotlib.ticker.MaxNLocator , which tries to automatically choose no more than n+1 "nice" contour levels between vmin and vmax.

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

Returns

`~.contour.QuadContourSet`

Plot filled contours.

Examples

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

dask.array.creation.meshgrid matplotlib.pyplot.plotting

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them


File: /matplotlib/pyplot.py#2480
type: <class 'function'>
Commit: