earthkit.plots.Figure

class earthkit.plots.Figure(rows=None, columns=None, figsize=None, domain=None, crs=None, size=None, gridspec=None, chainable=False, **kwargs)[source]

Bases: object

The overall canvas onto which subplots are drawn.

A Figure is a container for one or more Subplots, each of which can contain one or more Layers. The Figure is responsible for managing the layout of Subplots and Layers, as well as providing methods for adding common elements like legends and titles.

Parameters:

  • rows (int, optional) – The number of rows in the figure.

  • columns (int, optional) – The number of columns in the figure.

  • size (list, optional) – The size of the figure in inches. This can be a list or tuple of two floats representing the width and height of the figure.

  • domain (earthkit.geo.Domain, optional) – The domain of the data being plotted. This is used to set the extent and projection of the map.

  • crs (cartopy.crs.CRS, optional) – The CRS of the map. If not provided, it will be inferred from the domain. See https://cartopy.readthedocs.io/stable/reference/projections.html#cartopy-projections for a list of available CRSs.

  • kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.gridspec.GridSpec.

Methods

add_climatology([row, column])

Add a Climatology subplot to the figure.

add_hovmoller([row, column])

Add a Hovmoller subplot to the figure.

add_logo(logo)

Add a logo to the figure.

add_map([row, column, domain, crs])

Add a map to the figure.

add_subplot([row, column])

Add a subplot to the figure.

add_timeseries([row, column])

Add a TimeSeries subplot to the figure.

administrative_areas(*args, **kwargs)

Add administrative areas to every Map subplot.

apply_to_subplots()

Decorator to apply a method to all subplots in the figure.

attribution(attribution[, location])

Add an attribution to the figure.

block(*args, **kwargs)

Plot a pcolormesh on every subplot in the figure.

borders(*args, **kwargs)

Add country borders to every Map subplot.

cities(*args, **kwargs)

Add cities to every Map subplot.

coastlines(*args, **kwargs)

Add coastlines to every Map subplot.

contour(*args, **kwargs)

Plot contour lines on every subplot in the figure.

contourf(*args, **kwargs)

Plot filled contours on every subplot in the figure.

countries(*args, **kwargs)

Add country boundaries to every Map subplot.

distinct_legend_layers([subplots])

Get a list of layers with distinct styles.

draw()

Draw the figure and all its subplots.

format_string(string[, unique, grouped])

Format a string with the subplot titles.

grid_cells(*args, **kwargs)

Plot data as grid cells on every subplot in the figure.

gridlines(*args[, sharex, sharey])

Add gridlines to every Map subplot in the figure.

gridpoints(*args, **kwargs)

Plot grid point centroids on every subplot in the figure.

imshow(*args, **kwargs)

Plot an image on every subplot in the figure.

iterate_subplots()

Decorator to iterate simultaneously over data and subplots.

land(*args, **kwargs)

Add land polygons to every Map subplot.

legend(*args[, subplots, location])

Add legends to the figure.

line(*args, **kwargs)

Plot a line on every subplot in the figure.

multiboxplot(*args, **kwargs)

Plot a multiboxplot on every subplot in the figure.

pcolormesh(*args, **kwargs)

Plot a pseudocolor mesh on every subplot in the figure.

plot(*args, **kwargs)

Plot filled contours on every subplot in the figure.

point_cloud(*args, **kwargs)

Plot data values as a coloured point cloud on every subplot in the figure.

quickplot(*args, **kwargs)

Auto-detect the best plot type and render data on every subplot.

save(*args[, bbox_inches])

Save the figure to a file.

set_title([label])

Set the top-level title of the figure.

show(*args, **kwargs)

Display the figure.

standard_layers(*args, **kwargs)

Add standard geographic layers to every Map subplot in the figure.

stock_img(*args, **kwargs)

Add a stock background image to every Map subplot.

subplot_titles(*args, **kwargs)

Set the titles of all subplots.

timeseries(data, *args[, row, col, plot, ...])

Plot time series data across a grid of panels.

title([label, unique, grouped, y])

Add a top-level title to the chart.

urban_areas(*args, **kwargs)

Add urban areas to every Map subplot.

xlabel(*args, **kwargs)

Set the x-axis label on every subplot.

xticks(*args, **kwargs)

Set x-axis tick locations and labels on every subplot.

ylabel(*args, **kwargs)

Set the y-axis label on every subplot.

yticks(*args, **kwargs)

Set y-axis tick locations and labels on every subplot.
add_climatology(row=None, column=None, **kwargs)[source]

Add a Climatology subplot to the figure.

Returns a Climatology instance whose line() method automatically splits multi-year data by year and remaps each year onto a common Jan-to-Dec x-axis.

Parameters:

  • row (int, optional) – The row in which to place the subplot.

  • column (int, optional) – The column in which to place the subplot.

  • **kwargs – Additional keyword arguments passed to the Climatology constructor.

Return type:

Climatology

Examples

>>> fig = ekp.Figure(rows=1, columns=1)
>>> ax = fig.add_climatology()
>>> ax.line(da)
>>> fig.show()
add_hovmoller(row=None, column=None, **kwargs)[source]

Add a Hovmoller subplot to the figure.

Returns a Hovmoller instance pre-configured for Hovmöller diagrams (time on one axis, pressure/height on the other, with automatic axis inversion for pressure coordinates).

Parameters:

  • row (int, optional) – The row in which to place the subplot.

  • column (int, optional) – The column in which to place the subplot.

  • **kwargs – Additional keyword arguments passed to the Hovmoller constructor. Key options include time_axis ("x" or "y") and invert_vertical (True, False, or "auto").

Return type:

Hovmoller

Examples

>>> fig = ekp.Figure()
>>> hov = fig.add_hovmoller()
>>> hov.contourf(da, style="auto")
>>> fig.show()

Add a logo to the figure.

Parameters:

logo (str) – Either the name of a built-in logo, or a path to the logo image file to add to the figure.

add_map(row=None, column=None, domain=None, crs=None, **kwargs)[source]

Add a map to the figure.

Parameters:

  • row (int, optional) – The row in which to place the subplot.

  • column (int, optional) – The column in which to place the subplot.

  • domain (earthkit.geo.Domain, optional) – The domain of the data being plotted. This is used to set the extent and projection of the map.

  • crs (cartopy.crs.CRS, optional) – The CRS of the map. If not provided, it will be inferred from the domain or set to PlateCarree (regular lat-lon).

  • kwargs (dict, optional) – Additional keyword arguments to pass to the Map constructor.

add_subplot(row=None, column=None, **kwargs)[source]

Add a subplot to the figure.

Parameters:

  • row (int, optional) – The row in which to place the subplot.

  • column (int, optional) – The column in which to place the subplot.

  • kwargs (dict, optional) – Additional keyword arguments to pass to the Subplot constructor.

add_timeseries(row=None, column=None, **kwargs)[source]

Add a TimeSeries subplot to the figure.

Returns a TimeSeries instance pre-configured for time series visualisation (sensible default size, automatic time-axis margin removal on show/save).

Parameters:

  • row (int, optional) – The row in which to place the subplot.

  • column (int, optional) – The column in which to place the subplot.

  • kwargs (dict, optional) – Additional keyword arguments passed to the TimeSeries constructor.

Return type:

TimeSeries

Examples

>>> fig = ekp.Figure(rows=2, columns=1)
>>> ts1 = fig.add_timeseries()
>>> ts1.line(t2m_da, x="valid_time", units="celsius")
>>> ts2 = fig.add_timeseries()
>>> ts2.band(mean_da, std_da, x="valid_time", units="celsius")
>>> fig.show()
administrative_areas(*args, **kwargs)[source]

Add administrative areas to every Map subplot.

Accepts the same arguments as administrative_areas().

apply_to_subplots()[source]

Decorator to apply a method to all subplots in the figure.

attribution(attribution, location='lower center', **kwargs)[source]

Add an attribution to the figure.

Parameters:

  • attribution (str) – The attribution text to add to the figure.

  • location (str, optional) – The location of the attribution text. Accepts the same values as matplotlib legend locations: ‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’, ‘upper center’, ‘lower center’, ‘center left’, ‘center right’, ‘center’. Default is ‘lower center’.

  • **kwargs – Additional keyword arguments passed to matplotlib.figure.Figure.text.

block(*args, **kwargs)[source]

Plot a pcolormesh on every subplot in the figure.

Deprecated: Use pcolormesh() instead.

Parameters:
borders(*args, **kwargs)[source]

Add country borders to every Map subplot.

Accepts the same arguments as borders().

cities(*args, **kwargs)[source]

Add cities to every Map subplot.

Accepts the same arguments as cities().

coastlines(*args, **kwargs)[source]

Add coastlines to every Map subplot.

Accepts the same arguments as coastlines().

contour(*args, **kwargs)[source]

Plot contour lines on every subplot in the figure.

Parameters:
contourf(*args, **kwargs)[source]

Plot filled contours on every subplot in the figure.

Parameters:
countries(*args, **kwargs)[source]

Add country boundaries to every Map subplot.

Accepts the same arguments as countries().

distinct_legend_layers(subplots=None)[source]

Get a list of layers with distinct styles.

Parameters:

subplots (list, optional) – If provided, only these subplots will be considered when identifying unique styles.

draw()[source]

Draw the figure and all its subplots.

This calls matplotlib.backend_bases.FigureCanvasBase.draw() to render the figure and then resets face colors for all layers.

format_string(string, unique=True, grouped=True)[source]

Format a string with the subplot titles.

Parameters:

  • string (str) – The string to format.

  • unique (bool, optional) – If True, format keys which are uniform across subplots/layers will produce a single result. For example, if all data layers have the same variable_name, only one variable name will appear in the title.

  • grouped (bool, optional) – If True, a single title will be generated to represent all data layers, with each format key evaluating to a list where layers differ - e.g. “{variable} at {time}” might be evaluated to “temperature and wind at 2023-01-01 00:00”. If False, the title will be duplicated by the number of subplots/ layers - e.g. `”{variable} at {time}” might be evaluated to `”temperature at 2023-01-01 00:00 and wind at 2023-01-01 00:00”.

grid_cells(*args, **kwargs)[source]

Plot data as grid cells on every subplot in the figure.

For HEALPix and octahedral reduced Gaussian grids the fast pixel- sampling nnshow backends are used automatically. For other grid types, plain pcolormesh rendering is used.

Parameters:

  • data (xarray.DataArray or earthkit.data.core.Base, optional) – The data to plot.

  • x (str, array-like, or None, optional) – Explicit coordinates / values.

  • y (str, array-like, or None, optional) – Explicit coordinates / values.

  • z (str, array-like, or None, optional) – Explicit coordinates / values.

  • style (earthkit.plots.styles.Style, optional) – The Style to apply. If None, a Style is automatically generated from the data.

  • units (str, optional) – Target units for value conversion (e.g. "celsius"). See Unit conversion for examples.

  • grid (str or GridSpec, optional) – Grid specification to use for rendering. Pass "auto" (the default) to detect the grid type from the data metadata.

  • **kwargs – Additional keyword arguments forwarded to the underlying plot method.

gridlines(*args, sharex=True, sharey=True, **kwargs)[source]

Add gridlines to every Map subplot in the figure.

Parameters:

  • sharex (bool, optional) – If True, only the bottom row of subplots will have x-axis gridlines.

  • sharey (bool, optional) – If True, only the leftmost column of subplots will have y-axis gridlines.

  • kwargs (dict, optional) – Additional keyword arguments to pass to the Map.gridlines() method.

gridpoints(*args, **kwargs)[source]

Plot grid point centroids on every subplot in the figure.

Parameters:
imshow(*args, **kwargs)[source]

Plot an image on every subplot in the figure.

Parameters:
iterate_subplots()[source]

Decorator to iterate simultaneously over data and subplots.

land(*args, **kwargs)[source]

Add land polygons to every Map subplot.

Accepts the same arguments as land().

legend(*args, subplots=None, location=None, **kwargs)[source]

Add legends to the figure.

Parameters:

  • subplots (list, optional) – If provided, only these subplots will have legends.

  • location (str or list, optional) – The location of the legend. If a list, each item is the location for the corresponding subplot.

  • kwargs (dict, optional) – Additional keyword arguments to pass to the Subplot legend method.

line(*args, **kwargs)[source]

Plot a line on every subplot in the figure.

Parameters:

  • data (xarray.DataArray or array-like) – The data to plot.

  • **kwargs – Additional keyword arguments forwarded to each subplot’s line().

multiboxplot(*args, **kwargs)[source]

Plot a multiboxplot on every subplot in the figure.

Parameters:

  • data (xarray.DataArray) – The data to plot.

  • **kwargs – Additional keyword arguments forwarded to each subplot’s multiboxplot().

pcolormesh(*args, **kwargs)[source]

Plot a pseudocolor mesh on every subplot in the figure.

Parameters:
plot(*args, **kwargs)[source]

Plot filled contours on every subplot in the figure.

Parameters:
point_cloud(*args, **kwargs)[source]

Plot data values as a coloured point cloud on every subplot in the figure.

Each data point is rendered as a scatter point coloured by its value. Suitable for sparse or unstructured observation data.

Parameters:
quickplot(*args, **kwargs)[source]

Auto-detect the best plot type and render data on every subplot.

Iterates over data items and subplots simultaneously, calling quickplot() on each.

Parameters:
save(*args, bbox_inches='tight', **kwargs)[source]

Save the figure to a file.

Parameters:

  • fname (str or file-like object) – The file to which to save the figure.

  • bbox_inches (str, optional) – The bounding box in inches to use when saving the figure.

  • kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.pyplot.savefig().

set_title(label=None, **kwargs)[source]

Set the top-level title of the figure.

Alias for title() that matches the matplotlib set_title convention. Accepts the same arguments.

Parameters:

  • label (str, optional) – The title text. Can contain metadata keys in curly braces, e.g. "{variable_name}".

  • **kwargs – Additional keyword arguments forwarded to title().

show(*args, **kwargs)[source]

Display the figure.

This calls matplotlib.pyplot.show() to display the figure.

standard_layers(*args, **kwargs)[source]

Add standard geographic layers to every Map subplot in the figure.

:param Accepts the same arguments as Map.standard_layers().:

stock_img(*args, **kwargs)[source]

Add a stock background image to every Map subplot.

Accepts the same arguments as stock_img().

subplot_titles(*args, **kwargs)[source]

Set the titles of all subplots.

Parameters:

  • label (str, optional) – The text to use in the title. This text can include format keys surrounded by {} curly brackets, which will extract metadata from your plotted data layers.

  • unique (bool, optional) – If True, format keys which are uniform across subplots/layers will produce a single result. For example, if all data layers have the same variable_name, only one variable name will appear in the title. If False, each format key will evaluate to a list of values found across subplots/layers.

  • kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.pyplot.title().

timeseries(data, *args, row=None, col=None, plot='line', subplot_titles='{variable_name}', rows=None, columns=None, figsize=None, size=None, xticks=None, yticks=None, xlabel=None, ylabel=None, **kwargs)[source]

Plot time series data across a grid of panels.

A convenience wrapper around plot() that uses TimeSeries subplots and applies time-axis formatting.

When data is an xarray Dataset with more than one variable, row defaults to "variable" so each variable appears in its own row.

Parameters:

  • data (xarray.Dataset or xarray.DataArray) – The time series data to distribute across panels.

  • *args – Positional arguments forwarded to the subplot plot method.

  • row (str or None, optional) – Dimension to vary along rows. Defaults to "variable" when data is a multi-variable Dataset.

  • col (str or None, optional) – Dimension to vary along columns (e.g. a coordinate name like "step" or "number"). Default is None.

  • plot (str, optional) – Subplot method to call on each panel. Default is "line".

  • subplot_titles (str or None, optional) – Per-panel title format string. Default is "{variable_name}".

  • rows (int, optional) – Override the total number of rows.

  • columns (int, optional) – Override the total number of columns.

  • size (tuple, optional) – Figure size (width, height) in inches.

  • xticks (str or dict, optional) – Tick configuration for the x-axis of every panel.

  • yticks (str or dict, optional) – Tick configuration for the y-axis of every panel.

  • xlabel (str, optional) – x-axis label applied to every panel.

  • ylabel (str, optional) – y-axis label applied to every panel.

  • **kwargs – Additional keyword arguments forwarded to the subplot method.

Return type:

self

Examples

Multi-variable Dataset – one row per variable:

>>> fig = ekp.Figure()
>>> fig.timeseries(ds)
>>> fig.show()

Variable × step grid:

>>> fig = ekp.Figure()
>>> fig.timeseries(ds, row="variable", col="step")
>>> fig.show()
title(label=None, unique=True, grouped=True, y=None, **kwargs)[source]

Add a top-level title to the chart.

Parameters:

  • label (str, optional) – The text to use in the title. This text can include format keys surrounded by {} curly brackets, which will extract metadata from your plotted data layers.

  • unique (bool, optional) – If True, format keys which are uniform across subplots/layers will produce a single result. For example, if all data layers have the same variable_name, only one variable name will appear in the title. If False, each format key will evaluate to a list of values found across subplots/layers.

  • grouped (bool, optional) – If True, a single title will be generated to represent all data layers, with each format key evaluating to a list where layers differ - e.g. “{variable} at {time}” might be evaluated to “temperature and wind at 2023-01-01 00:00”. If False, the title will be duplicated by the number of subplots/ layers - e.g. `”{variable} at {time}” might be evaluated to `”temperature at 2023-01-01 00:00 and wind at 2023-01-01 00:00”.

  • kwargs (dict, optional) – Additional keyword arguments to pass to matplotlib.pyplot.suptitle().

urban_areas(*args, **kwargs)[source]

Add urban areas to every Map subplot.

Accepts the same arguments as urban_areas().

xlabel(*args, **kwargs)[source]

Set the x-axis label on every subplot.

Forwards all arguments to each subplot’s Subplot.xlabel() method, which ultimately calls matplotlib.axes.Axes.set_xlabel().

xticks(*args, **kwargs)[source]

Set x-axis tick locations and labels on every subplot.

Forwards all arguments to each subplot’s Subplot.xticks() method. See xticks() for the full parameter list.

ylabel(*args, **kwargs)[source]

Set the y-axis label on every subplot.

Forwards all arguments to each subplot’s Subplot.ylabel() method, which ultimately calls matplotlib.axes.Axes.set_ylabel().

yticks(*args, **kwargs)[source]

Set y-axis tick locations and labels on every subplot.

Forwards all arguments to each subplot’s Subplot.yticks() method. See yticks() for the full parameter list.