climate-diagnostics 1.3.0

Production-ready climate diagnostics tools with advanced chunking optimization for analyzing and visualizing climate data

Climate Diagnostics Toolkit

A Python toolkit for analyzing, processing, and visualizing climate data from model output, reanalysis, and observations. Built on xarray, it provides specialized accessors for time series analysis, trend calculations, and spatial diagnostics with chunking optimization and parallel processing support.

Version 1.3.0 - Features a refactored architecture with centralized data processing, enhanced exception handling, and optimized performance for scientific computing workflows.

Table of Contents

• Key Features
• Installation
• Quick Start
• API Overview
• Documentation
• Contributing & Support
• Development & Testing
• License
• Citation

Key Features

• Production-Ready Architecture: Centralized data processing pipeline with robust exception handling and optimized performance.
• xarray Integration: Access features via .climate_plots, .climate_timeseries, and .climate_trends accessors on xarray Datasets.
• Chunking Optimization: Memory-efficient chunking strategies for large datasets.
• Enhanced Reliability: Specific exception handling provides clear error messages and improved debugging experience.
• Temporal Analysis: Trend detection, STL decomposition, and variability analysis.
• Spatial Visualization: Map plotting with Cartopy and custom projections.
• Statistical Diagnostics: Climate science methods including ETCCDI indices.
• Radiative Equilibrium Models: Functions for simulating radiative and radiative-convective equilibrium.
• Multi-model Analysis: Compare and evaluate climate model outputs.
• Performance: Dask-powered parallel processing for large datasets.

Installation

With pip (from PyPI)

pip install climate_diagnostics

With pip (from source)

For the latest development version:

git clone https://github.com/pranay-chakraborty/climate_diagnostics.git
cd climate_diagnostics
pip install -e .

With conda

If you prefer to manage your environment with conda, you can use the provided environment.yml file:

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

Quick Start

This example demonstrates a typical workflow for analyzing and visualizing climate data using this toolkit.

import xarray as xr
from climate_diagnostics import accessors
from climate_diagnostics.models.rce import create_rce_model

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

# 2. Calculate and plot spatial trends with a custom projection
trends = ds.climate_trends.calculate_spatial_trends(
    variable="air",
    frequency="Y",  # Annual trends
    projection="Robinson"
)

# 3. Plot the mean temperature for a specific season
fig = ds.climate_plots.plot_mean(
    variable="air", 
    season="JJA", 
    title="Mean Summer (JJA) Temperature"
)

# 4. Run a single-column Radiative-Convective Equilibrium (RCE) model
rce_model = create_rce_model(integrate_years=2)

API Overview

Accessors

• climate_plots: Geographic and statistical visualizations including:
  • plot_mean(), plot_std(), plot_percentile()
  • plot_prcptot(), plot_sdii(), plot_days_above_threshold()
  • plot_cdd(), plot_wsdi(), plot_csdi()
• climate_timeseries: Time series analysis and decomposition:
  • plot_time_series(), plot_std_space()
  • decompose_time_series()
• climate_trends: Trend calculation and significance testing:
  • calculate_trend(), calculate_spatial_trends()

Models

• create_rce_model(): Simulate radiative-convective equilibrium
• create_re_model(): Simulate pure radiative equilibrium

Example: Time Series Analysis

# Decompose a time series into trend and seasonal components
decomposition = ds.climate_timeseries.decompose_time_series(
    variable="air",
    latitude=slice(30, 40),
    longitude=slice(-100, -90)
)

Documentation

Complete Documentation

• Quick Start Guide - Get started quickly
• API Reference - Complete function documentation
• User Guide - In-depth tutorials
• Examples - Usage examples

Local Documentation Build

To build and view documentation locally:

cd docs
make html
# Open build/html/index.html in your browser

Contributing & Support

• Report Issues - Bug reports and feature requests
• Discussions - Questions and community support
• Contributing Guide - How to contribute

Development & Testing

git clone https://github.com/pranay-chakraborty/climate_diagnostics.git
cd climate_diagnostics
conda env create -f environment.yml
conda activate climate-diagnostics
pip install -e ".[dev]"
pytest

License

This project is licensed under the MIT LICENSE.

Citation

If you use Climate Diagnostics Toolkit in your research, please cite:

Chakraborty, P. (2025) & Muhammed I. K., A. (2025). Climate Diagnostics Toolkit: Tools for analyzing and visualizing climate data using xarray accessors. Version 1.3.0. https://github.com/pranay-chakraborty/climate_diagnostics

For LaTeX users:

@software{chakraborty2025climate,
  author = {Chakraborty, Pranay and Muhammed I. K., Adil},
  title = {{Climate Diagnostics Toolkit: Tools for analyzing and visualizing climate data using xarray accessors}},
  year = {2025},
  version = {1.3.0},
  publisher = {GitHub},
  url = {https://github.com/pranay-chakraborty/climate_diagnostics},
  note = {[Computer software]}
}

---

Documentation | Issues | Discussions