🌍 climatrix

---

Climatrix is a flexible toolbox for sampling and reconstructing climate datasets.

It provides utilities and an xarray accessor that simplifies the workflow of working with climate data arrays — from preprocessing to statistical sampling.

---

👤 Author

• Name: Jakub Walczak
• GitHub: @jamesWalczak
• Email: jakub.walczak@p.lodz.pl

---

👥 Contributors

• Name: Wojciech Żyndul
• GitHub: @wzyndul
• Email: 242575@edu.p.lodz.pl

---

📌 Version

Caution

This is an alpha release – features are still evolving, and breaking changes may occur.

---

📚 Table of Contents

• 🚀 Getting Started
• 📦 Installation
• ⚙️ Usage
• 🧪 Examples
• 📈 Interactive Plotting
• 🛠️ Features
• 📄 License
• 🙏 Citation

---

🚀 Getting Started

These instructions will get you a copy of the project up and running on your local machine.

git clone https://github.com/jamesWalczak/climatrix/
cd climatrix

Important

The project is now available via PyPI (pip install climatrix)

---

⚙️ Usage

Getting started and API reference are available in the official documentation.

---

🧪 Examples

🔍 Click to expand example: Accessing `climatrix` features

import climatrix as cm
import xarray as xr

my_dataset = "/file/to/netcdf.nc
cm_dset = xr.open_dataset(my_dataset).cm

📊 Click to expand example: Getting values of coordinate

import climatrix as cm
import xarray as xr

my_dataset = "/file/to/netcdf.nc"
cm_dset = xr.open_dataset(my_dataset).cm
print("Latitude values: ", cm_dset.latitude)
print("Time values: ", cm_dset.time)

📊 Subsetting by bounding box

import climatrix as cm
import xarray as xr

my_dataset = "/file/to/netcdf.nc"
cm_dset = xr.open_dataset(my_dataset).cm
europe = cm_dset.cm.subset(north=71, south=36, west=-24, east=35)

🌐 Interactive plotting

import climatrix as cm
import xarray as xr

# Load your dataset
my_dataset = "/file/to/netcdf.nc"
cm_dset = xr.open_dataset(my_dataset).cm

# Create interactive plot
plot = cm.plot.Plot(cm_dset)
plot.show()  # Opens in browser with interactive controls

---

📈 Interactive Plotting

Climatrix provides a powerful interactive plotting utility built with Plotly and Dash that creates beautiful, web-based visualizations of your climate data.

Quick Start

import climatrix as cm
import xarray as xr

# Load your climate dataset
ds = xr.open_dataset("your_data.nc")
cm_ds = ds.cm

# Create and launch interactive plot
plot = cm.plot.Plot(cm_ds)
plot.show()  # Opens in browser

Features

• 🎨 Material Design Interface: Clean, professional styling with responsive controls
• ⏰ Time Animation: Slider control for datasets with time dimensions
• 📏 Vertical Levels: Navigate through atmospheric/oceanic layers
• 🔍 Smart Visualization: Automatic selection of scatter plots for sparse data, heatmaps for dense data
• ⚡ Performance Optimized: Efficient rendering for large datasets
• 🖱️ Interactive Controls: Zoom, pan, and click-to-select regions
• 💾 Export Options: Save static HTML versions of your plots

Installation

Install the plotting dependencies:

pip install climatrix[plot]
# or manually:
pip install plotly dash

Advanced Usage

# Customize the plot
plot = cm.plot.Plot(
    dataset=cm_ds,
    port=8050,          # Custom port
    host='0.0.0.0',     # Make accessible on network
    auto_open=False,    # Don't auto-open browser
    debug=True          # Enable debug mode
)

# Save static version
plot.save_html("my_climate_plot.html")

# Launch server
plot.show()

Example Script

Run the complete demonstration:

python examples/interactive_plotting_demo.py

This creates sample datasets and demonstrates all plotting features including time series, sparse station data, and 3D atmospheric data.

---

🛠️ Features

• 🧭 Easy access to coordinate data (similar to MetPy), using regex to locate lat/lon
• 📊 Sampling of climate data, both uniformly and using normal-like distributions
• 🔁 Reconstruction via:
  • IDW (Inverse Distance Weighting)
  • Ordinary Kriging
  • SIREN (Sinusoidal INR)
  • SiNET (Spatial Interpolation NET)
• 🧪 Tools to compare reconstruction results
• 📈 Interactive plotting utilities for visualizing inputs and outputs
• 🔧 Hyperparameter Optimization via Bayesian optimization for all reconstruction methods

---

🔧 Hyperparameter Optimization

Climatrix provides automated hyperparameter optimization for all reconstruction methods using Bayesian optimization. The HParamFinder class offers an intuitive interface for finding optimal parameters.

Quick Start

from climatrix.optim import HParamFinder

# Basic usage - optimize IDW parameters
finder = HParamFinder(train_dataset, validation_dataset, method="idw")
result = finder.optimize()
best_params = result['best_params']

# Use optimized parameters for reconstruction
optimized_reconstruction = train_dataset.reconstruct(
    target=test_domain,
    method="idw", 
    **best_params
)

Advanced Usage

# Optimize specific parameters only
finder = HParamFinder(
    train_dataset, validation_dataset,
    method="sinet",
    include=["lr", "batch_size"],     # Only optimize these parameters
    exclude=["k"],                    # Or exclude specific parameters  
    metric="rmse",                    # Optimization metric (mae, mse, rmse)
    explore=0.7,                      # Exploration vs exploitation (0-1)
    n_iters=50,                       # Total optimization iterations
    random_seed=123                   # For reproducible results
)

result = finder.optimize()
print(f"Best parameters: {result['best_params']}")
print(f"Best {result['metric_name']} score: {result['best_score']}")

Installation

The hyperparameter optimization feature requires the bayesian-optimization package:

pip install climatrix[optim]

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributing

The rules for contributing on the project are described in CONTRIBUTING file in details.

---

🙏 Citation

If you are using this software in scientific work, cite us:

@article{walczak2025climatrix,
  title={Climatrix: Xarray accessor for climate data sampling and reconstruction},
  author={Walczak, Jakub and {\.Z}yndul, Wojciech},
  journal={SoftwareX},
  volume={31},
  pages={102263},
  year={2025},
  publisher={Elsevier}
}