🌍 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

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

📚 Table of Contents

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

⚙️ Usage

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

🧪 Examples

import climatrix as cm
import xarray as xr

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

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)

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)

🛠️ 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)
• 🧪 Tools to compare reconstruction results
• 📈 Plotting utilities for visualizing inputs and outputs
• 🔧 Hyperparameter Optimization

🔧 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}
}