PyStormTracker 0.2.2__tar.gz → 0.3.0__tar.gz

pystormtracker-0.3.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

pystormtracker-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    # Skip PR CI if the head branch is 'dev' to avoid double runs (push trigger covers it)
+    if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
+    outputs:
+      python-versions: ${{ steps.versions.outputs.value }}
+    steps:
+      - id: versions
+        run: echo 'value=["3.11", "3.12", "3.13", "3.14"]' >> $GITHUB_OUTPUT
+
+  ruff-lint:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install dependencies
+        run: pip install ruff
+      - name: Lint with Ruff
+        run: ruff check .
+
+  ruff-format:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install dependencies
+        run: pip install ruff
+      - name: Check formatting with Ruff
+        run: ruff format --check .
+
+  mypy-typecheck:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Type check with Mypy
+        run: mypy src/ tests/
+
+  unit-tests:
+    name: unit-tests (Python ${{ matrix.python-version }})
+    needs: prepare
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(needs.prepare.outputs.python-versions) }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run Unit Tests
+        run: |
+          pytest -vv
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  integration-tests:
+    name: integration-tests (Python ${{ matrix.python-version }})
+    needs: prepare
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(needs.prepare.outputs.python-versions) }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install MPI
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y openmpi-bin libopenmpi-dev
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run Integration Tests
+        run: |
+          pytest -vv tests/test_integration.py --run-all
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

pystormtracker-0.3.0/.github/workflows/docker-publish.yml

@@ -0,0 +1,70 @@
+name: Docker Publish
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+env:
+  DOCKER_HUB_REPO: xddd/pystormtracker
+  GHCR_REPO: ghcr.io/xddd/pystormtracker
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    # Only run if CI was successful AND it was a push event to main or dev
+    # Added head_repository check to prevent checkout of untrusted code in trusted context
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      (github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'workflow_dispatch') &&
+      (github.event.workflow_run.head_branch == 'main' || github.event.workflow_run.head_branch == 'dev')
+
+    steps:
+      - name: Checkout repository
+        # Use the commit from the completed workflow run
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ vars.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GHCR_PAT }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.DOCKER_HUB_REPO }}
+            ${{ env.GHCR_REPO }}
+          tags: |
+            type=raw,value=dev,pattern=dev
+            type=raw,value=latest,pattern=main
+            type=semver,pattern={{version}},pattern=main
+            type=semver,pattern={{major}}.{{minor}},pattern=main
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

{pystormtracker-0.2.2 → pystormtracker-0.3.0}/.github/workflows/python-publish.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
 
@@ -27,7 +27,7 @@ jobs:
           python -m build
 
       - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: release-dists
           path: dist/
@@ -54,7 +54,7 @@ jobs:
           echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
 
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: release-dists
           path: dist/

{pystormtracker-0.2.2 → pystormtracker-0.3.0}/.gitignore

@@ -64,7 +64,10 @@ target/
 
 # netCDF files
 *.nc
-!data/test/*.nc
 
-# CSV files
-*.csv
+# TXT track files
+*.txt
+!data/test/tracks/*.txt
+
+# VSCode
+.vscode/

{pystormtracker-0.2.2 → pystormtracker-0.3.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -9,16 +9,14 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.4
+    rev: v0.9.9
     hooks:
-      # Run the linter.
       - id: ruff
         args: [ --fix ]
-      # Run the formatter.
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.15.0
     hooks:
       - id: mypy
-        additional_dependencies: [ types-all ]
+        additional_dependencies: [numpy, pooch, scipy, pytest, pandas, xarray, dask, distributed, h5netcdf]

pystormtracker-0.3.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+
+sphinx:
+  configuration: docs/conf.py

{pystormtracker-0.2.2 → pystormtracker-0.3.0}/CITATION.cff

@@ -19,8 +19,8 @@ keywords:
   - dask
   - mpi
 license: BSD-3-Clause
-version: 0.2.2
-date-released: '2026-03-04'
+version: 0.3.0
+date-released: '2026-03-08'
 preferred-citation:
   type: article
   authors:

pystormtracker-0.3.0/Dockerfile

@@ -0,0 +1,32 @@
+# Use Python 3.14 slim as the base image
+FROM python:3.14-slim
+
+# Install system dependencies for MPI and building packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libopenmpi-dev \
+    openmpi-bin \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Create data directory for mounting
+RUN mkdir /data && chmod 777 /data
+
+# Copy the project files
+COPY . .
+
+# Install the package and its dependencies
+RUN pip install --no-cache-dir .
+
+# Add a non-root user for security
+RUN useradd -m pst
+USER pst
+
+# Volume for data persistence
+VOLUME /data
+
+# Default command
+ENTRYPOINT ["stormtracker"]
+CMD ["--help"]

{pystormtracker-0.2.2 → pystormtracker-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyStormTracker
-Version: 0.2.2
+Version: 0.3.0
 Summary: A Parallel Object-Oriented Cyclone Tracker in Python
 Project-URL: Homepage, https://github.com/mwyau/PyStormTracker
 Project-URL: Repository, https://github.com/mwyau/PyStormTracker.git
@@ -13,57 +13,72 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
-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: Topic :: Scientific/Engineering :: Atmospheric Science
-Requires-Python: >=3.10
-Requires-Dist: dask>=2024.2.0
-Requires-Dist: distributed>=2024.2.0
-Requires-Dist: netcdf4>=1.6.5
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: scipy>=1.10.0
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: xarray[accel,io,parallel]>=2024.9.0
 Provides-Extra: dev
-Requires-Dist: mpi4py>=3.1.5; extra == 'dev'
-Requires-Dist: mypy>=1.9.0; extra == 'dev'
-Requires-Dist: netcdf4>=1.6.5; extra == 'dev'
+Requires-Dist: mpi4py>=4.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: myst-parser>=2.0.0; extra == 'dev'
 Requires-Dist: pandas>=2.2.0; extra == 'dev'
-Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.1.1; extra == 'dev'
-Requires-Dist: ruff>=0.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'dev'
+Requires-Dist: sphinx>=7.2.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # PyStormTracker
 
+[![CI](https://github.com/mwyau/PyStormTracker/actions/workflows/ci.yml/badge.svg)](https://github.com/mwyau/PyStormTracker/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/pystormtracker/badge/?version=latest)](https://pystormtracker.readthedocs.io/en/latest/?badge=latest)
+[![codecov](https://codecov.io/github/mwyau/PyStormTracker/graph/badge.svg?token=JmTabGA3cq)](https://codecov.io/github/mwyau/PyStormTracker)
+[![PyPI version](https://img.shields.io/pypi/v/PyStormTracker)](https://pypi.org/project/PyStormTracker/)
+![Python versions](https://img.shields.io/pypi/pyversions/PyStormTracker)
+![License](https://img.shields.io/pypi/l/PyStormTracker)
+[![Docker](https://img.shields.io/badge/docker-xddd%2Fpystormtracker-blue?logo=docker)](https://hub.docker.com/r/xddd/pystormtracker)
+[![GHCR](https://img.shields.io/badge/ghcr.io-xddd%2Fpystormtracker-blue?logo=github)](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
 [![DOI](https://zenodo.org/badge/36328800.svg)](https://doi.org/10.5281/zenodo.18764813)
 
 PyStormTracker provides the implementation of the "Simple Tracker" algorithm used for cyclone trajectory analysis in **Yau and Chang (2020)**. It was originally developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 Summer Internships in Parallel Computational Science (SIParCS)** program, utilizing a task-parallel strategy with temporal decomposition and a tree reduction algorithm to process large climate datasets.
 
 ## Features
 
-- **Modern Python 3 Support**: Fully migrated from Python 2 with comprehensive type hints.
-- **Flexible Data Support**: Works with `netCDF4` and handles various coordinate naming conventions (`lat`/`lon` vs `latitude`/`longitude`).
+- **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**: Handles masked/missing data correctly and includes automated unit/integration tests.
-- **User-Friendly Output**: Results are exported directly to CSV with readable datetime strings and formatted numeric values.
+- **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 `generic_filter` with a sliding window (default 5x5) to identify local minima (cyclones) or maxima (anticyclones/vorticity).
+- **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](https://pystormtracker.readthedocs.io/).
+
 ## Installation
 
 ### Prerequisites
-- Python 3.10+
-- (Optional) MS-MPI or OpenMPI for MPI support.
+- Python 3.11+
+- (Optional) OpenMPI for MPI support.
 
 ### From PyPI (Recommended)
 You can install the latest stable version of PyStormTracker directly from PyPI:
@@ -78,9 +93,10 @@ pip install PyStormTracker
    cd PyStormTracker
    ```
 
-2. Install the package in editable mode:
+2. Install with **uv** (Recommended):
    ```bash
-   pip install -e .
+   uv sync --extra dev
+   uv run pre-commit install --hook-type pre-push
    ```
 
 ## Usage
@@ -88,7 +104,7 @@ pip install PyStormTracker
 Once installed, you can use the `stormtracker` command directly:
 
 ```bash
-stormtracker -i data/test/slp.2012.nc -v slp -o my_tracks
+stormtracker -i era5_msl_2.5x2.5.nc -v msl -o my_tracks
 ```
 
 ### Command Line Arguments
@@ -96,50 +112,74 @@ stormtracker -i data/test/slp.2012.nc -v slp -o my_tracks
 | Argument | Short | Description |
 | :--- | :--- | :--- |
 | `--input` | `-i` | **Required.** Path to the input NetCDF file. |
-| `--var` | `-v` | **Required.** Variable name to track (e.g., `slp`, `vo`). |
-| `--output` | `-o` | **Required.** Path to the output CSV file (appends `.csv` if missing). |
+| `--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). |
 
-### Examples
+## Development
 
-**Run with Dask (Auto-detected cores):**
+### Setup
+Using **uv** is the recommended way to set up your environment:
 ```bash
-stormtracker -i input.nc -v slp -o tracks
+# Install dependencies and sync virtual environment
+uv sync --extra dev
+
+# Install pre-push hooks
+uv run pre-commit install --hook-type pre-push
 ```
 
-**Run with MPI (Distributed):**
+### Quality Control
+Run automated checks using **uv run**:
+
+**Linting & Formatting:**
 ```bash
-mpiexec -n 4 stormtracker -i input.nc -v slp -o tracks -b mpi
+uv run ruff check . --fix
+uv run ruff format .
 ```
 
-## Project Structure
+**Type Checking:**
+```bash
+uv run mypy src/
+```
 
-- `src/pystormtracker/models/`: Data structures (`Center`, `Grid`, `Tracks`).
-- `src/pystormtracker/simple/`: Implementation of the Simple Tracker logic (`SimpleDetector`, `SimpleLinker`).
-- `src/pystormtracker/stormtracker.py`: CLI orchestration and parallel backends.
+### Tiered Testing
+To keep development cycles fast, testing is tiered:
+- **Fast Tests**: Default local runs (skips slow tests).
+- **Slow Tests**: ONLY long-running integration/regression tests.
+- **Full Suite**: Everything (used in CI).
 
-## Testing
+**Run fast unit tests only (Default):**
+```bash
+uv run pytest
+```
 
-Run the full test suite (unit and integration tests) using `pytest`:
+**Run ONLY slow/integration tests:**
+```bash
+uv run pytest --run-slow
+```
 
+**Run everything:**
 ```bash
-pytest
+uv run pytest --run-all
 ```
 
 ## Citations
 
 If you use this software in your research, please cite the following:
 
-- **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.   
+- **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.
 
 - **Yau, A. M. W.**, 2026: mwyau/PyStormTracker. *Zenodo*, https://doi.org/10.5281/zenodo.18764813.
 
 ## 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
 
 ## License