Metadata-Version: 2.5
Name: hydrometlib
Version: 1.1.1
Summary: A trusted library of verified and referenced hydrometeorological calculations and derivations.
Project-URL: bugs, https://github.com/NERC-CEH/hydrometlib/issues
Project-URL: changelog, https://github.com/NERC-CEH/hydrometlib/releases
Project-URL: documentation, https://NERC-CEH.github.io/hydrometlib/
Project-URL: homepage, https://github.com/NERC-CEH/hydrometlib
Author-email: Richard Smith <ricsmi@ceh.ac.uk>
Maintainer-email: Richard Smith <ricsmi@ceh.ac.uk>
License: MIT License
        
        Copyright (c) 2026 UKCEH
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cosmic-ray neutron sensing,evapotranspiration,hydrology,hydrometeorology,meteorology,polars,soil moisture
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: polars>=1.42.1
Provides-Extra: numpy
Requires-Dist: numpy>=1.26; extra == 'numpy'
Provides-Extra: pandas
Requires-Dist: pandas>=2.2; extra == 'pandas'
Requires-Dist: pyarrow>=17; extra == 'pandas'
Description-Content-Type: text/markdown

[![PyPI](https://img.shields.io/pypi/v/hydrometlib.svg)](https://pypi.org/project/hydrometlib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/NERC-CEH/hydrometlib/blob/main/LICENSE)
![Language](https://img.shields.io/github/languages/top/NERC-CEH/hydrometlib)
[![tests badge](https://github.com/NERC-CEH/hydrometlib/actions/workflows/pipeline.yml/badge.svg)](https://github.com/NERC-CEH/hydrometlib/actions)
[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%9A%20online-blue)](https://nerc-ceh.github.io/hydrometlib)

# Hydrometeorology Calculation Library

A trusted library of verified and referenced hydrometeorological calculations and derivations.

## Overview

`hydrometlib` is a small collection of standard calculations used to turn raw hydrometeorological
measurements into derived quantities: net radiation, potential evapotranspiration, absolute humidity, soil moisture
from cosmic-ray neutron counts, and more. Each one is a single function you call with the data types you already have.

- **Flexible inputs**: call every function with a Polars expression, a column name, a Polars Series, a pandas Series
  or a NumPy array, and get the result back in the same form. Site attributes, such as a sensor height or latitude,
  take a plain number or a column.
- **Referenced and tested**: every calculation cites the paper or standard it comes from, and is checked against
  known-good values across all supported input types.
- **Trusted source**: developed and maintained by [UKCEH](https://www.ceh.ac.uk/) as part of the
  [Floods and Droughts Research Infrastructure (FDRI)](https://fdri.org.uk/).

See the [quick start](https://nerc-ceh.github.io/hydrometlib/getting_started/quick_start.html) for example calculations
using Polars, pandas and NumPy, and the [calculation library](https://nerc-ceh.github.io/hydrometlib/api/index.html) for
every function with its inputs, units and source.

## Installation

```bash
pip install hydrometlib
```

or with uv:

```bash
uv add hydrometlib
```

pandas and NumPy inputs need the matching extra, e.g. `pip install "hydrometlib[pandas]"`.
See the [installation guide](https://nerc-ceh.github.io/hydrometlib/getting_started/installation.html) for details.

## License

This project is licensed under the [MIT license](https://github.com/NERC-CEH/hydrometlib/blob/main/LICENSE).

## Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

1. Clone the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please make sure your code passes all tests and follows the coding style before submitting a PR.
See **developer setup** below for more information.

## Developer Setup

This is for active development on the hydrometlib package itself.

### Requirements

#### Install uv

[Official instructions](https://docs.astral.sh/uv/getting-started/installation/)

### Clone the repository

```bash
git clone https://github.com/NERC-CEH/hydrometlib.git
cd hydrometlib
```

### Setting up and activating a virtual environment

```commandline
uv sync
source .venv/bin/activate
```

### Linting
Linting uses ruff using the config in pyproject.toml
```
ruff check --fix
```

### Formatting
Formating uses ruff using the config in pyproject.toml which follows the default black settings.
```
ruff format .
```

### Testing
Testing is done using pytest and tests are in the /tests directory.
```
pytest
```

### Pre commit hooks
Run below to setup the pre-commit hooks.
```
git config --local core.hooksPath .githooks/
```
This will set this repo up to use the git hooks in the `.githooks/` directory.
The hook runs `ruff format --check` and `ruff check` to prevent commits that are not formatted correctly or have errors.
The hook intentionally does not alter the files, but informs the user which command to run.

## Documentation

For full documentation, visit https://nerc-ceh.github.io/hydrometlib/

To build the documentation locally:

```bash
# Install documentation dependencies (but they are included by default)
uv sync --group docs

# Build the documentation
cd docs
make html

# View documentation
open _build/html/index.html
```

## Citation

If you use this software, please cite it using the metadata in [`CITATION.cff`](https://github.com/NERC-CEH/hydrometlib/blob/main/CITATION.cff).

Built with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the [NERC-CEH/fdri-cookiecutter-pypackage](https://github.com/NERC-CEH/fdri-cookiecutter-pypackage) template.
