Basic functionality of octant package

Import the necessary modules

from pathlib import Path
from octant.core import TrackRun, OctantTrack, HOUR

Define the common data directory

sample_dir = Path(".") / "sample_data"

Data are usually organised in hierarchical directory structure. Here, the relevant parameters are defined.

dataset = "era5"
period = "test"
run_id = 0

Construct the full path

track_res_dir = sample_dir / dataset / f"run{run_id:03d}" / period

Load the data

The standard loading procedure is done during the initialisation of TrackRun by reading text files (output from PMCTRACK) from the given directory.

tr = TrackRun(track_res_dir)

print(tr)

<octant.core.TrackRun>
[671 tracks]

Data columns:
lon | lat | vo | time | area | vortex_type

Sources:
sample_data/era5/run000/test

The TrackRun object also has an HTML view available in Jupyter Notebooks

tr

Cyclone tracking results
Number of tracks	671
Data columns	lon, lat, vo, time, area, vortex_type
Sources
	sample_data/era5/run000/test

type(tr)

octant.core.TrackRun

len(tr)

671

tr.size()

671

tr.tstep_h

1.0

Main data container

The main attribute of TrackRun is .data, which has all the tracks stored in one DataFrame-like object.

tr.data.head()

		lon	lat	vo	time	area	vortex_type
track_idx	row_idx
0	0	9.3	79.2	0.000345	2011-01-01 00:00:00	10617.93652	0
	1	9.3	79.2	0.000352	2011-01-01 01:00:00	10154.14648	0
	2	9.3	79.2	0.000362	2011-01-01 02:00:00	10136.94629	0
1	0	20.4	70.5	0.000317	2011-01-01 00:00:00	34750.66016	1
	1	20.7	70.5	0.000310	2011-01-01 01:00:00	36727.84375	1

It always has track_idx level in order to index through individual tracks.

Tracking run configuration

If a .conf file is present in the same directory, it is loaded to TrackRun.

tr.conf

Tracking algorithm settings (43)
dt_start =	201101010000
dt_end =	201101312300
vor_lvl =	950
steer_lvl_btm =	1000
steer_lvl_top =	700
datadir =	../../reanalysis/era5
outdir =	../results/test7
vort_name =	vo
u_name =	u
v_name =	v
psea_name =	msl
land_name =	lsm
prefix_lvl =	era5.an.pl.
prefix_sfc =	era5.an.sfc.
proj =	1
vert_grid =	1
lon1 =	-20
lon2 =	50
lat1 =	65
lat2 =	85
halo_r =	30.0
smth_type =	0
nsmth_x =	10
nsmth_y =	10
r_smth =	60.0
zeta_max0 =	0.0002
zeta_min0 =	0.00015
int_zeta_min0 =	2e-06
gamma =	0.25
d_cf_min =	400.0
size_synop =	90000.0
distance_ec =	300.0
del_psea_min =	0.5
steering_type =	2
n_steering_x =	20
n_steering_y =	20
r_steering =	200.0
track_type =	2
del_lon =	1.0
del_lat =	0.8
del_r =	120.0
merge_opt =	2
vor_out_on =	0

Other methods of initialisation

TrackRun class can be initialised empty:

tr_empty = TrackRun()

tr_empty

Cyclone tracking results
Number of tracks	0
Data columns	lon, lat, vo, time, area, vortex_type

Concatenate data from several directories

TR = TrackRun(one_directory)
TR2 = TrackRun(another_directory)
TR.extend(TR2)

or

TR += TrackRun(another_directory)

Some attributes of TrackRun

TrackRun object has a few useful properties

• for example, it is possible to access the list of files that the data were loaded from.

tr.filelist[:5]

[PosixPath('sample_data/era5/run000/test/vortrack_0001_0001.txt'),
 PosixPath('sample_data/era5/run000/test/vortrack_0002_0001.txt'),
 PosixPath('sample_data/era5/run000/test/vortrack_0003_0001.txt'),
 PosixPath('sample_data/era5/run000/test/vortrack_0004_0001.txt'),
 PosixPath('sample_data/era5/run000/test/vortrack_0005_0001.txt')]

• there is a shortcut to group tracks by their index

tr.gb

<pandas.core.groupby.generic.DataFrameGroupBy object at 0x7fee3dd9f390>

It is equivalent of doing tr.data.groupby("track_idx").

for idx, a_track in tr.gb:
    print(f"Track with index={idx}")
    print(a_track)
    break

Track with index=0
                   lon   lat        vo                time         area  \
track_idx row_idx
0         0        9.3  79.2  0.000345 2011-01-01 00:00:00  10617.93652
          1        9.3  79.2  0.000352 2011-01-01 01:00:00  10154.14648
          2        9.3  79.2  0.000362 2011-01-01 02:00:00  10136.94629

                   vortex_type
track_idx row_idx
0         0                  0
          1                  0
          2                  0

• current TrackRun is not categorised yet (see “Categorisation” examples), so this attribute is empty:

tr.cat_labels

[]

Serialising TrackRun

TrackRun and all its metadata can be saved to and loaded from an HDF file.

tr.to_archive("test.h5")

new_tr = TrackRun.from_archive("test.h5")

new_tr

Cyclone tracking results
Number of tracks	671
Data columns	lon, lat, vo, time, area, vortex_type
Sources
	sample_data/era5/run000/test

Units of TrackRun

import random

Each cyclone track stored in lists of TrackRun class as a OctantTrack instance

ot = random.choice([*tr[:].gb])[1]

It is essentially a sub-class of pandas.DataFrame

ot

		lon	lat	vo	time	area	vortex_type
track_idx	row_idx
124	0	12.3	72.0	0.000423	2011-01-05 23:00:00	7615.17285	1
	1	10.8	72.0	0.000393	2011-01-06 00:00:00	19943.68750	1
	2	8.7	72.0	0.000349	2011-01-06 01:00:00	18887.55273	1
	3	-3.6	67.2	0.000666	2011-01-06 02:00:00	95968.20312	3

type(ot)

octant.core.OctantTrack

It has a few useful properties

ot.lifetime_h

3.0

ot.total_dist_km

836.7043121073503

including maximum vorticity in $ s^{-1}$:

ot.max_vort

0.00066578

ot.gen_lys_dist_km

810.8722660749592

ot.average_speed

278.90143736911676

ot.lonlat

array([[12.3, 72. ],
       [10.8, 72. ],
       [ 8.7, 72. ],
       [-3.6, 67.2]])

Running octant with a progress bar

Having either the fastprogress or tqdm module installed allows for running some methods with a bar that shows progress. To enable it, set the attribute of RUNTIME variable to True:

import octant
octant.RUNTIME.enable_progress_bar = True

conditions = [
    ("long_lived", [lambda ot: ot.lifetime_h >= 6]),
    (
        "far_travelled_and_very_long_lived",
        [lambda ot: ot.lifetime_h >= 36, lambda ot: ot.gen_lys_dist_km > 300.0],
    ),
    ("strong", [lambda x: x.max_vort > 1e-3]),
]

tr.classify(conditions)

100.00% [671/671 00:02<00:00]

More classify() examples

octant’s utilities

from octant.utils import great_circle

great_circle(lon1=9.6, lon2=10.2, lat1=76.9, lat2=78.9)

222826.50759451024