PepC-Global Intensity

A Python package for predicting tropical cyclone intensity using pre-trained Input-Output Hidden Markov Models.

Installation

pip install --upgrade pepc-global-intensity

Or from source:

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

Quick Start

import pandas as pd
from pepc_global_intensity import predict_intensity

# Create DataFrame for a single storm with required columns
df = pd.DataFrame({
    "step":       [0, 1, 2],
    "time":       pd.to_datetime(["2000-07-01 00:00", "2000-07-01 06:00", "2000-07-01 12:00"]),
    "year":       [2000, 2000, 2000],
    "mode":       ["ocean", "ocean", "ocean"],
    "ILD":        [50.0, 50.0, 50.0],
    "grd":        [1e-4, 1e-4, 1e-4],
    "ut":         [5.0, 5.0, 5.0],
    "pi":         [70.0, 70.0, 70.0],
    "shr":        [10.0, 10.0, 10.0],
    "rh600":      [0.7, 0.7, 0.7],
    "ocean":      [True, True, True],
    "ocean_next": [True, True, True],
    "mean_stl1":  [0.0, 0.0, 0.0],
    "mean_swvl1": [0.0, 0.0, 0.0],
})

# Predict intensity for a specific basin and experiment
result = predict_intensity(
    basin="NA",  # North Atlantic
    df=df,
    experiment="historical",
    model="ACCESS-ESM1-5",
    variant="r1i1p1f1",
    seed=42,
)

print(result[["step", "time", "pre_wind", "state"]])

Available Basins

API Reference

predict_intensity(basin, df, experiment, model, variant, seed)

Predict tropical cyclone intensity using Input-Output Hidden Markov Models.

Parameters:

• basin (str): Basin name (one of: 'AS', 'BoB', 'WNP', 'ENP', 'NA', 'SI', 'SP')
• df (pd.DataFrame): Pre-prepared data for a single storm with required columns (see Input Variables table below)
• experiment (str): Experiment type — 'historical' or 'ssp585'
• model (str): CMIP6 model name (used for ssp585 upper-bound schedule lookup)
• variant (str): CMIP6 variant label (used for ssp585 upper-bound schedule lookup)
• seed (int or None): Random seed for reproducibility

Returns:

• pd.DataFrame: Copy of the input DataFrame with added columns:
  • pre_wind: Predicted wind speed
  • pre_delta_wind_b: Predicted backward wind change
  • pre_delta_wind_f: Predicted forward wind change
  • pre_ocn: Predicted ocean state
  • state: Hidden state classification

Raises:

• ValueError: If basin is invalid, experiment is not 'historical' or 'ssp585', or required columns are missing from df

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

Model Details

This package contains pre-trained Input-Output Hidden Markov Models (IOHMM) for 7 tropical cyclone basins. The models were pre-trained on ERA5 monthly data using multiple environmental predictors known to influence tropical cyclone intensity:

1. Ocean coupling (ILD, grd): Ocean thermal structure affecting ocean feedback
2. Storm motion (ut): Translation speed affecting ocean feedback
3. Potential intensity (pi): Theoretical upper bound on storm strength
4. Wind shear (shr): Vertical wind shear affecting intensification
5. Mid-level humidity (rh600): Environmental moisture affecting intensification
6. Land effects (mean_stl1, mean_swvl1): Soil temperature and moisture setting the land enthalpy flux that slows over-land decay

Over land, wind decays exponentially toward 10 kt: v_next = 10 + (v − 10)·exp(−α·L̄), where L̄ = 0.2·(1−ocean) + 0.8·(1−ocean_next), α = exp(g0 + g1·E), and E = θ̄·max(0, exp(0.07·(T̄ − 299)) − 1), with T̄ = mean_stl1/L̄ and θ̄ = mean_swvl1/L̄.

Each basin has its own pre-trained IOHMM parameters and land-decay coefficients (g0, g1).

License

MIT License

Citation

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

Method development

Gao, Cong, and 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. Available at https://arxiv.org/abs/2609.14259.

Applications

Gao, Cong, and Ning Lin. "Recent increase in near-perpendicular tropical cyclone landfall fraction projected to emerge under high-emissions warming." Submitted. Available at https://arxiv.org/abs/2610.00975.

Gao, Cong, and Ning Lin. "A common warming-dependent decline emerges from divergent projections of tropical cyclone frequency." Geophysical Research Letters, under review. Available at https://arxiv.org/abs/2609.16521.