pepc-global-genesis 1.2.4

Global tropical cyclone genesis prediction using trained SVC models

PepC-Global Genesis

A Python package for predicting tropical cyclone genesis using trained Support Vector Classification (SVC) models.

Installation

pip install --upgrade pepc-global-genesis

Or from source:

git clone https://github.com/CongGao-CG/pepc-global-genesis.git
cd pepc-global-genesis
pip install .

Quick Start

import numpy as np
from pepc_global_genesis import predict_genesis

# Create predictor arrays (all must have the same shape)
# Shape can be (lat, lon) or (time, lat, lon), etc.
av850 = np.random.uniform(-1e-4, 1e-4, size=(10, 10))  # Absolute vorticity at 850 hPa (s^-1)
shr = np.random.uniform(0, 20, size=(10, 10))          # Vertical wind shear between 200 hPa and 850 hPa (m s^-1)
rh600 = np.random.uniform(30, 80, size=(10, 10))       # Relative humidity at 600 hPa (%)
pi = np.random.uniform(0, 100, size=(10, 10))          # Potential intensity (m s^-1)

# Predict genesis for a specific basin
basin = 'NA'  # North Atlantic
genesis_flag = predict_genesis(av850, shr, rh600, pi, basin=basin)

# genesis_flag is a numpy array of 0s and 1s with the same shape as inputs
print(f"Predicted genesis: {np.sum(genesis_flag)} grid points")

Available Basins

Basin Code	Name	Latitude Range	Longitude Range
AS	Arabian Sea	5° to 22.5°N	50° to 77.5°E
BoB	Bay of Bengal	5° to 22.5°N	80° to 100°E
WNP	Western North Pacific	5° to 30°N	102.5°E to 180°
ENP	Eastern North Pacific	5° to 25°N	177.5° to 75°W
NA	North Atlantic	5° to 30°N	97.5° to 2.5°W
SI	South Indian	30° to 5°S	20° to 145°E
SP	South Pacific	30° to 5°S	147.5°E to 100°W

API Reference

predict_genesis(av850, shr, rh600, pi, basin)

Predict tropical cyclone genesis.

Parameters:

• av850 (np.ndarray): Absolute vorticity at 850 hPa (s^−1)
• shr (np.ndarray): Vertical wind shear between 200 hPa and 850 hPa (m s^−1)
• rh600 (np.ndarray): Relative humidity at 600 hPa (%)
• pi (np.ndarray): Potential intensity (m s^−1)
• basin (str): Basin name (one of: 'AS', 'BoB', 'WNP', 'ENP', 'NA', 'SI', 'SP')

Returns:

• np.ndarray: Binary array (0 or 1) indicating predicted genesis, same shape as inputs

Raises:

• ValueError: If basin is invalid or input array shapes don't match

predict_genesis_global(av850, shr, rh600, pi)

Predict tropical cyclone genesis globally across all basins on a 2.5° grid.

This function automatically assigns each grid cell to the appropriate basin, applies an ocean mask to exclude land points, and handles the ENP/NA overlap region. Longitudes in −180 to 180 are converted to 0 to 360 internally.

Parameters:

• av850 (xr.DataArray): Absolute vorticity at 850 hPa (s^−1)
• shr (xr.DataArray): Vertical wind shear between 200 hPa and 850 hPa (m s^−1)
• rh600 (xr.DataArray): Relative humidity at 600 hPa (%)
• pi (xr.DataArray): Potential intensity (m s^−1)

All inputs must share the same dimensions and be on a 2.5° global grid (lon: 0, 2.5, ..., 357.5; lat: 90 to −90 or −90 to 90). Extra dimensions (e.g., time) are supported.

Returns:

• xr.Dataset with two variables:
  • genesis (float): 1 = genesis, 0 = no genesis, NaN = not predicted (land or outside all basins)
  • basin (str): cell classification — one of the 7 basin names ('AS', 'BoB', 'WNP', 'ENP', 'NA', 'SI', 'SP'), 'ocean_outside' (ocean but outside all basins), 'land_outside' (land outside all basins), or 'land_inside' (land inside a basin's lat/lon range)

Raises:

• ValueError: If lat/lon dimensions cannot be detected or coordinates are not on the expected 2.5° grid

Example:

import numpy as np
import xarray as xr
from pepc_global_genesis import predict_genesis_global

# Create 2.5° global grid
lon = np.arange(0, 360, 2.5)
lat = np.arange(90, -90.1, -2.5)
time = np.arange(12)

# Create predictor DataArrays (time x lat x lon)
dims = ['time', 'lat', 'lon']
coords = {'time': time, 'lat': lat, 'lon': lon}
av850 = xr.DataArray(np.random.uniform(-1e-4, 1e-4, (12, 73, 144)), dims=dims, coords=coords)
shr = xr.DataArray(np.random.uniform(0, 20, (12, 73, 144)), dims=dims, coords=coords)
rh600 = xr.DataArray(np.random.uniform(30, 80, (12, 73, 144)), dims=dims, coords=coords)
pi = xr.DataArray(np.random.uniform(0, 100, (12, 73, 144)), dims=dims, coords=coords)

# Predict genesis globally
result = predict_genesis_global(av850, shr, rh600, pi)
print(result)  # Dataset with 'genesis' and 'basin' variables

get_basin_names()

Get the list of valid basin names.

Returns:

• list[str]: List of 7 basin names

BASINS

List of valid basin names.

Input Variables

Variable	Description	Typical Units
av850	Absolute vorticity at 850 hPa	s^−1
shr	Vertical wind shear between 200 hPa and 850 hPa	m s^−1
rh600	Relative humidity at 600 hPa	%
pi	Potential intensity	m s^−1

Model Details

This package contains pre-trained SVC models for 7 tropical cyclone basins. The models were trained on ERA5 monthly data using four environmental predictors known to influence tropical cyclone genesis:

1. Absolute vorticity (av850): Measures rotation in the lower-level atmosphere
2. Wind shear (shr): Vector difference between upper-level and lower-level winds
3. Relative humidity (rh600): Mid-level moisture
4. Potential intensity (pi): Upper limit of tropical cyclone intensity

Each basin has its own trained model and scaling parameters stored within the package.

License

MIT License

Citation

If you use this package in your research, please cite:

Gao, Cong, Ning Lin. "PepC-Global: A Basin-Tuned Probabilistic Tropical Cyclone Model with Enhanced Out-of-Sample Skill and Climate-Sensitive Over-Land Decay". Journal of Advances in Modeling Earth Systems (JAMES), under review.