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.
⚡ Sophisticated Chunking: Advanced 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")

# Optimize chunking for time series analysis
ds = ds.climate_timeseries.optimize_chunks_advanced(
    operation_type='timeseries',
    performance_priority='balanced'
)

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

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

# Calculate trends with spatial chunking optimization
trend = ds.climate_trends.calculate_spatial_trends(
    variable="air",
    optimize_chunks=True
)

# Get chunking recommendations
ds.climate_timeseries.analyze_chunking_strategy()

📚 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",
    num_years=30
)

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: You’re reading it! 📚
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}
}