atmo-evaltools 2.0.3

A model evaluation Python package to assess surface atmosphere composition prediction models against in-situ observations.

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):

pip install atmo-evaltools

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

pip3 install .

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

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. uv sync creates the .venv, resolves a locked dependency set (uv.lock) and installs evaltools itself (editable, with its compiled extension built):

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:

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 across Linux, macOS and Windows for CPython 3.10–3.13. Pushing a version tag triggers a release:

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

cd tests && python3 chart_catalog.py

and then compile the html documentation with

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”.