1. Basic Usage

This tutorial will get you started with the Climate Diagnostics Toolkit. You’ll learn how to load data, access the toolkit’s features, and create your first visualization.

1.1. 🚀 Getting Started

First, let’s import the necessary libraries:

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

# Import the climate diagnostics toolkit
import climate_diagnostics

1.2. 📊 Loading Climate Data

The toolkit works with xarray Datasets. Let’s start with some sample data:

# Load a climate dataset (ERA5 example)
ds = xr.open_dataset("era5_temperature.nc")

# Or create sample data for this tutorial
import numpy as np

# Create sample temperature data
lon = np.arange(0, 360, 2.5)
lat = np.arange(-90, 91, 2.5)
time = pd.date_range("2000-01-01", "2020-12-31", freq="MS")

# Generate realistic temperature data
temp_data = 15 + 20 * np.cos(np.radians(lat[None, :, None])) + \
            5 * np.random.randn(len(time), len(lat), len(lon))

ds = xr.Dataset({
    "air": (["time", "lat", "lon"], temp_data)
}, coords={
    "time": time,
    "lat": lat,
    "lon": lon
})

1.3. 🔧 Accessing Toolkit Features

Once you have a Dataset, the toolkit provides three main accessors:

  1. climate_plots - For visualizations

  2. climate_timeseries - For temporal analysis

  3. climate_trends - For trend calculations

# Check available methods
print(dir(ds.climate_plots))
print(dir(ds.climate_timeseries))
print(dir(ds.climate_trends))

1.4. � Your First Plot

Let’s create a simple temperature map:

# Plot the mean temperature
fig = ds.climate_plots.plot_mean(
    variable="air",
    title="Global Mean Temperature"
)
plt.show()

1.5. 📈 Time Series Analysis

Extract and plot a time series:

# Plot regional time series
ts = ds.climate_timeseries.plot_time_series(
    variable="air",
    latitude=slice(30, 60),
    longitude=slice(-120, -80)
)

1.6. 📊 Trend Analysis

Calculate and visualize trends:

# Calculate trend for a region
trend = ds.climate_trends.calculate_trend(
    variable="air",
    latitude=slice(40, 50),
    longitude=slice(-100, -90)
)

print(f"Temperature trend: {trend.values:.3f} units/year")

1.7. 🎯 Key Concepts

Note

xarray Integration: All toolkit features are accessed through xarray accessor methods (.climate_plots, .climate_timeseries, .climate_trends)

Tip

Data Requirements: Your data should have coordinate dimensions named ‘lat’/’latitude’, ‘lon’/’longitude’, and ‘time’ for optimal compatibility.

Warning

Memory Management: For large datasets, consider using Dask arrays or chunking your data.

1.8. 🔄 Next Steps

Now that you’ve learned the basics, you’re ready to:

1.9. 💡 Common Patterns

Here are some common usage patterns you’ll use frequently:

# Seasonal analysis
winter_mean = ds.sel(time=ds.time.dt.season == "DJF").mean("time")

# Regional subset
arctic = ds.sel(lat=slice(60, 90))

# Multi-variable analysis
for var in ["air", "prate"]:
    if var in ds.data_vars:
        fig = ds.climate_plots.plot_mean(variable=var)
        plt.show()