Metadata-Version: 2.4
Name: cyclophaser
Version: 2.1.0
Summary: Determine phases from extratropical cyclone life cycle
Author: Danilo Couto de Souza
Author-email: danilo.oceano@gmail.com
License: GPL-3.0-or-later
Project-URL: Documentation, https://cyclophaser.readthedocs.io/en/latest/
Project-URL: Source Code, https://github.com/daniloceano/CycloPhaser
Project-URL: Issue Tracker, https://github.com/daniloceano/CycloPhaser/issues
Keywords: cyclone,vorticity,meteorology,atmospherical sciences
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cmocean>=4.0
Requires-Dist: contourpy>=1.3
Requires-Dist: cycler>=0.12
Requires-Dist: fonttools>=4.53
Requires-Dist: iniconfig>=2.0
Requires-Dist: kiwisolver>=1.4
Requires-Dist: matplotlib>=3.9
Requires-Dist: numpy>=2.1
Requires-Dist: packaging>=24.1
Requires-Dist: pandas>=2.2
Requires-Dist: pillow>=10.4
Requires-Dist: pluggy>=1.5
Requires-Dist: pyparsing>=3.1
Requires-Dist: python-dateutil>=2.9
Requires-Dist: pytz>=2024.2
Requires-Dist: scipy>=1.14
Requires-Dist: setuptools>=72
Requires-Dist: six>=1.16
Requires-Dist: tzdata>=2024.1
Requires-Dist: wheel>=0.44
Requires-Dist: xarray>=2024.9
Provides-Extra: test
Requires-Dist: pytest>=8.3; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# CycloPhaser: A Python Package for Detecting Extratropical Cyclone Life Cycles

[![Documentation Status](https://readthedocs.org/projects/cyclophaser/badge/?version=latest)](https://cyclophaser.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://badge.fury.io/py/cyclophaser.svg)](https://badge.fury.io/py/cyclophaser)
[![PyPI Downloads](https://pepy.tech/badge/cyclophaser)](https://pepy.tech/project/cyclophaser)
[![CircleCI](https://circleci.com/gh/daniloceano/CycloPhaser.svg?style=shield)](https://circleci.com/gh/daniloceano/CycloPhaser)
[![License: GPL v3 or later](https://img.shields.io/badge/License-GPLv3%2B-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python Versions](https://img.shields.io/pypi/pyversions/cyclophaser)](https://pypi.org/project/cyclophaser/)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.07363/status.svg)](https://doi.org/10.21105/joss.07363)


CycloPhaser is a package designed to automate and improve the accuracy of detecting and categorizing cyclone life cycle phases, including intensification, maturation, and decay. Understanding these phases is crucial for analyzing cyclone behavior and the dynamic processes that drive their development. This knowledge supports both operational forecasters and researchers focused on improving cyclone representation in numerical models, ultimately enhancing forecast accuracy. Traditionally, phase identification requires manual analysis, which introduces subjectivity and limits the feasibility of analyzing large datasets. CycloPhaser addresses these challenges by offering an efficient, objective approach, compatible with high-resolution reanalysis data and real-time observations alike. With CycloPhaser, users gain a powerful tool for cyclone life cycle classification, supporting both advanced meteorological research and practical forecasting applications.

CycloPhaser is described in detail in the paper by de Souza et al. (2025) and has been used to generate results presented by de Souza et al. (2024).

![CycloPhaser Example Plot](https://github.com/daniloceano/CycloPhaser/raw/master/docs/_images/test_custom.png)

**Important Note**: CycloPhaser requires cyclone tracking data as input but does not perform cyclone tracking itself. There are various cyclone tracking algorithms available in the literature. Walker et al. (2020) provide a discussion on these methods, while open-source tracking tools, such as [CyTRACK](https://github.com/apalarcon/CyTRACK) by Pérez-Alarcón et al. (2024), are publicly accessible. Additionally, cyclone track databases, like the [Atlantic extratropical cyclone tracks database](https://data.mendeley.com/datasets/kwcvfr52hp/4) by Gramcianinov et al. (2020), are available for use.


## Installation

1. Install using pip

   ```
   pip install cyclophaser
   ```

## Documentation

For detailed documentation, visit the [CycloPhaser Documentation](https://cyclophaser.readthedocs.io/en/latest/). This includes function parameters, module descriptions, and more.

## Interactive Calibration Tool

CycloPhaser includes a visual calibration app built with [Streamlit](https://streamlit.io) that lets you tune filtering and phase-detection parameters interactively, inspect results across multiple cyclones side-by-side, and export configurations as YAML for use in your own scripts.

**This tool is not part of the PyPI package** — it is not installed by `pip install cyclophaser`. It lives in the repository under [`tools/calibration_app/`](tools/calibration_app/).

**Hosted version** (no installation required):

> <STREAMLIT_APP_URL>

**Run locally:**

```bash
# 1. Clone the repository
git clone https://github.com/daniloceano/CycloPhaser.git
cd CycloPhaser

# 2. Install app dependencies (pulls cyclophaser from PyPI)
pip install -r tools/calibration_app/requirements.txt

# 3. Launch
streamlit run tools/calibration_app/app.py
```

For local development with an editable install of CycloPhaser (changes to the source take effect immediately):

```bash
pip install -e .
pip install -r tools/calibration_app/requirements-app.txt
streamlit run tools/calibration_app/app.py
```

## Development Environment

Development on this repository (as opposed to just using the released
package) needs `cyclophaser` installed in **editable** mode, in an
environment dedicated to this repo. Installing it non-editably into an
environment shared with other projects lets `import cyclophaser` silently
resolve to a *different* installed copy depending on the current working
directory a script happens to be launched from — confirmed concretely: from
the repository root it resolves to the repository, from `/tmp` it resolves
to whichever released version is sitting in that environment's
`site-packages`. `research/labels/evaluate_against_labels.py` imports
`cyclophaser.determine_periods`, so under a shared, non-editable install the
version of the detector that scores the manual labels depends on where the
script was launched from — silently, with no error.

```bash
conda env create -f environment.yml
conda activate cyclophaser
pip install -e .
```

**Verify the editable install actually wins**, from a directory *outside*
the repository (the failure mode above only shows up off-repo):

```bash
cd /tmp && python -c "import cyclophaser, importlib.metadata as m; print(cyclophaser.__file__); print(m.version('cyclophaser'))"
```

(`cyclophaser.__version__` is not defined by the package — use
`importlib.metadata.version('cyclophaser')` instead, as above.) The printed
path must be inside this repository's `cyclophaser/` directory and the
printed version must be this repository's (`setup.py`'s `VERSION`), not
whatever else may be installed elsewhere — if either is wrong, a different
environment is active or the editable install did not take.

# Support and Contact

For support, feature requests, or any queries, please open an issue on the GitHub repository.

# License

This project is licensed under the GNU General Public License, version 3 or (at your option) any later version (GPL-3.0-or-later), as declared in `setup.py`. The licence text is in `LICENSE`; it is also available at https://www.gnu.org/licenses/gpl-3.0.html.


### References

- de Souza, D. C., da Silva Dias, P. L., Gramcianinov, C. B., & de Camargo, R. (2025). CycloPhaser: A Python Package for Detecting Extratropical Cyclone Life Cycles. *Journal of Open Source Software*, 10(108), 7363. https://doi.org/10.21105/joss.07363
  
- de Souza, D. C., da Silva Dias, P. L., Gramcianinov, C. B., da Silva, M. B. L., & de Camargo, R. (2024). New perspectives on South Atlantic storm track through an automatic method for detecting extratropical cyclones' lifecycle. *International Journal of Climatology*, 44(10), 3568-3588.

- Gramcianinov, C. B., Campos, R. M., de Camargo, R., Hodges, K. I., Guedes Soares, C., & da Silva Dias, P. L. (2020). Atlantic extratropical cyclone tracks in 41 years of ERA5 and CFSR/CFSv2 databases. *Mendeley Data*, 4, 108111.

- Pérez-Alarcón, A., Coll-Hidalgo, P., Trigo, R. M., Nieto, R., & Gimeno, L. (2024). CyTRACK: An open-source and user-friendly Python toolbox for detecting and tracking cyclones. *Environmental Modelling & Software*, 176, 106027.

- Walker, E., Mitchell, D. M., & Seviour, W. J. (2020). The numerous approaches to tracking extratropical cyclones and the challenges they present. *Weather*, 75(11), 336-341.
