Plotting API Reference¶

The climate_plots accessor provides plotting capabilities for climate data visualization.

Overview¶

The Plots module extends xarray Datasets with a .climate_plots accessor that provides:

Geographic visualization with automatic projections
Statistical plots (mean, standard deviation, percentiles)
Precipitation indices and extreme event analysis

Quick Example¶

import xarray as xr
import climate_diagnostics

ds = xr.open_dataset("temperature_data.nc")

# Plot mean temperature with a specific projection
fig = ds.climate_plots.plot_mean(
    variable="air",
    title="Mean Temperature",
    projection="Robinson"
)

Accessor Class¶

class climate_diagnostics.plots.plot.PlotsAccessor(xarray_obj)[source]¶

Bases: object

A custom xarray accessor for creating climate-specific visualizations.

This accessor extends xarray Dataset and DataArray objects with a .climate_plots namespace, providing a suite of plotting methods for common climate diagnostics. These methods simplify the process of selecting data, calculating indices, and generating publication-quality spatial plots.

The accessor handles common data-wrangling tasks such as: - Finding coordinate names (e.g., ‘lat’, ‘latitude’). - Subsetting data by space, time, and vertical level. - Applying seasonal filters. - Calculating standard climate indices (e.g., Rx5day, CWD). - Generating descriptive titles and labels.

Examples

>>> import xarray as xr
>>> # Assuming 'climate_diagnostics' is imported to register the accessor
>>> import climate_diagnostics
>>>
>>> # Load a dataset
>>> ds = xr.tutorial.load_dataset("air_temperature")
>>>
>>> # Generate a plot of the mean air temperature for a specific time range
>>> ds.climate_plots.plot_mean(
...     variable='air',
...     time_range=slice('2013-05', '2013-09'),
...     season='jja'
... )

__init__(xarray_obj)[source]¶: Initialize the accessor with a Dataset object.

plot_mean(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', contour=False, figsize=(16, 10), cmap='coolwarm', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]¶

Plot the temporal mean of a variable over a specified period.

Calculates and plots the mean of a given variable over the specified time, space, and level dimensions. This is a fundamental plot for understanding the basic climate state.

Parameters:

variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object (e.g., slice(30, 60)).
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice (e.g., slice(-120, -80)).
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice (e.g., slice(500, 200)) will result in the data being averaged over that level range before the temporal mean is computed.
time_range (slice, optional) – Time range for selection, specified as a slice of datetime-like objects or strings (e.g., slice(‘2000-01-01’, ‘2010-12-31’)).
season (str, optional) – Season to calculate the mean for. Supported options are ‘annual’, ‘jjas’, ‘djf’, ‘mam’, ‘son’, ‘jja’. Defaults to ‘annual’.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘coolwarm’.
land_only (bool, optional) – If True, mask out ocean areas, plotting data only over land. Defaults to False.
levels (int, optional) – Number of contour levels for the plot. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot, allowing for further customization.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_std_time: Plot the temporal standard deviation.
plot_percentile_spatial: Plot a specific temporal percentile.

Examples

>>> import xarray as xr
>>> import climate_diagnostics
>>> ds = xr.tutorial.load_dataset("air_temperature")
>>> ds.climate_plots.plot_mean(
...     variable='air',
...     level=850,
...     time_range=slice('2013-01', '2013-12'),
...     season='djf'
... )

plot_std_time(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', contour=False, figsize=(16, 10), cmap='viridis', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]¶

Plot the temporal standard deviation of a variable.

Calculates and plots the standard deviation of a given variable over time, which is a key measure of climate variability.

Parameters:

variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object (e.g., slice(30, 60)).
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice (e.g., slice(-120, -80)).
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice (e.g., slice(500, 200)) will result in the data being averaged over that level range before the standard deviation is computed.
time_range (slice, optional) – Time range for selection, specified as a slice of datetime-like objects or strings (e.g., slice(‘2000-01-01’, ‘2010-12-31’)).
season (str, optional) – Season to calculate the standard deviation for. Supported options are ‘annual’, ‘jjas’, ‘djf’, ‘mam’, ‘son’, ‘jja’. Defaults to ‘annual’.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘viridis’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_mean: Plot the temporal mean.

plot_percentile_spatial(variable='prate', percentile=95, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Blues', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]¶

Plot the spatial distribution of a temporal percentile for a variable.

Calculates a given percentile (e.g., 95th) at each grid point over the time dimension and plots the resulting map. This is useful for identifying areas with extreme values.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
percentile (int, optional) – The percentile to calculate (0-100). Defaults to 95.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object.
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice.
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice will result in the data being averaged over that range.
time_range (slice, optional) – Time range for selection as a slice of datetime-like objects or strings.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘Blues’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels for the plot. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_mean: Plot the temporal mean of a variable.

plot_annual_sum_mean(variable='prate', latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Blues', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean of the annual total precipitation (PRCPTOT index).

This function calculates the total precipitation for each year and then computes the mean of these annual totals. It is useful for visualizing changes in total precipitation over time.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘Blues’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_max_1day_precip_mean: Plot the mean annual maximum 1-day precipitation.

plot_max_1day_precip_mean(variable='prate', latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='viridis', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean of the annual maximum 1-day precipitation (Rx1day index).

This function finds the highest precipitation amount in a single day for each year, averages these maxima, and plots the result. It is useful for analyzing changes in extreme precipitation events.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘viridis’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_annual_sum_mean: Plot the mean annual total precipitation.

plot_simple_daily_intensity_mean(variable='prate', latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='YlGnBu', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean Simple Daily Intensity Index (SDII).

SDII is the total annual precipitation divided by the number of wet days (days with precipitation above 1 mm). This index provides insight into changes in precipitation patterns and intensity.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘YlGnBu’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_days_above_threshold_mean: Plot the mean annual number of days above a temperature threshold.

plot_days_above_threshold_mean(variable='tasmax', threshold=25, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Reds', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean annual number of days where a variable is above a threshold.

For temperature, this can represent “summer days” (e.g., tasmax > 25°C).

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘tasmax’.
threshold (float, optional) – Threshold value. Defaults to 25.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘Reds’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_consecutive_dry_days_max_mean: Plot the mean annual maximum number of consecutive dry days.

plot_consecutive_dry_days_max_mean(variable='prate', threshold=1, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='YlOrBr', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean of the annual maximum number of consecutive dry days (CDD).

A “dry day” is defined as a day with precipitation below a certain threshold. This index is useful for identifying changes in dry spell patterns and durations.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
threshold (float, optional) – Threshold value. Defaults to 1 mm/day (converted to appropriate units).
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘YlOrBr’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_consecutive_wet_days: Plot the mean annual maximum number of consecutive wet days.

plot_warm_spell_duration_mean(variable='tasmax', threshold=25, min_consecutive_days=6, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Oranges', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean Warm Spell Duration Index (WSDI).

WSDI is the total number of days per year that are part of a “warm spell”. A warm spell is defined as a period of at least min_consecutive_days where the temperature is above a certain threshold.

Parameters:

variable (str, optional) – Name of the temperature variable. Defaults to ‘tasmax’.
threshold (float, optional) – Temperature threshold. Defaults to 25°C.
min_consecutive_days (int, optional) – Minimum number of consecutive days to qualify as a warm spell. Defaults to 6.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘Oranges’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_cold_spell_duration_mean: Plot the mean Cold Spell Duration Index (CSDI).

plot_cold_spell_duration_mean(variable='tasmin', threshold=0, min_consecutive_days=6, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Blues', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]¶

Plot the mean Cold Spell Duration Index (CSDI).

CSDI is the total number of days per year that are part of a “cold spell”. A cold spell is defined as a period of at least min_consecutive_days where the temperature is below a certain threshold.

Parameters:

variable (str, optional) – Name of the temperature variable. Defaults to ‘tasmin’.
threshold (float, optional) – Temperature threshold. Defaults to 0°C.
min_consecutive_days (int, optional) – Minimum number of consecutive days to qualify as a cold spell. Defaults to 6.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘Blues’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_warm_spell_duration_mean: Plot the mean Warm Spell Duration Index (WSDI).

Available Plotting Methods¶

Basic Statistical Plots¶

PlotsAccessor.plot_mean(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', contour=False, figsize=(16, 10), cmap='coolwarm', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]

Plot the temporal mean of a variable over a specified period.

Calculates and plots the mean of a given variable over the specified time, space, and level dimensions. This is a fundamental plot for understanding the basic climate state.

Parameters:

variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object (e.g., slice(30, 60)).
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice (e.g., slice(-120, -80)).
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice (e.g., slice(500, 200)) will result in the data being averaged over that level range before the temporal mean is computed.
time_range (slice, optional) – Time range for selection, specified as a slice of datetime-like objects or strings (e.g., slice(‘2000-01-01’, ‘2010-12-31’)).
season (str, optional) – Season to calculate the mean for. Supported options are ‘annual’, ‘jjas’, ‘djf’, ‘mam’, ‘son’, ‘jja’. Defaults to ‘annual’.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘coolwarm’.
land_only (bool, optional) – If True, mask out ocean areas, plotting data only over land. Defaults to False.
levels (int, optional) – Number of contour levels for the plot. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot, allowing for further customization.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_std_time: Plot the temporal standard deviation.
plot_percentile_spatial: Plot a specific temporal percentile.

Examples

>>> import xarray as xr
>>> import climate_diagnostics
>>> ds = xr.tutorial.load_dataset("air_temperature")
>>> ds.climate_plots.plot_mean(
...     variable='air',
...     level=850,
...     time_range=slice('2013-01', '2013-12'),
...     season='djf'
... )

PlotsAccessor.plot_std_time(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', contour=False, figsize=(16, 10), cmap='viridis', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]

Plot the temporal standard deviation of a variable.

Calculates and plots the standard deviation of a given variable over time, which is a key measure of climate variability.

Parameters:

variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object (e.g., slice(30, 60)).
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice (e.g., slice(-120, -80)).
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice (e.g., slice(500, 200)) will result in the data being averaged over that level range before the standard deviation is computed.
time_range (slice, optional) – Time range for selection, specified as a slice of datetime-like objects or strings (e.g., slice(‘2000-01-01’, ‘2010-12-31’)).
season (str, optional) – Season to calculate the standard deviation for. Supported options are ‘annual’, ‘jjas’, ‘djf’, ‘mam’, ‘son’, ‘jja’. Defaults to ‘annual’.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘viridis’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_mean: Plot the temporal mean.

PlotsAccessor.plot_percentile_spatial(variable='prate', percentile=95, latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Blues', land_only=False, levels=30, save_plot_path=None, title=None, projection='PlateCarree')[source]

Plot the spatial distribution of a temporal percentile for a variable.

Calculates a given percentile (e.g., 95th) at each grid point over the time dimension and plots the resulting map. This is useful for identifying areas with extreme values.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
percentile (int, optional) – The percentile to calculate (0-100). Defaults to 95.
latitude (float, slice, or list, optional) – Latitude range for selection. Can be a single value, a list of values, or a slice object.
longitude (float, slice, or list, optional) – Longitude range for selection. Can be a single value, a list, or a slice.
level (float or slice, optional) – Vertical level for data selection. A single value selects the nearest level. A slice will result in the data being averaged over that range.
time_range (slice, optional) – Time range for selection as a slice of datetime-like objects or strings.
contour (bool, optional) – If True, use contour lines instead of filled contours. Defaults to False.
figsize (tuple, optional) – Figure size in inches (width, height). Defaults to (16, 10).
cmap (str, optional) – Colormap name for the plot. Defaults to ‘Blues’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels for the plot. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_mean: Plot the temporal mean of a variable.

Precipitation Indices¶

PlotsAccessor.plot_annual_sum_mean(variable='prate', latitude=None, longitude=None, level=None, time_range=None, contour=False, figsize=(16, 10), cmap='Blues', land_only=False, levels=30, save_plot_path=None, projection='PlateCarree')[source]

Plot the mean of the annual total precipitation (PRCPTOT index).

This function calculates the total precipitation for each year and then computes the mean of these annual totals. It is useful for visualizing changes in total precipitation over time.

Parameters:

variable (str, optional) – Name of the variable. Defaults to ‘prate’.
latitude (float, slice, or list, optional) – Latitude range for selection.
longitude (float, slice, or list, optional) – Longitude range for selection.
level (float or slice, optional) – Vertical level for selection. If a slice is given, data is averaged over the level range.
time_range (slice, optional) – Time range for selection.
contour (bool, optional) – Use contour lines if True. Defaults to False.
figsize (tuple, optional) – Figure size. Defaults to (16, 10).
cmap (str, optional) – Colormap. Defaults to ‘Blues’.
land_only (bool, optional) – If True, mask out ocean areas. Defaults to False.
levels (int, optional) – Number of contour levels. Defaults to 30.
save_plot_path (str or None, optional) – If provided, the path to save the plot figure to.
projection (str, optional) – The name of the cartopy projection to use. Defaults to ‘PlateCarree’.

Returns:

The Axes object of the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxes

See also

plot_max_1day_precip_mean: Plot the mean annual maximum 1-day precipitation.

Basic Examples¶

Comprehensive Plotting Workflow¶

This example demonstrates a complete workflow for creating various climate data visualizations, from basic statistical plots to specialized precipitation indices.

import xarray as xr
import matplotlib.pyplot as plt
import climate_diagnostics
import numpy as np

# Load a sample dataset
ds = xr.tutorial.load_dataset("air_temperature")

# Create a dummy precipitation variable for demonstration purposes
ds['pr'] = np.abs(ds.air.data - 273.15) / 10
ds['pr'].attrs['units'] = 'mm/day'


# 1. Plot mean temperature with a custom projection and colormap
fig1 = ds.climate_plots.plot_mean(
    variable="air",
    title="Mean Air Temperature",
    projection="Robinson",
    cmap="viridis"
)
plt.show()

# 2. Plot the maximum 1-day precipitation (a common climate index)
fig2 = ds.climate_plots.plot_rx1day(
    variable="pr",
    title="Maximum 1-Day Precipitation (Rx1day)",
    projection="PlateCarree"
)
plt.show()

# 3. Plot the 95th percentile of spatial temperature data
fig3 = ds.climate_plots.plot_percentile_spatial(
    variable="air",
    percentile=95,
    title="95th Percentile of Air Temperature"
)
plt.show()

Regional Focus¶

# Focus on a specific region
fig = ds.climate_plots.plot_mean(
    variable="air",
    latitude=slice(20, 80),
    longitude=slice(-140, 40),
    title="North Atlantic Temperature"
)

Customization Options¶

# Customize plot appearance
fig = ds.climate_plots.plot_mean(
    variable="air",
    cmap="viridis",
    figsize=(12, 8),
    levels=20,
    land_only=True,
    save_plot_path="temperature_map.png"
)

Working with Different Variables¶

# Temperature data
temp_fig = ds.climate_plots.plot_mean(variable="air")

# Precipitation data (if available)
if "prate" in ds.data_vars:
    precip_fig = ds.climate_plots.plot_annual_sum_mean(variable="prate")

# Check available variables
print("Available variables:", list(ds.data_vars))

Plotting API Reference¶

Overview¶

Quick Example¶

Accessor Class¶

Available Plotting Methods¶

Basic Statistical Plots¶

Precipitation Indices¶

Basic Examples¶

Comprehensive Plotting Workflow¶

Regional Focus¶

Customization Options¶

Working with Different Variables¶

See Also¶