maps.charts

Submodules

Package Contents

Classes

Chart

The top-level container for all plot elements.
class maps.charts.Chart(domain=None, domain_crs=None, crs=None, rows=None, columns=None)

The top-level container for all plot elements.

Parameters:

  • domain (str or list or earthkit.maps.domains.Domain, optional) – A named domain, or a list of domain extents in the order [x_min, x_max, y_min, y_max], describing the domain tp be used by all subplots in the Chart. If not provided, an automatic domain will be created based on the extents of any data plotted on the Chart (global if no data is plotted).

  • domain_crs (str or cartopy.crs.CRS, optional) – The coordinate reference system in which the domain extents are defined. By default, a regular equirectangular latitude-longitude CRS (Plate Carrée) is assumed.

  • crs (str or cartopy.crs.CRS, optional) – The coordinate reference system to use for all subplots on this Chart. If not provided, a suitable coordinate-reference system will be created based on the Chart’s domain.

  • rows (int, optional) – The number of rows to use for subplots on this Chart.

  • columns (int, optional) – The number of columns to use for subplots on this Chart.

property columns

The number of columns in the Chart’s subplot layout.

property fig

The Chart’s underlying matplotlib Figure object.

property gridspec

The Chart’s underlying matplotlib GridSpec object.

property rows

The number of rows in the Chart’s subplot layout.

property shape

The shape of the Chart’s subplot layout.

MAX_COLS = 8

The default maximum number of subplot columns - can be overridded by instantiating a Chart with the columns argument.

add_subplot(*args, data=None, domain=None, crs=None, row=None, column=None, **kwargs)

Add a subplot within the Chart’s subplot layout.

Parameters:

  • data (earthkit.data.core.Base, optional) – If provided, generate a subplot with a domain and CRS based on the extents of the input data.

  • domain (str or list or earthkit.maps.domains.Domain, optional) – A named domain, or a list of domain extents in the order [x_min, x_max, y_min, y_max], describing the domain tp be used by all subplots in the Chart. If not provided, the top-level Chart’s domain will be used.

  • domain_crs (str or cartopy.crs.CRS, optional) – The coordinate reference system in which the domain extents are defined. By default, a regular equirectangular latitude-longitude CRS (Plate Carrée) is assumed.

  • crs (str or cartopy.crs.CRS, optional) – The coordinate reference system to use for all subplots on this Chart. If not provided, a suitable coordinate-reference system will be created based on the Chart’s domain.

  • rows (int, optional) – The row position at which to insert this subplot.

  • columns (int, optional) – The column position at which to insert this subplot.

barbs(*args, **kwargs)
borders(*args, **kwargs)

Add country boundaries from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

cities(*args, **kwargs)

Add cities to each subplot in the Chart.

Parameters:

  • density (str, optional) – The density of cities to plot. One of “low”, “medium” or “high”.

  • capitals_only (bool, optional) – If True, only capital cities will be plotted (default False).

  • adjust_labels (bool, optional, EXPERIMENTAL) – If True, an algorithm will be applied which attempts to adjust city labels to minimise overlapping. This can be very slow.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

coastlines(*args, **kwargs)

Add coastal outlines from the Natural Earth “coastline” collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

contour(*args, **kwargs)

Plot some data on this Chart using the matplotlib contour method.

Parameters:

  • data (earthkit.data.core.Base or numpy.ndarray or xarray.Dataset) – The data to plot on the chart.

  • x (numpy.ndarray, optional) – The values of the geospatial x coordinate of the data. Only required if input data is a raw numpy array of values.

  • y (numpy.ndarray, optional) – The values of the geospatial y coordinate of the data. Only required if input data is a raw numpy array of values.

  • transform (cartopy.crs.CCRS, optional) – The CRS of the source x and y values.

  • style (earthkit.maps.styles.Style, optional) – The style to use for this visualisation. If no style is passed, earthkit-maps will attempt to choose a suitable style from its built-in styles library.

  • **kwargs (dict, optional) – Extra arguments to pass to the underlying matplotlib plotting method.

contourf(*args, **kwargs)

Plot some data on this Chart using the matplotlib contourf method.

Parameters:

  • data (earthkit.data.core.Base or numpy.ndarray or xarray.Dataset) – The data to plot on the chart.

  • x (numpy.ndarray, optional) – The values of the geospatial x coordinate of the data. Only required if input data is a raw numpy array of values.

  • y (numpy.ndarray, optional) – The values of the geospatial y coordinate of the data. Only required if input data is a raw numpy array of values.

  • transform (cartopy.crs.CCRS, optional) – The CRS of the source x and y values.

  • style (earthkit.maps.styles.Style, optional) – The style to use for this visualisation. If no style is passed, earthkit-maps will attempt to choose a suitable style from its built-in styles library.

  • **kwargs (dict, optional) – Extra arguments to pass to the underlying matplotlib plotting method.

distinct_legend_layers(subplots=None)

Get a list of layers with distinct styles.

Parameters:

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

format_string(string, unique=True, grouped=True)
classmethod from_gridspec(gridspec, *args, **kwargs)

Instantiate an earthkit Chart from a matplotlib gridspec.

Parameters:

  • gridspec (matplotlib.gridspec.GridSpec) – A matplotlib grid layout which determines subplot layout.

  • *args –

  • **kwargs –

gridlines(*args, **kwargs)

Add gridlines to the chart.

Parameters:

  • xstep (float, optional) – The step/difference between each x gridline.

  • xref (float, optional) – The reference point around which to calibrate the x level range.

  • ystep (float, optional) – The step/difference between each y gridline.

  • yref (float, optional) – The reference point around which to calibrate the y level range.

Note

Any keyword arguments accepted by cartopy’s gridlines method can be used when adding gridlines.

image(*args, **kwargs)
lakes(*args, **kwargs)

Add shaded lake polygons from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

land(*args, **kwargs)

Add shaded land polygons from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

legend(*args, subplots=None, location=None, **kwargs)

Add legends to the chart for all subplots.

ocean(*args, **kwargs)

Add shaded ocean polygons from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

pcolormesh(*args, **kwargs)

Plot some data on this Chart using the matplotlib pcolormesh method.

Parameters:

  • data (earthkit.data.core.Base or numpy.ndarray or xarray.Dataset) – The data to plot on the chart.

  • x (numpy.ndarray, optional) – The values of the geospatial x coordinate of the data. Only required if input data is a raw numpy array of values.

  • y (numpy.ndarray, optional) – The values of the geospatial y coordinate of the data. Only required if input data is a raw numpy array of values.

  • transform (cartopy.crs.CCRS, optional) – The CRS of the source x and y values.

  • style (earthkit.maps.styles.Style, optional) – The style to use for this visualisation. If no style is passed, earthkit-maps will attempt to choose a suitable style from its built-in styles library.

  • **kwargs (dict, optional) – Extra arguments to pass to the underlying matplotlib plotting method.

plot(data, *args, **kwargs)

Plot some data on this Chart.

Parameters:

  • data (earthkit.data.core.Base or numpy.ndarray or xarray.Dataset) – The data to plot on the chart.

  • x (numpy.ndarray, optional) – The values of the geospatial x coordinate of the data. Only required if input data is a raw numpy array of values.

  • y (numpy.ndarray, optional) – The values of the geospatial y coordinate of the data. Only required if input data is a raw numpy array of values.

  • transform (cartopy.crs.CCRS, optional) – The CRS of the source x and y values.

  • style (earthkit.maps.styles.Style, optional) – The style to use for this visualisation. If no style is passed, earthkit-maps will attempt to choose a suitable style from its built-in styles library.

  • **kwargs (dict, optional) – Extra arguments to pass to the underlying matplotlib plotting method.

rivers(*args, **kwargs)

Add river polygons from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

save(*args, bbox_inches='tight', **kwargs)

Save the chart.

scatter(*args, **kwargs)

Plot some data on this Chart using the matplotlib scatter method.

Parameters:

  • data (earthkit.data.core.Base or numpy.ndarray or xarray.Dataset) – The data to plot on the chart.

  • x (numpy.ndarray, optional) – The values of the geospatial x coordinate of the data. Only required if input data is a raw numpy array of values.

  • y (numpy.ndarray, optional) – The values of the geospatial y coordinate of the data. Only required if input data is a raw numpy array of values.

  • transform (cartopy.crs.CCRS, optional) – The CRS of the source x and y values.

  • style (earthkit.maps.styles.Style, optional) – The style to use for this visualisation. If no style is passed, earthkit-maps will attempt to choose a suitable style from its built-in styles library.

  • **kwargs (dict, optional) – Extra arguments to pass to the underlying matplotlib plotting method.

shapes(*args, **kwargs)

Add shapes to each subplot in the Chart.

Parameters:

shapes (str or cartopy.io.shapereader.Reader) – The shapes to add to each subplot. Either a path to a shapefile, or a cartopy shape reader object.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

show(*args, **kwargs)

Display the chart.

states_provinces(*args, **kwargs)

Add state/province boundaries from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

stock_img(*args, **kwargs)
subplot_titles(*args, **kwargs)
title(label=None, unique=True, grouped=True, y=None, **kwargs)

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) – Keyword argument to matplotlib.pyplot.suptitle (see https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.suptitle.html#matplotlib-pyplot-suptitle ).

urban_areas(*args, **kwargs)

Add urban areas polygons from the Natural Earth collection.

Parameters:

resolution (str, optional) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

Note

Matplotlib keyword arguments can be used when drawing the feature. This allows standard Matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.