Metadata-Version: 2.4
Name: isimip-utils
Version: 2.0.0
Summary: This package contains common functionality for different ISIMIP tools.
Project-URL: Repository, https://github.com/ISI-MIP/isimip-utils
Author-email: Jochen Klar <jochen.klar@pik-potsdam.de>
Maintainer-email: Jochen Klar <jochen.klar@pik-potsdam.de>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: python-dotenv
Requires-Dist: requests
Requires-Dist: rich
Provides-Extra: all
Requires-Dist: altair[all]~=6.0; extra == 'all'
Requires-Dist: build; extra == 'all'
Requires-Dist: cftime~=1.6; extra == 'all'
Requires-Dist: geopandas~=1.1; extra == 'all'
Requires-Dist: mkdocs; extra == 'all'
Requires-Dist: mkdocs-material; extra == 'all'
Requires-Dist: mkdocstrings-python; extra == 'all'
Requires-Dist: netcdf4~=1.7; extra == 'all'
Requires-Dist: palettable~=3.3; extra == 'all'
Requires-Dist: pre-commit; extra == 'all'
Requires-Dist: pytest-cov~=7.0; extra == 'all'
Requires-Dist: pytest~=9.0; extra == 'all'
Requires-Dist: rioxarray>=0.19; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: twine; extra == 'all'
Requires-Dist: xarray>=2025.11; extra == 'all'
Provides-Extra: altair
Requires-Dist: altair[all]~=6.0; extra == 'altair'
Requires-Dist: palettable~=3.3; extra == 'altair'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings-python; extra == 'docs'
Provides-Extra: geopandas
Requires-Dist: geopandas~=1.1; extra == 'geopandas'
Requires-Dist: rioxarray>=0.19; extra == 'geopandas'
Provides-Extra: netcdf
Requires-Dist: netcdf4~=1.7; extra == 'netcdf'
Provides-Extra: pytest
Requires-Dist: pytest-cov~=7.0; extra == 'pytest'
Requires-Dist: pytest~=9.0; extra == 'pytest'
Provides-Extra: recommended
Requires-Dist: altair[all]~=6.0; extra == 'recommended'
Requires-Dist: cftime~=1.6; extra == 'recommended'
Requires-Dist: geopandas~=1.1; extra == 'recommended'
Requires-Dist: netcdf4~=1.7; extra == 'recommended'
Requires-Dist: palettable~=3.3; extra == 'recommended'
Requires-Dist: rioxarray>=0.19; extra == 'recommended'
Requires-Dist: xarray>=2025.11; extra == 'recommended'
Provides-Extra: xarray
Requires-Dist: cftime~=1.6; extra == 'xarray'
Requires-Dist: xarray>=2025.11; extra == 'xarray'
Description-Content-Type: text/markdown

ISIMIP utils
============

[![Python Version](https://img.shields.io/badge/python->=3.11-blue)](https://www.python.org/)
[![License](https://img.shields.io/github/license/ISI-MIP/isimip-utils?style=flat)](https://github.com/rdmorganiser/isimip-utils/blob/main/LICENSE)
[![CI status](https://github.com/ISI-MIP/isimip-utils/actions/workflows/ci.yaml/badge.svg)](https://github.com/ISI-MIP/isimip-utils/actions/workflows/ci.yaml)
[![Latest release](https://img.shields.io/pypi/v/isimip-utils.svg?style=flat)](https://pypi.python.org/pypi/isimip-utils/)


[ISIMIP](https://isimip.org) offers a framework for consistently projecting the impacts
of climate change across affected sectors and spatial scales. An international network
of climate-impact modellers contribute to a comprehensive and consistent picture of the
world under different climate-change scenarios.

This package contains various utility methods for use in custom scripts as well
as in different ISIMIP tools:

* [ISIMIP quality control](https://github.com/ISI-MIP/isimip-qc)
* [ISIMIP quality assurance](https://github.com/ISI-MIP/isimip-qa)
* [ISIMIP publisher](https://github.com/ISI-MIP/isimip-publisher)


The different methods are described are documented at <https://utils.isimip.org>.


Setup
-----

Using the package requires a running Python 3 on your system. The installation for different systems is covered
[here](https://utils.isimip.org/prerequisites/).

Unless you already use an environment manager (e.g. `conda` or `uv`), it is highly recommended to use a
[virtual environment](https://docs.python.org/3/library/venv.html), which can be created using:

```bash
python3 -m venv env
source env/bin/activate  # needs to be invoked in every new terminal session
```

The package itself can be installed via `pip`:

```bash
pip install isimip-utils
```

For a development setup, the repo should be cloned and installed in *editable* mode:

```bash
git clone git@github.com:ISI-MIP/isimip-utils
pip install -e isimip-utils
```


Usage
-----

Once installed, the modules can be used like any other Python library, e.g. in order to create a ISIMIP
compliant NetCDF file, you can use:

```python
from isimip_utils.xarray import init_dataset, write_dataset

time = np.arrange(0, 365, dtype=np.float64)
var = np.ones((365, 360, 720), dtype=np.float32)

attrs={
    'global': {
        'contact': 'mail@example.com'
    },
    'var': {
        'standard_name': 'var',
        'long_name': 'Variable',
        'units': '1',
    }
}

# create an xarray.Dataset
ds = init_dataset(time=time, var=var, attrs=attrs)

# write the dataset as NetCDF file
write_dataset(ds, 'output.nc')
```

Please also note our [examples page](https://utils.isimip.org/examples/) and the [API reference](https://utils.isimip.org/reference/).
