spei.plot module

class spei.plot.Crameri(name: str)

Bases: object

Colormaps for matplotlib, useful for drought, based on Crameri et al. (2020).

References

Crameri, F., G.E. Shephard, and P.J. Heron: The misuse of colour in science communication, Nature Communications, 11, 5444. 2020.

static cmap_from_list(colors: list[list[float]], name: str, _r: bool = False) → Colormap
lajolla() → Colormap
roma() → Colormap
vik() → Colormap
spei.plot.deficit_knmi(df: DataFrame, ax: Axes | None = None, window: int = 0) → Axes

Plots the precipitation deficit for various scenarios using the given DataFrame.

The function generates a plot that visualizes the precipitation deficit over time for different statistical measures and specific years. It includes the 5% driest years, the median, specific record years (1976 and 2018), the maximum deficit, and optionally the current year if present in the DataFrame.

Parameters:

dfpandas.DataFrame

A DataFrame where: - Rows represent time (e.g., days or months within a year). - Columns represent years (e.g., 1976, 2018, etc.). - Values represent cumulative precipitation deficit (in millimeters).

axmatplotlib.axes._axes.Axes, optional

An Axes object to plot on. If None, a new figure and axes are created.

windowint, optional

If True, applies a rolling mean over a n-day window to the median and 95th percentile. This is also done by the KNMI but not documented.

Returns:

matplotlib.axes._axes.Axes

The Axes object of the generated plot.

Notes:

  • The x-axis represents the time of year, formatted as months (April to October).

  • The y-axis represents the precipitation deficit in millimeters.

  • The plot includes a grid on the y-axis for better readability.

  • If the current year is present in the DataFrame, it is highlighted in black.

  • The maximum deficit is annotated with the range of years in the dataset.

spei.plot.heatmap(sis: list[Series], add_category: bool = False, cmap: str = 'Reds_r', vmin: float = -3.0, vmax: float = -1.0, yticklabels: list[str] | None = None, ax: Axes | None = None) → Axes

Plots multiple standardized indices on a heatmap.

Parameters:

  • sis (List[Series]) – A list of pandas Series objects, each representing a time series of SI values.

  • add_category (bool, optional) – If True, adds category labels to the colorbar. Default is False.

  • cmap (str, optional) – The colormap to use for the heatmap. Default is “Reds_r”.

  • vmin (float, optional) – The minimum value for color normalization. Default is -3.0.

  • vmax (float, optional) – The maximum value for color normalization. Default is -1.0.

  • yticklabels (List[str] or None, optional) – Custom labels for the y-axis ticks. If None, the names of the Series objects are used. Default is None.

  • ax (matplotlib Axes, optional) – A matplotlib Axes object to plot on. If None, a new figure and axes are created. Default is None.

Returns:

The matplotlib Axes object with the heatmap.

Return type:

Matplotlib Axes

References

van Mourik, J., Ruijsch, D., van der Wiel, K., Hazeleger, W., Wanders, N.: Regional drivers and characteristics of multi-year droughts. 2024

spei.plot.monthly_density(si: Series, years: list[int], months: list[int], cmap: str | Colormap = 'tab20c', ax: Axes | None = None) → Axes

Plot the monthly kernel-density estimate for a specific year.

Parameters:

  • si (pandas.Series) – Series of the standardized index

  • year (list, optional) – List of years as int

  • months (list, optional) – List of months as int, by default all months

  • cmap (str, optional) – matlotlib colormap, by default ‘tab10’

  • ax (matplotlib.Axes, optional) – Axes handle, by default None which create a new axes

Returns:

Axes handle

Return type:

matplotlib.Axes

spei.plot.si(si: Series, add_category: bool = True, figsize: tuple[float, float] = (6.5, 4.0), cmap: str | Colormap = 'seismic_r', background: bool = True, ax: Axes | None = None, **kwargs) → Axes

Plot the standardized index values as a time series.

Parameters:

  • si (pandas.Series) – Series of the standardized index

  • add_category (bool, optional) – Add the category labels to the right y-axis, by default True

  • figsize (tuple[float], optional) – Figure size, by default (6.5, 4)

  • cmap (str, optional) – Colormap for the background or line fill

  • background (bool, optional) – Color the background if True, else color the line

  • ax (matplotlib.Axes, optional) – Axes handle, by default None which create a new axes

Returns:

Axes handle

Return type:

matplotlib.Axes

spei.plot.threshold(series: Series, threshold: Series, figsize: tuple[float, float] = (6.5, 4.0), fill_color: str = 'red', ax: Axes | None = None, **kwargs) → Axes

Plot the time series with a threshold line and fill the area below the threshold.

Parameters:

  • series (pandas.Series) – Time series of the meteorological of hydrological data

  • threshold (pandas.Series) – Series of the threshold, must have the same index as series

  • color (str, optional) – Color for the fill area, by default ‘red’

  • ax (matplotlib.Axes, optional) – Axes handle, by default None which create a new axes

Returns:

Axes handle

Return type:

matplotlib.Axes