earthkit.plots.Style

class earthkit.plots.Style(colors='plasma', levels=None, gradients=None, normalize=True, units=None, scale_factor=None, units_label=None, legend_style='colorbar', legend_kwargs=None, categories=None, ticks=None, preferred_method='contourf', resample=None, vmin=None, vmax=None, **kwargs)

Bases: object

A style for plotting data.

Parameters:

• colors (str or list or matplotlib.colors.Colormap, optional) – The colors to be used in this Style. This can be a named matplotlib colormap, a list of colors (as named CSS4 colors, hexadecimal colors or three (four)-element lists of RGB(A) values), or a pre-defined matplotlib colormap object. If not provided, the default colormap of the active schema will be used.

• levels (list or earthkit.maps.styles.levels.Levels, optional) – The levels to use in this Style. This can be a list of specific levels, or an earthkit Levels object. If not provided, some suitable levels will be generated automatically (experimental!).

• gradients (list, optional) – The number of colors to insert between each level in levels. If None, one color level will be inserted between each level.

• normalize (bool, optional) – If True (default), then the colors will be normalized over the level range.

• units (str, optional) – The units in which the levels are defined. If this Style is used with data not using the given units, then a conversion will be attempted; any data incompatible with these units will not be able to use this Style. If units are not provided, then data plotted using this Style will remain in their original units. See Unit conversion for examples.

• units_label (str, optional) – The label to use in titles and legends to represent the units of the data.

• legend_style (str, optional) – The style of legend to use by default with this style. Must be one of colorbar (default), disjoint, histogram, or None (no legend).

• bin_labels (list, optional) – A list of categorical labels for each bin in the legend.

Methods

apply_scale_factor(values)	Apply the scale factor to some values.
bandplot(ax, x, values[, colors])
bar(ax, x, y, values, *args, **kwargs)	Plot a scatter plot using this Style.
barbs(ax, x, y, u, v, *args, **kwargs)
boxplot(ax, x, values[, colors])
colorbar(*args, **kwargs)	Create a colorbar legend for this Style.
contour(ax, x, y, values, *args, **kwargs)	Plot line contours using this Style.
contourf(ax, x, y, values, *args, **kwargs)	Plot shaded contours using this Style.
convert_units(values, source_units[, short_name])	Convert some values from their source units to this Style's units.
disjoint(*args, **kwargs)	Create a disjoint legend for this Style.
from_dict(kwargs)	Create a Style from a dictionary.
imshow(ax, _x, _y, values, *args, **kwargs)	Plot an image using this Style.
legend(*args, **kwargs)	Create the default legend for this Style.
levels([data])	Generate levels specific to some data.
line(ax, x, y, values, *args, **kwargs)	Plot a scatter plot using this Style.
pcolormesh(ax, x, y, values, *args, **kwargs)	Plot a pcolormesh using this Style.
plot(*args, **kwargs)	Plot the data using the Style's defaults.
quantiles(ax, x, y, values, *args[, type, ...])	Compute and plot quantiles using this Style.
quiver(ax, x, y, u, v, *args, **kwargs)	Plot quiver arrows using this Style.
quiverkey(*args, **kwargs)	Create a quiverkey legend for this Style.
save_legend([data, label, filename, transparent])	Save a standalone image of the legend associated with this Style.
scatter(ax, x, y, values[, s])	Plot a scatter plot using this Style.
streamplot(ax, x, y, u, v, *args, **kwargs)	Plot streamlines using this Style.
stripes(ax, x, y, values, *args, **kwargs)	Plot climate stripes: one vertical colored bar per data point.
to_add_geometries_kwargs(data)	Generate add_geometries arguments required for plotting data in this Style.
to_contour_kwargs(data)	Generate contour arguments required for plotting data in this Style.
to_contourf_kwargs(data)	Generate contourf arguments required for plotting data in this Style.
to_matplotlib_kwargs(data[, extend_levels])	Generate matplotlib arguments required for plotting data in this Style.
to_pcolormesh_kwargs(data)	Generate pcolormesh arguments required for plotting data in this Style.
to_quantiles_kwargs(n[, c])
to_quiver_kwargs(data)	Generate quiver arguments required for plotting data in this Style.
to_scatter_kwargs(data)	Generate scatter arguments required for plotting data in this Style.
tricontour(ax, x, y, values, *args, **kwargs)	Plot triangulated contour lines using this Style.
tricontourf(ax, x, y, values, *args, **kwargs)	Plot triangulated shaded contours using this Style.
tripcolor(ax, x, y, values, *args, **kwargs)	Plot triangulated shaded contours using this Style.
values_to_colors(values[, data])	Convert a value or list of values to colors based on this Style.
vector(*args, **kwargs)	Create a vector legend for this Style.
with_overrides(**overrides)	Create a copy of this style with some parameters overridden.

Attributes

extend	Convenience access to 'extend' kwarg.
units	Formatted units for use in figure text.

apply_scale_factor(values)

Apply the scale factor to some values.

bar(ax, x, y, values, *args, **kwargs)

Plot a scatter plot using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.scatter.

colorbar(*args, **kwargs)

Create a colorbar legend for this Style.

contour(ax, x, y, values, *args, **kwargs)

Plot line contours using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.contour.

contourf(ax, x, y, values, *args, **kwargs)

Plot shaded contours using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.contourf.

convert_units(values, source_units, short_name='')

Convert some values from their source units to this Style’s units.

Parameters:

• values (numpy.ndarray) – The values to convert from their source units to this Style’s units.

• source_units (str) – The source units of the given values.

• short_name (str, optional) – The short name of the variable, which is used to make extra assumptions about the data’s unit covnersion (for example, temperature anomalies need special consideration when converting between Celsius and Kelvin).

disjoint(*args, **kwargs)

Create a disjoint legend for this Style.

property extend

Convenience access to ‘extend’ kwarg.

classmethod from_dict(kwargs)

Create a Style from a dictionary.

imshow(ax, _x, _y, values, *args, **kwargs)

Plot an image using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates (unused directly; pass extent= if needed).

• y (numpy.ndarray) – The y coordinates (unused directly; pass extent= if needed).

• values (numpy.ndarray) – The 2-D image array to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.imshow.

legend(*args, **kwargs)

Create the default legend for this Style.

Parameters:

• *args (list) – Arguments to be passed to the legend method.

• **kwargs (dict) – Keyword arguments to be passed to the legend method.

levels(data=None)

Generate levels specific to some data.

Parameters:

data (numpy.ndarray or xarray.DataArray or earthkit.data.core.Base) – The data for which to generate a list of levels.

Return type:

list

line(ax, x, y, values, *args, **kwargs)

Plot a scatter plot using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.scatter.

pcolormesh(ax, x, y, values, *args, **kwargs)

Plot a pcolormesh using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.pcolormesh.

plot(*args, **kwargs)

Plot the data using the Style’s defaults.

quantiles(ax, x, y, values, *args, type='band', quantiles=[0, 0.25, 0.5, 0.75, 1], **kwargs)

Compute and plot quantiles using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The coordinates of the data to be plotted.

• values (numpy.ndarray) – The data of which to compute the statistics. The computation is applied along axis 0, so the size along axis 1 must match the size of the coordinates.

• type ("box" | "band") – The type of plot used to represent the quantile ranges.

• quantiles (array_like) – Probabilities of the quantiles to compute. Values must be between 0 and 1 inclusive.

quiver(ax, x, y, u, v, *args, **kwargs)

Plot quiver arrows using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• u (numpy.ndarray) – The u-component of the data to be plotted.

• v (numpy.ndarray) – The v-component of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.quiver.

quiverkey(*args, **kwargs)

Create a quiverkey legend for this Style.

save_legend(data=None, label=None, filename='legend.png', transparent=True, **kwargs)

Save a standalone image of the legend associated with this Style.

Parameters:

• data (earthkit.data.core.Base, optional) – It can sometimes be useful to pass some data in order to automatically generate legend labels or color ranges, depending on the Style.

• label (str, optional) – The label to use for the legend. If not provided, the label will be generated automatically based on the Style’s units.

• filename (str) – The name of the file to save the legend to. The file format will be determined by the file extension (e.g., .png, .pdf, etc.). By default, the legend will be saved as a file named legend.png.

• transparent (bool, optional) – If True, the saved legend will have a transparent background. Otherwise, it will have a white background. Default is True.

• **kwargs – Additional keyword arguments to be passed to the legend method.

scatter(ax, x, y, values, s=3, *args, **kwargs)

Plot a scatter plot using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.scatter.

streamplot(ax, x, y, u, v, *args, **kwargs)

Plot streamlines using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• u (numpy.ndarray) – The u-component of the data to be plotted.

• v (numpy.ndarray) – The v-component of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.streamplot.

stripes(ax, x, y, values, *args, **kwargs)

Plot climate stripes: one vertical colored bar per data point.

Each bar spans between the midpoints of adjacent x positions, and is colored according to the y value mapped through this Style’s colormap and normalisation.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot.

• x (numpy.ndarray) – The x coordinates (e.g. time values as matplotlib date floats or numeric values).

• y (numpy.ndarray) – The data values used to determine each bar’s color.

• values (numpy.ndarray) – Unused (kept for API consistency with other Style methods).

• **kwargs – Forwarded to matplotlib.axes.Axes.broken_barh(). Common useful kwargs: ymin, ymax.

to_add_geometries_kwargs(data)

Generate add_geometries arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_contour_kwargs(data)

Generate contour arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_contourf_kwargs(data)

Generate contourf arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_matplotlib_kwargs(data, extend_levels=True)

Generate matplotlib arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_pcolormesh_kwargs(data)

Generate pcolormesh arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_quiver_kwargs(data)

Generate quiver arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

to_scatter_kwargs(data)

Generate scatter arguments required for plotting data in this Style.

Parameters:

data (numpy.ndarray) – The data to be plotted using this Style.

tricontour(ax, x, y, values, *args, **kwargs)

Plot triangulated contour lines using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.tricontour.

tricontourf(ax, x, y, values, *args, **kwargs)

Plot triangulated shaded contours using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.tricontourf.

tripcolor(ax, x, y, values, *args, **kwargs)

Plot triangulated shaded contours using this Style.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot the data.

• x (numpy.ndarray) – The x coordinates of the data to be plotted.

• y (numpy.ndarray) – The y coordinates of the data to be plotted.

• values (numpy.ndarray) – The values of the data to be plotted.

• **kwargs – Any additional arguments accepted by matplotlib.axes.Axes.tricontourf.

property units

Formatted units for use in figure text.

values_to_colors(values, data=None)

Convert a value or list of values to colors based on this Style.

Parameters:

values (float or list of floats) – The values to convert to colors on this Style’s color scale.

vector(*args, **kwargs)

Create a vector legend for this Style.

with_overrides(**overrides)

Create a copy of this style with some parameters overridden.

This method creates a new Style instance with the same configuration as the current one, but with specific parameters overridden. The original style is not modified.

Parameters:

**overrides (dict) – Keyword arguments to override in the new style. Common parameters include: - colors (or cmap): color scheme or colormap - levels: contour levels - gradients: gradient steps between levels - normalize: whether to normalize colors - units: data units - legend_style: type of legend - categories: categorical labels - ticks: tick locations

Returns:

A new Style instance with overridden parameters.

Return type:

Style

Examples

>>> style = Style(colors="viridis", levels=[0, 10, 20, 30])
>>> new_style = style.with_overrides(levels=[0, 5, 10, 15, 20])
>>> # original style is unchanged