CPyS : A package for efficient computation of the Cyclone Phase Space parameters

Author: Stella Bourdin, [email protected] . Please reach out for any question!

Installation

# Download the package very simply with pip
pip install CPyS

Preliminaries

1. You need a csv file which contains your track(s) (tracks.csv hereafter, but you can name it as you wish). This csv can be the output of TempestExtremes' StitchNodes, or it can be obtained from TRACK's output with a code similar to the one at the bottom at this page. It needs to contains at least the longitude and the latitude of the points, named lon and lat. If several tracks are in the file, it is advised to have a track_id variable to distinguish among the tracks. Otherwise, the value of $\theta$ and $B$ for the last point of each track will be wrong. If your csv file has any other additional columns, they will be kept through the process, although not used.
2. You need a NetCDF file with the geopotential at several levels from 900 to 300hPa (at least five are recommended) covering the region where your tracks are (geopt.nc hereafter, but you can name it as you wish).
3. Use TempestExtremes' NodeFileCompose to obtain snapshots of the geopotential field along the track(s). Use a code similar to that below, adapted to your data:

NodeFileCompose \
    --in_nodefile "tracks.csv" \
    --in_nodefile_type SN \
    --in_fmt "(auto)" \
    --in_data "geopt.nc" \
    --out_grid "RAD" \     # Use radial grid for circular snapshots along the tracks
    --dx 0.5 --resx 10  \  # Snapshots dimension along the radial axis : 10 steps every 0.5° = 500km
    --out_data "snaps.nc" \
    --var "z(:)" \      # Change z to the name of the geopt variable in your data.
    --varout "zg" \     # Your snapshots will be named "snap_zg"
    --snapshots \       # Make sure to output individual snapshots
    --latname latitude --lonname longitude \  # Change to the names in your geopt.nc file
    --regional          # Use this option if your geopt.nc file is not global

NB : NodeFileCompose does not output the value of the vertical coordinate. Be careful to change it before using the snapshots with CPyS

This example is based on the track of Typhoon Dale. Dale.csv contains the track data, and Dale.nc contains the snapshots.

Loading the data

# Load the csv data using pandas, or your favorite function.
import pandas as pd
track = pd.read_csv("Dale.csv")
track[["track_id", "time", "lon", "lat"]] # Extract of the track file

	track_id	time	lon	lat
0	1277	1996-11-05 00:00:00	150.50	9.00
1	1277	1996-11-05 06:00:00	152.00	10.25
2	1277	1996-11-05 12:00:00	152.25	11.25
3	1277	1996-11-05 18:00:00	151.50	12.00
4	1277	1996-11-06 00:00:00	150.50	11.25
5	1277	1996-11-06 06:00:00	150.50	11.00
6	1277	1996-11-06 12:00:00	150.00	11.75
7	1277	1996-11-06 18:00:00	148.75	11.50
8	1277	1996-11-07 00:00:00	148.75	11.00
9	1277	1996-11-07 06:00:00	147.75	11.25
10	1277	1996-11-07 12:00:00	146.50	11.50
11	1277	1996-11-07 18:00:00	145.00	11.75
12	1277	1996-11-08 00:00:00	143.25	11.75
13	1277	1996-11-08 06:00:00	142.00	11.75
14	1277	1996-11-08 12:00:00	141.00	11.75
15	1277	1996-11-08 18:00:00	139.50	12.25
16	1277	1996-11-09 00:00:00	138.25	12.75
17	1277	1996-11-09 06:00:00	137.00	13.25
18	1277	1996-11-09 12:00:00	136.00	14.25
19	1277	1996-11-09 18:00:00	135.00	15.25
20	1277	1996-11-10 00:00:00	133.75	16.50
21	1277	1996-11-10 06:00:00	132.75	17.50
22	1277	1996-11-10 12:00:00	131.75	18.50
23	1277	1996-11-10 18:00:00	131.25	19.50
24	1277	1996-11-11 00:00:00	130.75	20.75
25	1277	1996-11-11 06:00:00	131.00	21.75
26	1277	1996-11-11 12:00:00	131.25	22.75
27	1277	1996-11-11 18:00:00	132.00	24.00
28	1277	1996-11-12 00:00:00	132.75	25.25
29	1277	1996-11-12 06:00:00	133.75	26.25
30	1277	1996-11-12 12:00:00	135.50	27.50
31	1277	1996-11-12 18:00:00	138.50	28.50
32	1277	1996-11-13 00:00:00	142.75	30.50
33	1277	1996-11-13 06:00:00	148.00	32.50
34	1277	1996-11-13 12:00:00	155.00	36.50

# Load the snapshots file with xarray
import xarray as xr
snaps = xr.open_dataset("Dale.nc")
#snaps["level"] = [...] # !! Change the vertical variable here if necessary. It must be in Pa.

# Snapshots dimensions
snaps.snap_zg.dims

('snapshot', 'level', 'r', 'az')

# Dimensions
snaps.coords

Coordinates:
  * az       (az) float64 128B 0.0 22.5 45.0 67.5 ... 270.0 292.5 315.0 337.5
  * r        (r) float64 400B 0.1 0.3 0.5 0.7 0.9 1.1 ... 9.1 9.3 9.5 9.7 9.9
  * level    (level) int32 148B 100 200 300 500 700 ... 92500 95000 97500 100000

Computation of the CPS parameters

from CPyS import compute_CPS_parameters

track_w_CPS_params = compute_CPS_parameters(track, snaps)
track_w_CPS_params[["track_id", "time", "lon", "lat", "theta", "B", "VTL", "VTU"]] # Results!

Computing B...
Level 90000 is taken for 900hPa
Level 60000 is taken for 600hPa

Computing VTL & VTU...

	track_id	time	lon	lat	theta	B	VTL	VTU
0	1277	1996-11-05 00:00:00	150.50	9.00	39.805571	-2.858689	48.728841	36.933898
1	1277	1996-11-05 06:00:00	152.00	10.25	75.963757	-6.972262	74.375981	47.726629
2	1277	1996-11-05 12:00:00	152.25	11.25	135.000000	-10.449450	81.880806	54.397699
3	1277	1996-11-05 18:00:00	151.50	12.00	216.869898	-0.754497	120.169291	116.594427
4	1277	1996-11-06 00:00:00	150.50	11.25	270.000000	11.002904	119.258912	107.699136
5	1277	1996-11-06 06:00:00	150.50	11.00	123.690068	-7.824734	122.372489	105.959700
6	1277	1996-11-06 12:00:00	150.00	11.75	191.309932	-1.379825	142.778913	106.332585
7	1277	1996-11-06 18:00:00	148.75	11.50	270.000000	2.639275	128.205585	116.285513
8	1277	1996-11-07 00:00:00	148.75	11.00	165.963757	3.478431	151.808066	132.191755
9	1277	1996-11-07 06:00:00	147.75	11.25	168.690068	1.628800	157.627609	130.330405
10	1277	1996-11-07 12:00:00	146.50	11.50	170.537678	2.838853	168.825123	140.099883
11	1277	1996-11-07 18:00:00	145.00	11.75	180.000000	3.555864	165.303199	166.089468
12	1277	1996-11-08 00:00:00	143.25	11.75	180.000000	4.846188	202.031166	197.741404
13	1277	1996-11-08 06:00:00	142.00	11.75	180.000000	8.541439	200.608822	231.410117
14	1277	1996-11-08 12:00:00	141.00	11.75	161.565051	7.499349	231.229205	275.971821
15	1277	1996-11-08 18:00:00	139.50	12.25	158.198591	8.350890	221.525033	301.511912
16	1277	1996-11-09 00:00:00	138.25	12.75	158.198591	13.814835	201.318918	325.515701
17	1277	1996-11-09 06:00:00	137.00	13.25	135.000000	9.081773	199.958096	327.971192
18	1277	1996-11-09 12:00:00	136.00	14.25	135.000000	8.773186	168.909787	338.476551
19	1277	1996-11-09 18:00:00	135.00	15.25	135.000000	3.275680	203.648746	315.273011
20	1277	1996-11-10 00:00:00	133.75	16.50	135.000000	1.542190	224.866598	390.489712
21	1277	1996-11-10 06:00:00	132.75	17.50	135.000000	2.163576	234.454862	357.229220
22	1277	1996-11-10 12:00:00	131.75	18.50	116.565051	-4.552958	251.703436	369.438634
23	1277	1996-11-10 18:00:00	131.25	19.50	111.801409	-4.863091	248.684975	388.123252
24	1277	1996-11-11 00:00:00	130.75	20.75	75.963757	-5.425436	225.197118	402.630643
25	1277	1996-11-11 06:00:00	131.00	21.75	75.963757	-0.924122	197.898618	386.382148
26	1277	1996-11-11 12:00:00	131.25	22.75	59.036243	13.115511	214.416774	364.826074
27	1277	1996-11-11 18:00:00	132.00	24.00	59.036243	22.026497	193.967018	320.715098
28	1277	1996-11-12 00:00:00	132.75	25.25	45.000000	47.103238	143.214635	216.606582
29	1277	1996-11-12 06:00:00	133.75	26.25	35.537678	66.173683	179.447963	103.050376
30	1277	1996-11-12 12:00:00	135.50	27.50	18.434949	84.836855	132.319875	-99.523735
31	1277	1996-11-12 18:00:00	138.50	28.50	25.201124	110.467675	113.114828	-158.705783
32	1277	1996-11-13 00:00:00	142.75	30.50	20.854458	136.636961	-101.234583	-313.597616
33	1277	1996-11-13 06:00:00	148.00	32.50	29.744881	173.836766	-393.814981	-413.435704
34	1277	1996-11-13 12:00:00	155.00	36.50	29.744881	242.850398	-732.284368	-589.779152

Plot of the phase space diagram

I have included a simple function to plot the two traditionnal phase space diagrams.

from CPyS import plot_CPS

plot_CPS(track_w_CPS_params, title = "Dale")