iris.plot#

Iris-specific extensions to matplotlib, mimicking the matplotlib.pyplot interface.

See also: matplotlib.

class iris.plot.PlotDefn(coords, transpose)#

Bases: tuple

Create new instance of PlotDefn(coords, transpose)

coords#: Alias for field number 0

count(value, /)#: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

transpose#: Alias for field number 1

iris.plot.animate(cube_iterator, plot_func, fig=None, **kwargs)[source]#

Animate the given cube iterator.

Parameters:

cube_iterator (iterable of iris.cube.Cube objects) – Each animation frame corresponds to each iris.cube.Cube object. See iris.cube.Cube.slices().
plot_func (iris.plot or iris.quickplot plotting function) – Plotting function used to animate. Must accept the signature plot_func(cube, vmin=vmin, vmax=vmax, coords=coords). contourf(), contour(), pcolor() and pcolormesh() all conform to this signature.
fig (matplotlib.figure.Figure instance, optional) – By default, the current figure will be used or a new figure instance created if no figure is available. See matplotlib.pyplot.gcf().
coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
interval (int, float or long, optional) – Defines the time interval in milliseconds between successive frames. A default interval of 100ms is set.
vmin (int, float or long, optional) – Color scaling values, see matplotlib.colors.Normalize for further details. Default values are determined by the min-max across the data set over the entire sequence.
vmax (int, float or long, optional) – Color scaling values, see matplotlib.colors.Normalize for further details. Default values are determined by the min-max across the data set over the entire sequence.
**kwargs (dict, optional) – See matplotlib.animation.FuncAnimation for details of other valid keyword arguments.

Return type:

FuncAnimation object suitable for saving and or plotting.

Examples

>>> import iris
>>> from iris import plot as iplt
>>> from iris import quickplot as qplt
>>> my_cube = iris.load_cube(iris.sample_data_path("A1B_north_america.nc"))

To animate along a set of Cube slices :

>>> cube_iter = my_cube.slices(("longitude", "latitude"))
>>> ani = iplt.animate(cube_iter, qplt.contourf)
>>> iplt.show()

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.barbs(u_cube, v_cube, *args, **kwargs)[source]#

Draw a barb plot from two vector component cubes.

Draws a barb plot from two vector component cubes. Triangles, full-lines and half-lines represent increments of 50, 10 and 5 respectively.

Parameters:

u_cube (Cube) – u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and not map coordinate vectors. The components are aligned with the North and East of the cube coordinate system.
v_cube (Cube) – u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and not map coordinate vectors. The components are aligned with the North and East of the cube coordinate system.
coords (list of Coord or str, optional) – Coordinates or coordinate names. Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.barbs() for details of other valid keyword arguments.

Notes

Note

At present, if u_cube and v_cube have geographic coordinates, then they must be in a lat-lon coordinate system, though it may be a rotated one. To transform wind values between coordinate systems, use iris.analysis.cartography.rotate_grid_vectors(). To transform coordinate grid points, you will need to create 2-dimensional arrays of x and y values. These can be transformed with the transform_points() method of cartopy.crs.CRS.

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.citation(text, figure=None, axes=None)[source]#

Add a text citation to a plot.

Places an anchored text citation in the bottom right hand corner of the plot.

Parameters:

text (str) – Citation text to be plotted.
figure (matplotlib.figure.Figure, optional) – Target figure instance. Defaults to the current figure if none provided.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.

iris.plot.contour(cube, *args, **kwargs)[source]#

Draw contour lines based on the given Cube.

Parameters:

coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.contour() for details of other valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.contourf(cube, *args, **kwargs)[source]#

Draw filled contours based on the given Cube.

Parameters:

coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.contourf() for details of other valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.default_projection(cube)[source]#

Return the primary map projection for the given cube.

Using the returned projection, one can create a cartopy map with:

import matplotlib.pyplot as plt
ax = plt.ax(projection=default_projection(cube))

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.default_projection_extent(cube, mode=0)[source]#

Return the cube’s extents (x0, x1, y0, y1) in its default projection.

Parameters:: mode – Either iris.coords.POINT_MODE or iris.coords.BOUND_MODE Triggers whether the extent should be representative of the cell points, or the limits of the cell’s bounds. The default is iris.coords.POINT_MODE.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.fill_between(x, y1, y2, *args, **kwargs)[source]#

Plot y1 and y2 against x, and fills the space between them.

Parameters:

x (Cube or Coord) – A cube or a coordinate to plot on the x-axis.
y1 (Cube or Coord) – First cube or a coordinate to plot on the y-axis.
y2 (Cube or Coord) – Second cube or a coordinate to plot on the y-axis.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.fill_between() for details of additional valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.hist(x, *args, **kwargs)[source]#

Compute and plot a histogram.

Parameters:

x – A Cube, Coord, CellMeasure, or AncillaryVariable that will be used as the values that will be used to create the histogram. Note that if a coordinate is given, the points are used, ignoring the bounds.
**kwargs (dict, optional) – See matplotlib.pyplot.hist() for details of additional valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.orography_at_bounds(cube, facecolor='#888888', coords=None, axes=None)[source]#

Plot orography defined at cell boundaries from the given Cube.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.orography_at_points(cube, facecolor='#888888', coords=None, axes=None)[source]#

Plot orography defined at sample points from the given Cube.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.outline(cube, coords=None, color='k', linewidth=None, axes=None)[source]#

Draw cell outlines based on the given Cube.

Parameters:

coords (list of Coord objects or coordinate names) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
color (mpl color, default="k") – The color of the cell outlines. If None, the matplotlibrc setting patch.edgecolor is used by default.
linewidth (number, optional) – The width of the lines showing the cell outlines. If None, the default width in patch.linewidth in matplotlibrc is used.
axes (matplotlib.axes.Axes,voptional) – The axes to use for drawing. Defaults to the current axes if none provided.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.pcolor(cube, *args, **kwargs)[source]#

Draw a pseudocolor plot based on the given 2-dimensional Cube.

The cube must have either two 1-dimensional coordinates or two 2-dimensional coordinates with contiguous bounds to plot the cube against.

Parameters:

coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
contiguity_tolerance (float, optional) – The absolute tolerance used when checking for contiguity between the bounds of the cells. Defaults to None.
**kwargs (dict, optional) – See matplotlib.pyplot.pcolor() for details of other valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.pcolormesh(cube, *args, **kwargs)[source]#

Draw a pseudocolor plot based on the given 2-dimensional Cube.

The cube must have either two 1-dimensional coordinates or two 2-dimensional coordinates with contiguous bounds to plot against each other.

Parameters:

coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
contiguity_tolerance (float, optional) – The absolute tolerance used when checking for contiguity between the bounds of the cells. Defaults to None.
**kwargs (dict, optional) – See matplotlib.pyplot.pcolormesh() for details of other valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.plot(*args, **kwargs)[source]#

Draw a line plot based on the given cube(s) or coordinate(s).

Parameters:

axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.plot() for details of additional valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

Examples

The first one or two arguments may be cubes or coordinates to plot. Each of the following is valid:

# plot a 1d cube against its dimension coordinate
plot(cube)

# plot a 1d coordinate
plot(coord)

# plot a 1d cube against a given 1d coordinate, with the cube
# values on the y-axis and the coordinate on the x-axis
plot(coord, cube)

# plot a 1d cube against a given 1d coordinate, with the cube
# values on the x-axis and the coordinate on the y-axis
plot(cube, coord)

# plot two 1d coordinates against one-another
plot(coord1, coord2)

# plot two 1d cubes against one-another
plot(cube1, cube2)

iris.plot.points(cube, *args, **kwargs)[source]#

Draw sample point positions based on the given Cube.

Parameters:

coords (list of Coord objects or coordinate names, optional) – Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.scatter() for details of other valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.quiver(u_cube, v_cube, *args, **kwargs)[source]#

Draw an arrow plot from two vector component cubes.

Parameters:

u_cube (Cube) – u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and not map coordinate vectors. The components are aligned with the North and East of the cube coordinate system.
v_cube (Cube) – u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and not map coordinate vectors. The components are aligned with the North and East of the cube coordinate system.
coords (list of Coord or str, optional) – Coordinates or coordinate names. Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.quiver() for details of other valid keyword arguments.

Notes

Note

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.scatter(x, y, *args, **kwargs)[source]#

Draw a scatter plot based on the given cube(s) or coordinate(s).

Parameters:

x (Cube or Coord) – A cube or a coordinate to plot on the x-axis.
y (Cube or Coord) – A cube or a coordinate to plot on the y-axis.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
**kwargs (dict, optional) – See matplotlib.pyplot.scatter() for details of additional valid keyword arguments.

Notes

This function does not maintain laziness when called; it realises data. See more at Real and Lazy Data.

iris.plot.symbols(x, y, symbols, size, axes=None, units='inches')[source]#

Draw fixed-size symbols.

See iris.symbols for available symbols.

Parameters:

x (iterable) – The x coordinates where the symbols will be plotted.
y (iterable) – The y coordinates where the symbols will be plotted.
symbols (iterable) – The symbols (from iris.symbols) to plot.
size (float) – The symbol size in units.
axes (matplotlib.axes.Axes, optional) – The axes to use for drawing. Defaults to the current axes if none provided.
units (['inches', 'points'], default="inches") – The unit for the symbol size.

Notes

This function does maintain laziness when called; it doesn’t realise data. See more at Real and Lazy Data.