Metadata-Version: 2.4
Name: tctrack
Version: 0.2
Summary: A Python package for generating tropical cyclone tracks.
Author-email: Jack Atkinson <jwa34@cam.ac.uk>, Sam Avis <sa2329@cam.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Cambridge-ICCS/TCTrack
Project-URL: Repository, https://github.com/Cambridge-ICCS/TCTrack
Project-URL: Issues, https://github.com/Cambridge-ICCS/TCTrack/issues
Keywords: meteorology,weather,tropical cyclone,tracking
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Operating System :: Unix
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: h5py>=3.16.0
Requires-Dist: cf-python>=3.19.0; python_version > "3.10"
Requires-Dist: cf-python<3.19.0; python_version <= "3.10"
Requires-Dist: cftime
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: blackdoc<=0.4.2; extra == "lint"
Requires-Dist: black<=25.1.0; extra == "lint"
Requires-Dist: mypy; extra == "lint"
Requires-Dist: pytest; extra == "lint"
Provides-Extra: doc
Requires-Dist: sphinx<8.2.0; extra == "doc"
Requires-Dist: sphinx_rtd_theme; extra == "doc"
Requires-Dist: sphinx_autodoc_typehints; extra == "doc"
Requires-Dist: blackdoc<=0.4.2; extra == "doc"
Requires-Dist: black<=25.1.0; extra == "doc"
Provides-Extra: dev
Requires-Dist: tctrack[doc,lint,test]; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="https://raw.githubusercontent.com/Cambridge-ICCS/TCTrack/main/docs/images/TCTrack_Logo.svg" alt="TCTrack Logo">
</div>

# TCTrack

![GitHub License](https://img.shields.io/github/license/Cambridge-ICCS/TCTrack)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Cambridge-ICCS/TCTrack/unit-tests.yaml?label=unit-tests)
[![Documentation Status](https://readthedocs.org/projects/TCTrack/badge/?version=latest)](https://tctrack.readthedocs.io/en/latest/?badge=latest)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)


TCTrack is a Python library providing bindings to tracking algorithms for tropical
cyclones in an accessible manner to generate high-quality and
[FAIR](https://en.wikipedia.org/wiki/FAIR_data) output data.

It can be used for tracking cyclones in simulations and observations, and to compare
the output of different algorithms for a variety of data sources.


## Installation

### Dependencies
The package requires Python 3 (>=3.10).

### Package Installation
We recommend using a Conda virtual environment for TCTrack in order to simplify the
installation of dependencies (cf-python, esmpy/ESMF, UDUNITS).
```sh
conda create -n tctrack-env -c conda-forge cf-python cf-plot udunits2 esmpy
conda activate tctrack-env
```
When finished using TCTrack this can be turned off with `conda deactivate`.

TCTrack can then be installed using `pip`:
```sh
pip install tctrack
```

See the
[documentation](https://tctrack.readthedocs.io/en/latest/getting-started/index.html#installation).
for futher details about installation and dependencies, including how to install the
individual tracking algorithms.


## Using TCTrack

Details of how to use TCTrack can be found in the
[getting-started documentation online](https://tctrack.readthedocs.io/en/latest/getting-started/index.html).

New users may wish to follow the [TCTrack tutorial](https://tctrack.readthedocs.io/en/latest/getting-started/tutorial.html)
using the scripts in the [`tutorial/`](https://github.com/Cambridge-ICCS/TCTrack/tree/main/tutorial)
directory.

For a complete description of the library API see
[API documentation](https://tctrack.readthedocs.io/en/latest/api/index.html).


## Contributing

Contributions and collaborations are welcome.

For bugs, feature requests, and clear suggestions for improvement please
[open an issue](https://github.com/Cambridge-ICCS/TCTrack/issues).

If you have added something to _TCTrack_ that would be useful to others, or can
address an [open issue](https://github.com/Cambridge-ICCS/TCTrack/issues), please
[fork the repository](https://github.com/Cambridge-ICCS/TCTrack/fork) and open a
pull request.

Additional dependencies for deleopment can be installed as follows:
```sh
pip install --editable .[dev]
```

Full details for contribution and developers can be found in the
[online documentation](https://tctrack.readthedocs.io/en/latest/developer/index.html).

### Code of Conduct

Everyone participating in the _TCTrack_ project, and in particular in the
issue tracker, pull requests, and social media activity, is expected to treat other
people with respect and, more generally, to follow the guidelines articulated in the
[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).


## License

Copyright &copy; ICCS

*TCTrack* is distributed under the [GPL 3](https://github.com/Cambridge-ICCS/TCTrack/blob/main/LICENSE).


## Acknowledgments

This work was funded by a philantropic donation to the
[University of Cambridge](https://www.cam.ac.uk/) from
[INIGO Insurance](https://inigoinsurance.com/) as part of the InSPIRe project.

<p align="left">
  <img src="https://raw.githubusercontent.com/Cambridge-ICCS/TCTrack/main/docs/images/inigo_inspire.png" width="355">
</p>

The TCTrack logo was designed by [Jack Atkinson](https://jackatkinson.net/) - [@jatkinson1000](https://github.com/jatkinson1000).
