Metadata-Version: 2.4
Name: pepc-global-track
Version: 0.1.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

# 1D arrays of environmental predictors at storm locations
u250 = np.array([5.0, 6.0, 7.0])   # 250 hPa zonal wind (m s^−1)
v250 = np.array([1.0, 1.5, 2.0])   # 250 hPa meridional wind (m s^−1)
u850 = np.array([3.0, 3.5, 4.0])   # 850 hPa zonal wind (m s^−1)
v850 = np.array([-1.0, -0.5, 0.0]) # 850 hPa meridional wind (m s^−1)
lat  = np.array([15.0, 16.0, 17.0]) # storm latitude (degrees)

# Predict longitude displacement
delta_lon = predict_track("WNP", "lon", u250, v250, u850, v850, lat)

# Predict latitude displacement
delta_lat = predict_track("WNP", "lat", u250, v250, u850, v850, lat)
```

## Parameters

- **basin**: `str` — one of `"AS"`, `"BoB"`, `"WNP"`, `"ENP"`, `"NA"`, `"SI"`, `"SP"`
- **type**: `str` — `"lon"` (zonal displacement) or `"lat"` (meridional displacement)
- **u250, v250, u850, v850**: `numpy.ndarray` — 1D arrays of wind predictors
- **lat**: `numpy.ndarray` — 1D array of storm latitudes

## 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.
