- Axes.contourf(*args, data=None, **kwargs)[source]#
Plot filled contours.
Call signature:
contourf([X, Y,] Z, [levels], **kwargs)
contour and contourf draw contour lines and filled contours,respectively. Except as noted, function signatures and return valuesare 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 suchthatlen(X) == N
is the number of columns in Z andlen(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 iscontrolled 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 triesto automatically choose no more than n+1 "nice" contour levelsbetween minimum and maximum numeric values of Z.
If array-like, draw contour lines at the specified levels.The values must be in increasing order.
- Returns:
- QuadContourSet
- Other Parameters:
- corner_maskbool, default:
rcParams["contour.corner_mask"]
(default:True
) Enable/disable corner masking, which only has an effect if Z isa masked array. If
False
, any quad touching a masked point ismasked out. IfTrue
, only the triangular corners of quadsnearest those points are always masked out, other triangularcorners 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 theareas for contourf.
The sequence is cycled for the levels in ascending order. If thesequence is shorter than the number of levels, it's repeated.
As a shortcut, single color strings may be used in place ofone-element lists, i.e.
'red'
instead of['red']
to colorall levels with the same color. This shortcut does only work forcolor strings, not for other ways of specifying colors.By default (value None), the colormap specified by cmapwill 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 datato 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] rangebefore mapping to colors using cmap. By default, a linear scaling isused, 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 alist of available scales, call matplotlib.scale.get_scale_names().In that case, a suitable Normalize subclass is dynamically generatedand instantiated.
This parameter is ignored if colors is set.
- vmin, vmaxfloat, optional
When using scalar data and no explicit norm, vmin and vmax definethe data range that the colormap covers. By default, the colormap coversthe complete value range of the supplied data. It is an error to usevmin/vmax when a norm instance is given (but using a
str
normname together with vmin/vmax is acceptable).If vmin or vmax are not given, the default color scaling is based onlevels.
This parameter is ignored if colors is set.
- origin{None, 'upper', 'lower', 'image'}, default: None
Determines the orientation and exact position of Z by specifyingthe position of
Z[0, 0]
. This is only relevant, if X, Yare 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 leftcorner.'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 inimshow: it gives the outer pixel boundaries. In this case, theposition of Z[0, 0] is the center of the pixel, not a corner. Iforigin 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 callto contour.
- locatorticker.Locator subclass, optional
The locator is used to determine the contour levels if theyare not given explicitly via levels.Defaults to MaxNLocator.
- extend{'neither', 'both', 'min', 'max'}, default: 'neither'
Determines the
contourf
-coloring of values that are outside thelevels range.If 'neither', values outside the levels range are not colored.If 'min', 'max' or 'both', color the values below, above or belowand above the levels range.
Values below
min(levels)
and abovemax(levels)
are mappedto the under/over values of the Colormap. Note that mostcolormaps do not have dedicated colors for these by default, sothat the over and under values are the edge values of the colormap.You may want to set these values explicitly usingColormap.set_under and Colormap.set_over.Note
An existing QuadContourSet does not get notified ifproperties of its colormap are changed. Therefore, an explicitcall
QuadContourSet.changed()
is needed after modifying thecolormap. The explicit call can be left out, if a colorbar isassigned to the QuadContourSet because it internally callsQuadContourSet.changed()
.Example:
x = np.arange(1, 10)y = x.reshape(-1, 1)h = x * ycs = 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 amatplotlib.units.ConversionInterface.
- antialiasedbool, optional
Enable antialiasing, overriding the defaults. Forfilled 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 todivide the domain into subdomains of nchunk by nchunk quads.Chunking reduces the maximum length of polygons generated by thecontouring algorithm which reduces the rendering workload passedon to the backend and also requires slightly less RAM. It canhowever introduce rendering artifacts at chunk boundaries dependingon 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 withthe 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 aremonochrome. In that case, negative contours will instead take theirlinestyle from the negative_linestyles argument.
linestyles can also be an iterable of the above strings specifying a setof linestyles to be used. If this iterable is shorter than the number ofcontour 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 argumentspecifies the line style for negative contours.
If negative_linestyles is None, the default is taken from
rcParams["contour.negative_linestyles"]
.negative_linestyles can also be an iterable of the above stringsspecifying a set of linestyles to be used. If this iterable is shorter thanthe 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 andpolygons. The algorithms are implemented inContourPy, consult theContourPy documentation forfurther 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.
New in version 3.8.
- dataindexable object, optional
If given, all parameters also accept a string
s
, which isinterpreted asdata[s]
(unless this raises an exception).
- corner_maskbool, default:
Notes
contourf differs from the MATLAB version in that it does not drawthe polygon edges. To draw edges, add line contours with calls tocontour.
contourf fills intervals that are closed at the top; that is, forboundaries 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 tocompute contour locations. More information can be found inContourPy documentation.
Examples using matplotlib.axes.Axes.contourf
#
Contour Corner Mask
Contour Corner Mask
Contourf demo
Contourf demo
Contourf Hatching
Contourf Hatching
Contourf and log color scale
Contourf and log color scale
Contour plot of irregularly spaced data
Contour plot of irregularly spaced data
pcolormesh
pcolormesh
Triinterp Demo
Triinterp Demo
3D box surface plot
3D box surface plot
Filled contours
Filled contours
Project filled contour onto a graph
Project filled contour onto a graph
contourf(X, Y, Z)
contourf(X, Y, Z)