Climate Diagnostics Toolkit¶

A Python toolkit for analyzing and visualizing climate data from model output, reanalysis, and observations. Built on xarray, it provides specialized accessors for time series analysis, trend calculation, and spatial plotting with sophisticated disk-aware chunking optimization.

Key Features¶

xarray Integration: Access features via .climate_plots, .climate_timeseries, and .climate_trends accessors on xarray Datasets.
Advanced Chunking: Sophisticated disk-aware chunking strategies with automatic memory optimization and performance profiling.
Time Series Analysis: Extract and analyze time series with spatial averaging, seasonal filtering, and STL decomposition.
Spatial Visualization: Create climate maps with Cartopy integration and automatic coordinate detection.
Climate Indices: Calculate ETCCDI precipitation indices like Rx1day, Rx5day, wet/dry spell durations.
Dask Support: Process large datasets efficiently with built-in Dask integration and dynamic chunk optimization.

Quick Start¶

import xarray as xr
import climate_diagnostics

# Open a large climate dataset
ds = xr.open_dataset("temperature_data.nc")

# Manually optimize chunking for time series analysis
ds = ds.chunk({'time': 120, 'lat': 50, 'lon': 50})

# Create basic visualizations
ds.climate_plots.plot_mean(variable="air")

# Analyze time series
ts = ds.climate_timeseries.plot_time_series(
    variable="air",
    latitude=slice(30, 60)
)

# Calculate spatial trends
trend = ds.climate_trends.calculate_spatial_trends(
    variable="air",
    frequency="Y"
)

Documentation Contents¶

User Guide

User Guide
- Guide Sections
- What’s Covered

Examples

Examples

API Reference

API Reference

Development

Installation¶

With pip:

pip install climate_diagnostics

With conda (recommended):

conda env create -f environment.yml
conda activate climate-diagnostics
pip install -e .

Core Modules¶

Climate Plots

Geographic visualizations with Cartopy integration.

Explore Plotting API

Time Series Analysis

Temporal analysis including decomposition and trend detection.

Explore TimeSeries API

Trend Analysis

Statistical trend calculation with visualization.

Explore Trends API

Utilities

Helper functions for data processing and coordinates.

Explore Utils API

Quick Examples¶

Create a Mean Temperature Map:

# Load your data
ds = xr.open_dataset("temperature_data.nc")

# Plot mean with basic styling
fig = ds.climate_plots.plot_mean(
    variable="air",
    title="Mean Temperature"
)

Analyze Temperature Trends:

# Calculate spatial trends
trends = ds.climate_trends.calculate_spatial_trends(
    variable="air",
    frequency="Y"
)

Time Series Analysis:

# Extract regional time series
regional_ts = ds.climate_timeseries.plot_time_series(
    variable="air",
    latitude=slice(30, 60)
)

# Perform decomposition
decomp = ds.climate_timeseries.decompose_time_series(
    variable="air"
)

Contributing¶

We welcome contributions! Please see our Contributing Guide for details on:

Setting up a development environment
Code style guidelines
Testing procedures
Submitting pull requests

Support & Community¶

Documentation: Complete documentation with examples
Issues: GitHub Issues
Discussions: GitHub Discussions

Citation¶

If you use this toolkit in your research, please cite:

@software{climate_diagnostics_2025,
  title = {Climate Diagnostics Toolkit},
  author = {Chakraborty, Pranay and Muhammed, Adil I. K.},
  year = {2025},
  version = {1.1},
  url = {https://github.com/pranay-chakraborty/climate_diagnostics}
}