pepc-global-genesis 1.2.5

Global tropical cyclone genesis prediction using trained SVC models

PepC-Global Genesis

A Python package for predicting tropical cyclone genesis using pre-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 pre-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 pre-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.