Time Series Analysis API Reference

The climate_timeseries accessor provides time series analysis capabilities for climate data.

Overview

The TimeSeries module extends xarray Datasets with a .climate_timeseries accessor that provides:

  • Time series plotting and visualization

  • Spatial standard deviation analysis

  • STL decomposition for trend and seasonal analysis

Quick Example

import xarray as xr
import climate_diagnostics

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

# Plot a time series
fig = ds.climate_timeseries.plot_time_series(
    variable="air",
    latitude=slice(30, 60)
)

Accessor Class

class climate_diagnostics.TimeSeries.TimeSeries.TimeSeriesAccessor(xarray_obj)[source]

Bases: object

Accessor for analyzing and visualizing climate time series from xarray datasets. Provides methods for extracting, processing, and visualizing time series with support for weighted spatial averaging, seasonal filtering, and time series decomposition.

__init__(xarray_obj)[source]

Initialize the accessor with a Dataset object.

plot_time_series(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', year=None, area_weighted=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Plot a time series of a spatially averaged variable.

This function selects data for a given variable, performs spatial averaging over the specified domain, and plots the resulting time series.

Parameters:

  • variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.

  • latitude (float, slice, or list, optional) – Latitude range for spatial averaging.

  • longitude (float, slice, or list, optional) – Longitude range for spatial averaging.

  • level (float, slice, or list, optional) – Vertical level selection.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • area_weighted (bool, optional) – If True, use latitude-based area weighting for the spatial mean. Defaults to True.

  • figsize (tuple, optional) – Figure size. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – If provided, the path to save the plot figure.

  • title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.

Returns:

The Axes object of the plot, or None if no data could be plotted.

Return type:

matplotlib.axes.Axes or None

plot_std_space(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', year=None, area_weighted=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Plot a time series of the spatial standard deviation of a variable.

This function calculates the standard deviation across the spatial domain for each time step and plots the resulting time series. This can be used to analyze the spatial variability of a field over time.

Parameters:

  • variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.

  • latitude (float, slice, or list, optional) – Latitude range for the calculation.

  • longitude (float, slice, or list, optional) – Longitude range for the calculation.

  • level (float, slice, or list, optional) – Vertical level selection.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • area_weighted (bool, optional) – If True, use latitude-based area weighting for the standard deviation. Defaults to True.

  • figsize (tuple, optional) – Figure size. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – If provided, the path to save the plot figure.

  • title (str or None, optional) – Custom plot title. A default title is generated if not provided.

Returns:

The Axes object of the plot, or None if no data could be plotted.

Return type:

matplotlib.axes.Axes or None

decompose_time_series(variable='air', level=None, latitude=None, longitude=None, time_range=None, season='annual', year=None, stl_seasonal=13, stl_period=12, area_weighted=True, plot_results=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Decompose a time series into trend, seasonal, and residual components using STL.

Seasonal-Trend decomposition using LOESS (STL) is a robust method for decomposing a time series. This function first creates a spatially-averaged time series and then applies the STL algorithm.

Parameters:

  • variable (str, optional) – Name of the variable to decompose. Defaults to ‘air’.

  • level (float, slice, or list, optional) – Vertical level selection.

  • latitude (float, slice, or list, optional) – Latitude range for spatial averaging.

  • longitude (float, slice, or list, optional) – Longitude range for spatial averaging.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • stl_seasonal (int, optional) – Length of the seasonal smoother for STL. Must be an odd integer. Defaults to 13.

  • stl_period (int, optional) – The period of the seasonal component. For monthly data, this is typically 12. Defaults to 12.

  • area_weighted (bool, optional) – If True, use area weighting for the spatial mean. Defaults to True.

  • plot_results (bool, optional) – If True, plot the original series and its decomposed components. Defaults to True.

  • figsize (tuple, optional) – Figure size for the plot. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – Path to save the decomposition plot.

  • title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.

Returns:

If plot_results is False, returns a dictionary containing the ‘original’, ‘trend’, ‘seasonal’, and ‘residual’ components as pandas Series. If plot_results is True, returns a tuple of (dictionary, figure object). In error cases: returns None if plot_results is False, or (None, None) if plot_results is True.

Return type:

dict or (dict, matplotlib.figure.Figure) or None or (None, None)

Available Methods

Time Series Plotting

TimeSeriesAccessor.plot_time_series(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', year=None, area_weighted=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Plot a time series of a spatially averaged variable.

This function selects data for a given variable, performs spatial averaging over the specified domain, and plots the resulting time series.

Parameters:

  • variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.

  • latitude (float, slice, or list, optional) – Latitude range for spatial averaging.

  • longitude (float, slice, or list, optional) – Longitude range for spatial averaging.

  • level (float, slice, or list, optional) – Vertical level selection.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • area_weighted (bool, optional) – If True, use latitude-based area weighting for the spatial mean. Defaults to True.

  • figsize (tuple, optional) – Figure size. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – If provided, the path to save the plot figure.

  • title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.

Returns:

The Axes object of the plot, or None if no data could be plotted.

Return type:

matplotlib.axes.Axes or None

Statistical Analysis

TimeSeriesAccessor.plot_std_space(variable='air', latitude=None, longitude=None, level=None, time_range=None, season='annual', year=None, area_weighted=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Plot a time series of the spatial standard deviation of a variable.

This function calculates the standard deviation across the spatial domain for each time step and plots the resulting time series. This can be used to analyze the spatial variability of a field over time.

Parameters:

  • variable (str, optional) – Name of the variable to plot. Defaults to ‘air’.

  • latitude (float, slice, or list, optional) – Latitude range for the calculation.

  • longitude (float, slice, or list, optional) – Longitude range for the calculation.

  • level (float, slice, or list, optional) – Vertical level selection.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • area_weighted (bool, optional) – If True, use latitude-based area weighting for the standard deviation. Defaults to True.

  • figsize (tuple, optional) – Figure size. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – If provided, the path to save the plot figure.

  • title (str or None, optional) – Custom plot title. A default title is generated if not provided.

Returns:

The Axes object of the plot, or None if no data could be plotted.

Return type:

matplotlib.axes.Axes or None

Decomposition Methods

TimeSeriesAccessor.decompose_time_series(variable='air', level=None, latitude=None, longitude=None, time_range=None, season='annual', year=None, stl_seasonal=13, stl_period=12, area_weighted=True, plot_results=True, figsize=(16, 10), save_plot_path=None, title=None)[source]

Decompose a time series into trend, seasonal, and residual components using STL.

Seasonal-Trend decomposition using LOESS (STL) is a robust method for decomposing a time series. This function first creates a spatially-averaged time series and then applies the STL algorithm.

Parameters:

  • variable (str, optional) – Name of the variable to decompose. Defaults to ‘air’.

  • level (float, slice, or list, optional) – Vertical level selection.

  • latitude (float, slice, or list, optional) – Latitude range for spatial averaging.

  • longitude (float, slice, or list, optional) – Longitude range for spatial averaging.

  • time_range (slice, optional) – Time range for the series.

  • season (str, optional) – Seasonal filter. Defaults to ‘annual’.

  • year (int, optional) – Filter for a specific year.

  • stl_seasonal (int, optional) – Length of the seasonal smoother for STL. Must be an odd integer. Defaults to 13.

  • stl_period (int, optional) – The period of the seasonal component. For monthly data, this is typically 12. Defaults to 12.

  • area_weighted (bool, optional) – If True, use area weighting for the spatial mean. Defaults to True.

  • plot_results (bool, optional) – If True, plot the original series and its decomposed components. Defaults to True.

  • figsize (tuple, optional) – Figure size for the plot. Defaults to (16, 10).

  • save_plot_path (str or None, optional) – Path to save the decomposition plot.

  • title (str, optional) – The title for the plot. If not provided, a descriptive title will be generated automatically.

Returns:

If plot_results is False, returns a dictionary containing the ‘original’, ‘trend’, ‘seasonal’, and ‘residual’ components as pandas Series. If plot_results is True, returns a tuple of (dictionary, figure object). In error cases: returns None if plot_results is False, or (None, None) if plot_results is True.

Return type:

dict or (dict, matplotlib.figure.Figure) or None or (None, None)

Basic Examples

Comprehensive Analysis Workflow

This example demonstrates a complete workflow, from optimizing data chunks to decomposition and visualization.

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

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

# 1. Create a time series plot
fig = ds.climate_timeseries.plot_time_series(
    variable="air",
    latitude=slice(30, 60),
    longitude=slice(-120, -60)
)
# 2. Decompose the time series for a specific region
decomposition = ds.climate_timeseries.decompose_time_series(
    variable="air",
    latitude=slice(30, 40),
    longitude=slice(-100, -90)
)

# 3. Plot the original and decomposed time series components
fig, ax = plt.subplots(figsize=(12, 8))
decomposition['original'].plot(ax=ax, label="Original")
decomposition['trend'].plot(ax=ax, label="Trend")
decomposition['seasonal'].plot(ax=ax, label="Seasonal")
ax.legend()
ax.set_title("Time Series Decomposition")
plt.show()

   # 4. Analyze spatial standard deviation of the original data
fig_std = ds.climate_timeseries.plot_std_space(
    variable="air",
    title="Spatial Standard Deviation of Air Temperature"
)
plt.show()

Working with Regional Data

# Calculate regional mean using utilities
from climate_diagnostics.utils import get_spatial_mean

# Select region
arctic_data = ds.sel(latitude=slice(60, 90))

# Get mean time series
arctic_ts = get_spatial_mean(arctic_data.air, area_weighted=True)

# Plot using matplotlib
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
arctic_ts.plot()
plt.title("Arctic Temperature")
plt.show()

See Also