Metadata-Version: 2.4
Name: pepc-global-track
Version: 0.2.0
Summary: Predict tropical cyclone track displacements using pre-trained Random Forest models
Author-email: Cong Gao <cong.gao@princeton.edu>
License: MIT
Project-URL: Homepage, https://github.com/CongGao-CG/pepc-global-track
Project-URL: Repository, https://github.com/CongGao-CG/pepc-global-track.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: scikit-learn>=1.0
Requires-Dist: joblib>=1.1
Requires-Dist: huggingface-hub>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"

# pepc-global-track

Predict tropical cyclone track displacements (longitude or latitude) using pre-trained Random Forest models.

## Installation

```bash
pip install pepc-global-track
```

## Usage

```python
import numpy as np
from pepc_global_track import predict_track

# (N, 5) array with columns [u250, v250, u850, v850, lat]
# u250, v250, u850, v850: wind predictors (m s^−1)
# lat: storm latitude (degrees)
X = np.array([
    [5.0, 1.0, 3.0, -1.0, 15.0],
    [6.0, 1.5, 3.5, -0.5, 16.0],
    [7.0, 2.0, 4.0,  0.0, 17.0],
])

# Predict longitude displacement
delta_lon = predict_track("WNP", "lon", X)

# Predict latitude displacement
delta_lat = predict_track("WNP", "lat", X)
```

## Parameters

- **basin**: `str` — one of `"AS"`, `"BoB"`, `"WNP"`, `"ENP"`, `"NA"`, `"SI"`, `"SP"`
- **type**: `str` — `"lon"` (zonal displacement) or `"lat"` (meridional displacement)
- **X**: `numpy.ndarray` — 2D array of shape `(N, 5)` with columns `[u250, v250, u850, v850, lat]`

## Returns

- `numpy.ndarray` — 1D array of predicted displacements (no noise added)

## Model Weights

Model weights are automatically downloaded from [HuggingFace](https://huggingface.co/CONGG/pepc-global-track) on first use and cached locally.
