climatrix


Nameclimatrix JSON
Version 1.1a0 PyPI version JSON
download
home_pageNone
SummaryTool for climate data research
upload_time2025-10-24 12:21:12
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseNone
keywords climate data
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # 🌍 climatrix

<div align="center">

<img src="https://raw.githubusercontent.com/jamesWalczak/climatrix/0e2a3ab98836642140e50f2e59e314134c61137f/docs/assets/logo.svg" width="200" alt="Climatrix Logo">

<br>

<!-- Badges -->

<a href="https://www.python.org/downloads">
  <img src="https://img.shields.io/badge/-Python_3.12%7C3.13-blue?logo=python&logoColor=white" alt="Python Versions">
</a>
<a href="https://black.readthedocs.io/en/stable/">
  <img src="https://img.shields.io/badge/Code%20Style-Black-black.svg?labelColor=gray" alt="Code Style: Black">
</a>
<a href="https://pycqa.github.io/isort/">
  <img src="https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336" alt="Import Sort: isort">
</a>
<a href="https://github.com/jamesWalczak/climatrix/blob/main/LICENSE">
  <img src="https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray" alt="License: MIT">
</a>

</div>

______________________________________________________________________

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

It provides utilities and an [xarray](https://docs.xarray.dev/en/latest/index.html) accessor that simplifies the workflow of working with climate data arrays β€” from preprocessing to statistical sampling.

______________________________________________________________________

## πŸ‘€ Author

- **Name:** Jakub Walczak
- **GitHub:** [@jamesWalczak](https://github.com/jamesWalczak)
- **Email:** jakub.walczak@p.lodz.pl

______________________________________________________________________

## πŸ‘₯ Contributors

- **Name:** Wojciech Ε»yndul
- **GitHub:** [@wzyndul](https://github.com/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](#-getting-started)
- [πŸ“¦ Installation](#-installation)
- [βš™οΈ Usage](#%EF%B8%8F-usage)
- [πŸ§ͺ Examples](#-examples)
- [πŸ› οΈ Features](#%EF%B8%8F-features)
- [πŸ“„ License](#-license)
- [πŸ™ Citation](#-citation)

______________________________________________________________________

## βš™οΈ Usage

Getting started and API reference are available in the official [documentation](https://jameswalczak.github.io/climatrix/latest/).

______________________________________________________________________

## πŸ§ͺ Examples

<details>
<summary>πŸ” Click to expand example: Accessing `climatrix` features</summary>

```python
import climatrix as cm
import xarray as xr

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

</details>

<details>
<summary>πŸ“Š Click to expand example: Getting values of coordinate</summary>

```python
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)
```

</details>

<details>
<summary>πŸ“Š Subsetting by bounding box</summary>

```python
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)
```

</details>

______________________________________________________________________

## πŸ› οΈ 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

```python
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

```python
# 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:

```bash
pip install climatrix[optim]
```

______________________________________________________________________

## πŸ“„ License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/jamesWalczak/climatrix/blob/main/LICENSE) file for details.

## πŸ‘₯ Contributing

The rules for contributing on the project are described in [CONTRIBUTING](https://github.com/jamesWalczak/climatrix/blob/main/CONTRIBUTING.md) 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}
}
```

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "climatrix",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "climate data",
    "author": null,
    "author_email": "Jakub Walczak <jakub.walczak@p.lodz.pl>, Wojciech \u017byndul <242575@edu.p.lodz.pl>",
    "download_url": "https://files.pythonhosted.org/packages/59/56/46690051eae2232c7a7e504c2baf0a362bc706f294b9ff0013623745e1b6/climatrix-1.1a0.tar.gz",
    "platform": null,
    "description": "# \ud83c\udf0d climatrix\n\n<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/jamesWalczak/climatrix/0e2a3ab98836642140e50f2e59e314134c61137f/docs/assets/logo.svg\" width=\"200\" alt=\"Climatrix Logo\">\n\n<br>\n\n<!-- Badges -->\n\n<a href=\"https://www.python.org/downloads\">\n  <img src=\"https://img.shields.io/badge/-Python_3.12%7C3.13-blue?logo=python&logoColor=white\" alt=\"Python Versions\">\n</a>\n<a href=\"https://black.readthedocs.io/en/stable/\">\n  <img src=\"https://img.shields.io/badge/Code%20Style-Black-black.svg?labelColor=gray\" alt=\"Code Style: Black\">\n</a>\n<a href=\"https://pycqa.github.io/isort/\">\n  <img src=\"https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\" alt=\"Import Sort: isort\">\n</a>\n<a href=\"https://github.com/jamesWalczak/climatrix/blob/main/LICENSE\">\n  <img src=\"https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray\" alt=\"License: MIT\">\n</a>\n\n</div>\n\n______________________________________________________________________\n\n**Climatrix** is a flexible toolbox for sampling and reconstructing climate datasets.\n\nIt provides utilities and an [xarray](https://docs.xarray.dev/en/latest/index.html) accessor that simplifies the workflow of working with climate data arrays \u2014 from preprocessing to statistical sampling.\n\n______________________________________________________________________\n\n## \ud83d\udc64 Author\n\n- **Name:** Jakub Walczak\n- **GitHub:** [@jamesWalczak](https://github.com/jamesWalczak)\n- **Email:** jakub.walczak@p.lodz.pl\n\n______________________________________________________________________\n\n## \ud83d\udc65 Contributors\n\n- **Name:** Wojciech \u017byndul\n- **GitHub:** [@wzyndul](https://github.com/wzyndul)\n- **Email:** 242575@edu.p.lodz.pl\n\n______________________________________________________________________\n\n## \ud83d\udccc Version\n\n> **Important**\n> This is an alpha release \u2013 features are still evolving, and breaking changes may occur.\n\n______________________________________________________________________\n\n## \ud83d\udcda Table of Contents\n\n- [\ud83d\ude80 Getting Started](#-getting-started)\n- [\ud83d\udce6 Installation](#-installation)\n- [\u2699\ufe0f Usage](#%EF%B8%8F-usage)\n- [\ud83e\uddea Examples](#-examples)\n- [\ud83d\udee0\ufe0f Features](#%EF%B8%8F-features)\n- [\ud83d\udcc4 License](#-license)\n- [\ud83d\ude4f Citation](#-citation)\n\n______________________________________________________________________\n\n## \u2699\ufe0f Usage\n\nGetting started and API reference are available in the official [documentation](https://jameswalczak.github.io/climatrix/latest/).\n\n______________________________________________________________________\n\n## \ud83e\uddea Examples\n\n<details>\n<summary>\ud83d\udd0d Click to expand example: Accessing `climatrix` features</summary>\n\n```python\nimport climatrix as cm\nimport xarray as xr\n\nmy_dataset = \"/file/to/netcdf.nc\ncm_dset = xr.open_dataset(my_dataset).cm\n```\n\n</details>\n\n<details>\n<summary>\ud83d\udcca Click to expand example: Getting values of coordinate</summary>\n\n```python\nimport climatrix as cm\nimport xarray as xr\n\nmy_dataset = \"/file/to/netcdf.nc\"\ncm_dset = xr.open_dataset(my_dataset).cm\nprint(\"Latitude values: \", cm_dset.latitude)\nprint(\"Time values: \", cm_dset.time)\n```\n\n</details>\n\n<details>\n<summary>\ud83d\udcca Subsetting by bounding box</summary>\n\n```python\nimport climatrix as cm\nimport xarray as xr\n\nmy_dataset = \"/file/to/netcdf.nc\ncm_dset = xr.open_dataset(my_dataset).cm\neurope = cm_dset.cm.subset(north=71, south=36, west=-24, east=35)\n```\n\n</details>\n\n______________________________________________________________________\n\n## \ud83d\udee0\ufe0f Features\n\n- \ud83e\udded Easy access to coordinate data (similar to MetPy), using regex to locate lat/lon\n- \ud83d\udcca Sampling of climate data, both **uniformly** and using **normal-like distributions**\n- \ud83d\udd01 Reconstruction via:\n  - **IDW** (Inverse Distance Weighting)\n  - **Ordinary Kriging**\n  - **SIREN** (Sinusoidal INR)\n- \ud83e\uddea Tools to compare reconstruction results\n- \ud83d\udcc8 Plotting utilities for visualizing inputs and outputs\n- \ud83d\udd27 Hyperparameter Optimization\n\n______________________________________________________________________\n\n## \ud83d\udd27 Hyperparameter Optimization\n\nClimatrix provides automated hyperparameter optimization for all reconstruction methods using Bayesian optimization. The `HParamFinder` class offers an intuitive interface for finding optimal parameters.\n\n### Quick Start\n\n```python\nfrom climatrix.optim import HParamFinder\n\n# Basic usage - optimize IDW parameters\nfinder = HParamFinder(train_dataset, validation_dataset, method=\"idw\")\nresult = finder.optimize()\nbest_params = result['best_params']\n\n# Use optimized parameters for reconstruction\noptimized_reconstruction = train_dataset.reconstruct(\n    target=test_domain,\n    method=\"idw\", \n    **best_params\n)\n```\n\n### Advanced Usage\n\n```python\n# Optimize specific parameters only\nfinder = HParamFinder(\n    train_dataset, validation_dataset,\n    method=\"sinet\",\n    include=[\"lr\", \"batch_size\"],     # Only optimize these parameters\n    exclude=[\"k\"],                    # Or exclude specific parameters  \n    metric=\"rmse\",                    # Optimization metric (mae, mse, rmse)\n    explore=0.7,                      # Exploration vs exploitation (0-1)\n    n_iters=50,                       # Total optimization iterations\n    random_seed=123                   # For reproducible results\n)\n\nresult = finder.optimize()\nprint(f\"Best parameters: {result['best_params']}\")\nprint(f\"Best {result['metric_name']} score: {result['best_score']}\")\n```\n\n### Installation\n\nThe hyperparameter optimization feature requires the `bayesian-optimization` package:\n\n```bash\npip install climatrix[optim]\n```\n\n______________________________________________________________________\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/jamesWalczak/climatrix/blob/main/LICENSE) file for details.\n\n## \ud83d\udc65 Contributing\n\nThe rules for contributing on the project are described in [CONTRIBUTING](https://github.com/jamesWalczak/climatrix/blob/main/CONTRIBUTING.md) file in details.\n\n______________________________________________________________________\n\n## \ud83d\ude4f Citation\n\nIf you are using this software in scientific work, cite us:\n\n```\n@article{walczak2025climatrix,\n  title={Climatrix: Xarray accessor for climate data sampling and reconstruction},\n  author={Walczak, Jakub and {\\.Z}yndul, Wojciech},\n  journal={SoftwareX},\n  volume={31},\n  pages={102263},\n  year={2025},\n  publisher={Elsevier}\n}\n```\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Tool for climate data research",
    "version": "1.1a0",
    "project_urls": null,
    "split_keywords": [
        "climate",
        "data"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5fd9a30568cc0fa00b6f5bb3cb2d0843e0a6decfb13eb670ce84ad9f5a72d87d",
                "md5": "b33e491fe399e1d74b736f990417d752",
                "sha256": "0e873f8804afe1a283c6cc70e0507cd31e88826674494307e1e9440e65dfd10a"
            },
            "downloads": -1,
            "filename": "climatrix-1.1a0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b33e491fe399e1d74b736f990417d752",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 136164,
            "upload_time": "2025-10-24T12:21:10",
            "upload_time_iso_8601": "2025-10-24T12:21:10.491566Z",
            "url": "https://files.pythonhosted.org/packages/5f/d9/a30568cc0fa00b6f5bb3cb2d0843e0a6decfb13eb670ce84ad9f5a72d87d/climatrix-1.1a0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "595646690051eae2232c7a7e504c2baf0a362bc706f294b9ff0013623745e1b6",
                "md5": "0935a7c9c7218f293aeb3290ca74ba81",
                "sha256": "5b6793f8707c59532e3349fd20a96a35f78f2bb9796ae19200a57c47a6b39e25"
            },
            "downloads": -1,
            "filename": "climatrix-1.1a0.tar.gz",
            "has_sig": false,
            "md5_digest": "0935a7c9c7218f293aeb3290ca74ba81",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 6160894,
            "upload_time": "2025-10-24T12:21:12",
            "upload_time_iso_8601": "2025-10-24T12:21:12.151265Z",
            "url": "https://files.pythonhosted.org/packages/59/56/46690051eae2232c7a7e504c2baf0a362bc706f294b9ff0013623745e1b6/climatrix-1.1a0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-24 12:21:12",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "climatrix"
}
None
Elapsed time: 1.33620s