Welcome to PyStormTracker’s documentation!

CI Documentation Status codecov PyPI version Python versions License Docker GHCR DOI

PyStormTracker implements the “Simple Tracker” algorithm for cyclone trajectory analysis in Yau and Chang (2020). Work is currently in progress to port the adaptive constraints tracking algorithm in Hodges (1999) from C to Python, and the Accumulated Track Activity metrics in Yau and Chang (2020) from Matlab to Python.

Originally developed at the National Center for Atmospheric Research (NCAR) during the 2015 SIParCS program, this package utilizes task-parallel strategies and tree reduction algorithms to efficiently process large climate datasets.

Features

  • Modern Python Support: Strictly targets Python 3.11+ with comprehensive type hints and 100% strict mypy compliance.

  • Xarray Integrated: Leverages xarray with optimized I/O, acceleration, and parallel extras for robust, high-performance coordinate-aware processing and lazy data loading.

  • Parallel Backends:

    • Dask (Default): Automatically scales to all available CPU cores on local machines.

    • MPI: Supports distributed execution via mpi4py.

    • Serial: Standard sequential execution for smaller datasets or debugging.

  • Robust Detection: Optimized $O(N)$ extrema filtering and robust handling of masked/missing data.

  • CI/CD Integrated: Automated linting, type-checking, and code coverage reporting via GitHub Actions.

  • Standardized Output: Results are exported to the IMILAST intercomparison format (.txt) with readable datetime strings and formatted numeric values.

Technical Methodology

PyStormTracker treats meteorological fields as 2D images and leverages scipy.ndimage for robust feature detection:

  • Local Extrema Detection: Uses an optimized sliding window filter to identify local minima (cyclones) or maxima (anticyclones/vorticity).

  • Intensity & Refinement: Applies the Laplacian operator (laplace) to measure the “sharpness” of the field at each detected center point. This is used to resolve duplicates and ensure only the most physically intense point is kept when multiple adjacent pixels are flagged.

  • Spherical Continuity: Utilizes mode='wrap' for all filters to correctly handle periodic boundaries across the Prime Meridian, enabling seamless tracking across the entire globe.

  • Heuristic Linking: Implements a nearest-neighbor linking strategy to connect detected centers into trajectories across successive time steps.

Documentation

Full documentation, including API references and advanced usage examples, is available at pystormtracker.readthedocs.io.

Installation

Prerequisites

  • Python 3.11+

  • (Optional) OpenMPI for MPI support.

From Source

  1. Install with uv (Recommended):

    git clone https://github.com/mwyau/PyStormTracker.git
cd PyStormTracker
uv sync --group dev
uv run pre-commit install --hook-type pre-push

Usage

Once installed, you can use the stormtracker command directly:

stormtracker -i era5_msl_2.5x2.5.nc -v msl -o my_tracks

Command Line Arguments

Argument

Short

Description

--input

-i

Required. Path to the input NetCDF file.

--var

-v

Required. Variable name to track (e.g., msl, vo).

--output

-o

Required. Path to the output track file (appends .txt if missing).

--num

-n

Number of time steps to process.

--mode

-m

min (default) for low pressure, max for vorticity/high pressure.

--backend

-b

dask (default), serial, or mpi.

--workers

-w

Number of Dask workers (defaults to CPU core count).

Development

Setup

Using uv is the recommended way to set up your environment:

# Install dependencies and sync virtual environment
uv sync --group dev

# Install pre-push hooks
uv run pre-commit install --hook-type pre-push

Quality Control

Run automated checks using uv run:

Linting & Formatting:

uv run ruff check . --fix
uv run ruff format .

Type Checking:

uv run mypy src/

Tiered Testing

To keep development cycles fast, testing is tiered:

  • Fast Tests: Default local runs (skips integration tests).

  • Integration Tests: ONLY long-running integration/regression tests.

  • Full Suite: Everything (used in CI).

Run fast unit tests only (Default):

uv run pytest

Run ONLY integration tests:

uv run pytest --run-integration

Run everything:

uv run pytest --run-all

Citations

If you use this software in your research, please cite the following:

  • Yau, A. M. W., 2026: mwyau/PyStormTracker. Zenodo, https://doi.org/10.5281/zenodo.18764813.

  • Yau, A. M. W., and E. K. M. Chang, 2020: Finding Storm Track Activity Metrics That Are Highly Correlated with Weather Impacts. Part I: Frameworks for Evaluation and Accumulated Track Activity. J. Climate, 33, 10169–10186, https://doi.org/10.1175/JCLI-D-20-0393.1.

References

  • Yau, A. M. W., K. Paul and J. Dennis, 2016: PyStormTracker: A Parallel Object-Oriented Cyclone Tracker in Python. 96th American Meteorological Society Annual Meeting, New Orleans, LA. Zenodo, https://doi.org/10.5281/zenodo.18868625.

  • Neu, U., et al., 2013: IMILAST: A Community Effort to Intercompare Extratropical Cyclone Detection and Tracking Algorithms. Bull. Amer. Meteor. Soc., 94, 529–547, https://doi.org/10.1175/BAMS-D-11-00154.1.

    • IMILAST Intercomparison Protocol: https://proclim.scnat.ch/en/activities/project_imilast/intercomparison

    • IMILAST Data Download: https://proclim.scnat.ch/en/activities/project_imilast/data_download

  • Hodges, K. I., 1999: Adaptive Constraints for Feature Tracking. Mon. Wea. Rev., 127, 1362–1373, https://doi.org/10.1175/1520-0493(1999)127<1362:ACFFT>2.0.CO;2.

License

This project is licensed under the BSD-3-Clause terms found in the LICENSE file.

Resources

Indices and tables