Welcome to PyStormTracker’s documentation!
PyStormTracker is a Python package for cyclone trajectory analysis, implementing the “Simple Tracker” algorithm described in Yau and Chang (2020). It is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from Hodges (1999) (originally in C) and the Accumulated Track Activity metrics from Yau and Chang (2020) (originally in Matlab).
Initially developed at the National Center for Atmospheric Research (NCAR) as part of the 2015 SIParCS program, PyStormTracker leverages task-parallel strategies and tree reduction algorithms to efficiently and accurately process large-scale climate datasets.
Features
Modern & Typed: Strictly targets Python 3.11+ with complete type hints and strict
mypycompliance.Xarray Native: Leverages
xarrayfor robust, high-performance coordinate-aware processing, lazy data loading, and optimized I/O.Scalable Execution: Supports multiple backends:
Dask (Default): Automatically scales to utilize all available CPU cores.
MPI: Enables distributed execution across cluster nodes via
mpi4py.Serial: Standard sequential execution for debugging or small datasets.
Robust Feature Detection: Employs optimized $O(N)$ extrema filtering with robust handling of masked or missing data.
Interoperable Output: Exports tracking results to the standard IMILAST intercomparison format (
.txt) with human-readable datetime strings.
Technical Methodology
PyStormTracker treats meteorological fields as 2D images, utilizing scipy.ndimage for robust feature detection and tracking:
Local Extrema Detection: Employs an optimized sliding window filter to efficiently identify local minima (e.g., cyclones) or maxima (e.g., anticyclones, vorticity).
Intensity & Refinement: Applies the discrete Laplacian operator to measure the “sharpness” of the field at each candidate center. This metric resolves duplicate detections, ensuring only the most physically intense point is retained when adjacent pixels are flagged.
Spherical Continuity: Uses
mode='wrap'for all spatial filters to correctly handle periodic boundary conditions across the Prime Meridian, allowing for seamless global tracking.Trajectory Linking: Connects detected centers across consecutive time steps into continuous trajectories using a nearest-neighbor heuristic linking strategy.
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.
Windows Users: Note that the
griboptional dependency (viaeccodeslib) currently only supports Linux and macOS.
From PyPI (Recommended)
You can install the latest stable version of PyStormTracker directly from PyPI:
Using pip (standard):
pip install PyStormTracker
Using uv (recommended):
# For use as a CLI tool
uv tool install PyStormTracker
# For use as a library in your project
uv add PyStormTracker
From Source
Install with uv (Recommended):
git clone https://github.com/mwyau/PyStormTracker.git
cd PyStormTracker
uv sync
Usage
Once installed, you can use the stormtracker command directly:
stormtracker -i era5_msl_2025-2026_djf_2.5x2.5.nc -v msl -o my_tracks
Command Line Arguments
Argument |
Short |
Description |
|---|---|---|
|
|
Required. Path to the input NetCDF file. |
|
|
Required. Variable name to track (e.g., |
|
|
Required. Path to the output track file (appends |
|
|
Number of time steps to process. |
|
|
|
|
|
|
|
|
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
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.
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.