Metadata-Version: 2.4
Name: tcpyVPI
Version: 1.0.0
Summary: Calculate the tropical cyclone ventilated Potential Intensity (vPI) and the Genesis Potential Index using vPI (GPIv) from gridded datafiles. Supports both monthly mean and hourly ERA5 data. See Chavas Camargo Tippett (2025, J. Clim.) for details.
Home-page: https://github.com/drchavas/tcpyVPI
Author: Dan Chavas, Jose Ocegueda Sanchez
Author-email: drchavas@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: netCDF4
Requires-Dist: tcpyPI
Requires-Dist: pandas
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: cartopy; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# tcpyVPI

A Python package to calculate the tropical cyclone ventilated Potential Intensity (vPI) and the Genesis Potential Index using vPI (GPIv) from gridded datafiles. 

See Chavas, Camargo, & Tippett (2025, J. Clim.) for details.

**Author:** Dan Chavas (2025)  
**Collaborators:** Aaron Kruskie, Jose Ocegueda Sanchez (2025)

## Installation

```bash
pip install tcpyVPI
```

Or install from source:
```bash
git clone https://github.com/drchavas/tcpyVPI.git
cd tcpyVPI
pip install -e .
```

## Features

- **Monthly Mean Data**: Compute GPIv from ERA5 monthly mean reanalysis (d633001)
- **Hourly Data**: Compute GPIv from ERA5 hourly reanalysis (d633000) via THREDDS remote access
- **Climatology**: Compute and store monthly climatologies of GPIv and its components
- **Anomalies**: Calculate anomalies relative to climatological means
- **Standardized Anomalies**: Compute z-scores for statistical analysis

## Quick Start

### Monthly Mean Computation

```python
from tcpyVPI import run_vpigpiv

# Compute GPIv for September 2022
results = run_vpigpiv(2022, 9)
```

### Hourly Computation

```python
from tcpyVPI import run_vpigpiv_hourly

# Compute GPIv for August 15, 2020 at 12Z
results = run_vpigpiv_hourly(2020, 8, 15, hour=12)
```

### With Anomalies

```python
from tcpyVPI import run_vpigpiv_hourly

# First, compute or load a climatology
results = run_vpigpiv_hourly(
    2020, 8, 15, hour=12,
    compute_anomalies=True,
    climatology_path='gpiv_climatology.nc'
)
```

## Data Loading

The package provides flexible data loading from NCAR RDA THREDDS servers:

```python
from tcpyVPI import load_era5_data, load_era5_hourly

# Load monthly mean data
ds_monthly = load_era5_data(2022, 9, data_source='monthly')

# Load hourly data for a specific time
ds_hourly = load_era5_data(2020, 8, day=15, hour=12, data_source='hourly')

# Load all hours of a day
ds_day = load_era5_hourly(2020, 8, 15)
```

### ERA5 Dataset Structure

The package accesses ERA5 data via THREDDS with the following structure:

**Monthly Mean (d633001):**
- All 12 months in a single file per variable per year
- Both surface and pressure level variables

**Hourly (d633000):**
- **Surface variables**: Monthly files containing all hours
  - Example: `e5.oper.an.sfc.128_165_10u.ll025sc.2020080100_2020083123.nc`
- **Pressure level variables**: Daily files containing 24 hours
  - Example: `e5.oper.an.pl.128_131_u.ll025uv.2020081500_2020081523.nc`

## Climatology Computation

```python
from tcpyVPI import compute_monthly_climatology, compute_gpiv_from_dataset

# Compute 40-year climatology (1980-2020)
climatology = compute_monthly_climatology(
    compute_gpiv_from_dataset,
    years=range(1980, 2020),
    output_path='gpiv_climatology.nc'
)
```

## Computing Components Individually

```python
from tcpyVPI import (
    load_era5_data,
    calculate_potential_intensity,
    calculate_vws,
    calculate_entropy_deficit,
    calculate_etac,
)

# Load data
ds = load_era5_data(2022, 9, data_source='monthly')

# Calculate individual components
PI, asdeq = calculate_potential_intensity(ds)
VWS = calculate_vws(ds)
Chi = calculate_entropy_deficit(ds, asdeq)
eta_c = calculate_etac(ds)
```

## Output Variables

The main computation returns a dataset with:

| Variable | Description | Units |
|----------|-------------|-------|
| `GPIv` | Ventilated Genesis Potential Index | - |
| `vPI` | Ventilated Potential Intensity | m/s |
| `PI` | Potential Intensity | m/s |
| `VWS` | Vertical Wind Shear (200-850 hPa) | m/s |
| `Chi` | Entropy Deficit | - |
| `eta_c` | Capped Absolute Vorticity (850 hPa) | s⁻¹ |
| `ventilation_index` | Ventilation Index | - |

When computing anomalies, additional fields are added:
- `*_anom`: Anomaly fields
- `*_clim`: Climatological values

## Dependencies

- numpy
- xarray
- tcpyPI
- matplotlib (for plotting)
- cartopy (for plotting)

## License

MIT License - see LICENSE file for details.

## Citation

If you use this package, please cite:

Chavas, D. R., Camargo, S. J., & Tippett, M. K. (2025). "Tropical cyclone genesis potential using a ventilated potential intensity". *Journal of Climate*.


