spei.plot module¶
Plotting functions for standardized indices and related drought visualizations.
- class spei.plot.Crameri(name: str)¶
Bases:
objectColormaps 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¶
Create a colormap from a list of colors.
- lajolla() Colormap¶
Lajolla colormap.
- roma() Colormap¶
Roma colormap.
- vik() Colormap¶
Vik colormap.
- spei.plot.deficit_knmi(df: DataFrame, ax: Axes | None = None, window: int = 0) Axes¶
Plot 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:
df (pandas.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).
ax (matplotlib.axes._axes.Axes, optional) – An Axes object to plot on. If None, a new figure and axes are created.
window (int, 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:
The Axes object of the generated plot.
- Return type:
matplotlib.axes._axes.Axes
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¶
Plot 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
years (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
**kwargs (dict) – Additional keyword arguments passed to the plot function for the series line.
- 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
figsize (tuple[float], optional) – Figure size, by default (6.5, 4)
fill_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
**kwargs (dict) – Additional keyword arguments passed to the plot function for the series line.
- Returns:
Axes handle
- Return type:
matplotlib.Axes