Metadata-Version: 2.4
Name: atmo-evaltools
Version: 2.0.3
Summary: A model evaluation Python package to assess surface atmosphere composition prediction models against in-situ observations.
Author: Météo France
License-Expression: CECILL-C
Project-URL: Documentation, https://umr-cnrm.github.io/EvalTools
Project-URL: Homepage, https://umr-cnrm.github.io/EvalTools
Keywords: air quality,model evaluation,atmosphere,CAMS,scores
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: matplotlib>=3.7
Requires-Dist: scipy>=1.10
Requires-Dist: six>=1.16
Requires-Dist: packaging>=21.0
Requires-Dist: cftime>=1.6
Provides-Extra: maps
Requires-Dist: netCDF4>=1.6; extra == "maps"
Requires-Dist: cartopy>=0.21; extra == "maps"
Requires-Dist: shapely>=1.8; extra == "maps"
Provides-Extra: doc
Requires-Dist: sphinx>=7.2; extra == "doc"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "doc"
Requires-Dist: ipython>=8.0; extra == "doc"
Provides-Extra: test
Requires-Dist: xarray>=2022.3; extra == "test"
Dynamic: license-file

# *evaltools* : a model evaluation Python package

The Python package *evaltools* is designed to assess surface atmosphere
composition prediction models with respect to in-situ observations. This
package provides different tools to compute and plot model scores. It is used
to evaluate air quality models from the Copernicus Atmosphere Monitoring
Service (CAMS).

The concept of *evaltools* is to compare observations (measured over time
at fixed lat/lon locations) with simulations (which may have a forecast
horizon of several days) computed over a period of several days. It can
therefore be used for other data types like AERONET data, but will not
handle data with a vertical component.

## Installation

The package is published on PyPI as `atmo-evaltools` (the import name stays
`evaltools`):

```bash
pip install atmo-evaltools
```

All dependencies are declared in `pyproject.toml`. To install from a checkout,
go to the package directory and execute

```bash
pip3 install .
```

This installs the core dependencies required to run evaltools. Optional
dependency groups are also available:

```bash
pip3 install ".[maps]"   # dependencies needed for plotting maps
pip3 install ".[doc]"    # dependencies needed to build the documentation
pip3 install ".[test]"   # dependencies used by the example scripts under tests/
```

The version numbers specified in `pyproject.toml` are the lower bounds that
have been used to test the library.

> **Note:** evaltools ships a compiled Cython extension
> (`evaltools/scores/_fastimpl.pyx`). Installing from source therefore requires
> a C compiler (GCC/Clang on Linux/macOS, the MSVC Build Tools on Windows).
> Installing a pre-built wheel from PyPI needs no compiler.

### Development with uv

The project is managed with [uv](https://docs.astral.sh/uv/). `uv sync` creates
the `.venv`, resolves a locked dependency set (`uv.lock`) and installs
evaltools itself (editable, with its compiled extension built):

```bash
uv sync --all-extras     # core + maps + doc + test extras
# or select extras explicitly:
uv sync --extra maps --extra test

uv run python -c "import evaltools; print(evaltools.__version__)"
```

Use `uv sync` (no flags) for just the core runtime dependencies. Building the
package during sync requires a C compiler (see the note above); on Windows
install the MSVC Build Tools.

## Building and publishing

Build a source distribution and a wheel for the current platform:

```bash
uv build            # writes dist/*.tar.gz (sdist) and dist/*.whl (wheel)
```

Because the wheel embeds a compiled extension, it is specific to the platform
and Python version it was built on. Cross-platform wheels for PyPI are built in
CI (`.github/workflows/release.yml`) with
[cibuildwheel](https://cibuildwheel.pypa.io/) across Linux, macOS and Windows
for CPython 3.10–3.13. Pushing a version tag triggers a release:

```bash
git tag v2.0.1 && git push origin v2.0.1
```

Publishing uses **PyPI Trusted Publishing** (OIDC), so no API token is stored
in the repository. One-time setup on <https://pypi.org>:

1. Log in to PyPI → *Your projects* → *Publishing* (or *Manage* → *Publishing*
   for an existing project) → *Add a new pending publisher*.
2. Fill in: PyPI Project Name `atmo-evaltools`, Owner `roeland-vito`,
   Repository `EvalTools`, Workflow `release.yml`, Environment `pypi`.
3. Save. The next `v*` tag push will publish automatically.

To rehearse the flow first, configure the same publisher on
<https://test.pypi.org> and uncomment the `repository-url` lines in the publish
step of `release.yml`.

## Documentation

Online doc of the latest release on master branch is available at
https://umr-cnrm.github.io/EvalTools

To compile html documentation, first draw the example charts with

```bash
cd tests && python3 chart_catalog.py
```
and then compile the html documentation with

```bash
cd doc && make html
```

To look at the documentation then open `doc/_build/html/index.html` with
a web navigator.

## License

Copyright Météo France (2017 - )

This software is governed by the CeCILL-C license under French law and
abiding by the rules of distribution of free software. You can use, modify
and/ or redistribute the software under the terms of the CeCILL-C license as
circulated by CEA, CNRS and INRIA at the following
URL “http://www.cecill.info”.
