Core hierarchy

The core API is built on top of pandas package, and the main unit is OctantTrack, which is a subclass of pandas.DataFrame with extra methods and properties relevant to analysing cyclone tracking output.

class octant.core.OctantTrack(*args, **kw)[source]

Bases: pandas.core.frame.DataFrame

Instance of cyclone track.

DataFrame with a bunch of extra methods and properties.

__init__(*args, **kw)[source]

Initialise octant.core.OctantTrack.

property gb

Shortcut to group by track_idx index.

classmethod from_df(df)[source]

Create OctantTrack from pandas.DataFrame.

classmethod from_mux_df(df)[source]

Create OctantTrack from a multi-index pandas.DataFrame.

property coord_view

longitude, latitude, time.

Type

Numpy view of track coordinates

property lonlat

Values of longitude and latitude as 2D numpy array.

property lonlat_c

Values of longitude and latitude as C-ordered 2D numpy array.

property tridlonlat

Values of track index, longitude, latitude as 2D numpy array.

property tridlonlat_c

Values of track index, longitude, latitude as C-order 2D array.

property lifetime_h

Track duration in hours.

property gen_lys_dist_km

Distance between genesis and lysis of the cyclone track in km.

property total_dist_km

Total track distance in km.

property average_speed

Average cyclone propagation speed in km per hour.

property max_vort

Maximum vorticity of the cyclone track.

within_rectangle(lon0, lon1, lat0, lat1, time_frac=1)[source]

Check that OctantTrack is within a rectangle for a fraction of its lifetime.

Parameters

  • lon1, lat0, lat1 (lon0,) – Boundaries of longitude-latitude rectangle (lon_min, lon_max, lat_min, lat_max)

  • time_frac (float, optional) – Time fraction threshold. By default, set to maximum, i.e. track should be within the box entirely.

Returns

Return type

bool

Examples

Test that cyclone spends no more than a third of its life time outside the box

>>> bbox = [-10, 25, 68, 78]
>>> ot.within_rectangle(*bbox, time_frac=0.67)
True

See also

octant.misc.check_far_from_boundaries()

plot_track(ax=None, **kwargs)[source]

Plot cyclone track using as plot function from plotting submodule.

Filled circle shows the beginning, empty circle - the end of the track.

Parameters

  • ax (matplotlib axes object, optional) – Axes in which to plot the track If not given, a new figure with cartopy geoaxes is created

  • transform (matplotlib transform, optional) – Default: cartopy.crs.PlateCarree()

  • kwargs (other keyword arguments) – Options to pass to matplotlib plot() function

Returns

ax – The same ax as the input ax (if given), or a newly created axes

Return type

matplotlib axes object

class octant.core.TrackRun(dirname=None, columns=['lon', 'lat', 'vo', 'time', 'area', 'vortex_type'], **kwargs)[source]

Bases: object

Results of tracking experiment.

data

DataFrame-like container of tracking locations, times, and other data

Type

octant.core.OctantTrack

filelist

List of source “vortrack” files; see PMCTRACK docs for more info

Type

list

conf

Configuration used for tracking

Type

octant.parts.TrackSettings

is_categorised

Flag if categorisation has been applied to the TrackRun

Type

bool

cats

DataFrame with the same index as data and the number of columns equal to the number of categories; None if is_categorised is False

Type

None or pandas.DataFrame

__init__(dirname=None, columns=['lon', 'lat', 'vo', 'time', 'area', 'vortex_type'], **kwargs)[source]

Initialise octant.core.TrackRun.

Parameters

  • dirname (pathlib.Path, optional) – Path to the directory with tracking output If present, load the data during on init

  • columns (sequence of str, optional) – List of column names. Should contain ‘time’ to parse datetimes.

  • kwargs (other keyword arguments) – Parameters passed to load_data()

property cat_labels

List of category labels.

property gb

Group by track index.

size(subset=None)[source]

Size of subset of tracks.

rename_cats(**mapping)[source]

Rename categories of the TrackRun.

Parameters

mapping (dict) – How to rename categories, {old_key: new_key}

load_data(dirname, columns=['lon', 'lat', 'vo', 'time', 'area', 'vortex_type'], wcard='vortrack*0001.txt', conf_file=None, scale_vo=0.001)[source]

Read tracking results from a directory into TrackRun.data attribute.

Parameters

  • dirname (pathlib.Path) – Path to the directory with tracking output

  • columns (sequence of str, optional) – List of column names. Should contain ‘time’ to parse datetimes.

  • conf_file (pathlib.Path, optional) – Path to the configuration file. If omitted, an attempt is made to find a .conf file in the dirname directory

  • wcard (str) – Wildcard for files to read in. By default, loads only “primary” vortices and skips merged. See PMCTRACK docs for more info.

  • scale_vo (float, optional) – Scale vorticity values column to SI units (s-1) By default PMCTRACK writes out vorticity in (x10-3 s-1), so scale_vo default is 1e-3. To switch off scaling, set it to 1.

classmethod from_archive(filename)[source]

Construct TrackRun object from HDF5 file.

Parameters

filename (str) – File path to HDF5 file

Returns

Return type

octant.core.TrackRun

to_archive(filename)[source]

Save TrackRun and its metadata to HDF5 file.

Parameters

filename (str) – File path to HDF5 file

extend(other, adapt_conf=True)[source]

Extend the TrackRun by appending elements from another TrackRun.

Parameters

  • other (octant.core.TrackRun) – Another TrackRun

  • adapt_conf (bool) – Merge TrackSettings (.conf attribute) of each of the TrackRuns This is done by retaining matching values and setting other to None

time_slice(start=None, end=None)[source]

Subset TrackRun by time using pandas boolean indexing.

Parameters
Returns

Return type

octant.core.TrackRun

Examples

>>> from octant.core import TrackRun
>>> tr = TrackRun(path_to_directory_with_tracks)
>>> sub_tr = tr.time_slice('2018-09-04', '2018-11-25')
classify(conditions, inclusive=False, clear=True)[source]

Categorise the loaded tracks.

Parameters

  • conditions (list) – List of tuples. Each tuple is a (label, list) pair containing the category label and a list of functions each of which has OctantTrack as its only argument. The method assigns numbers to the labels in the same order that they are given, starting from number 1 (see examples).

  • inclusive (bool, optional) – If true, next category in the list is a subset of lower category; otherwise categories are independent.

  • clear (bool, optional) – If true, existing TrackRun categories are deleted.

Examples

Simple check using OctantTrack properties

>>> from octant.core import TrackRun
>>> tr = TrackRun(path_to_directory_with_tracks)
>>> def myfun(x):
        bool_flag = (x.vortex_type != 0).sum() / x.shape[0] < 0.2
        return bool_flag
>>> conds = [
    ('category_a', [lambda ot: ot.lifetime_h >= 6]),  # only 1 function checking lifetime
    ('category_b', [myfun,
                    lambda ot: ot.gen_lys_dist_km > 300.0])  # 2 functions
]
>>> tr.classify(conds)
>>> tr.size('category_a'), tr.size('category_b')
31, 10

For more examples, see example notebooks.

See also

octant.misc.check_by_mask()

categorise(*args, **kwargs)[source]

Alias for classify().

categorise_by_percentile(by, subset=None, perc=95, oper='ge')[source]

Categorise by percentile.

Parameters

  • by (str or tuple) – Property of OctantTrack to apply percentile to. If tuple is passed, it should be of form (label, function), where the function takes OctantTrack as the only parameter and returns one value for each track.

  • subset (str, optional) – Subset of Trackrun to apply percentile to.

  • perc (float, optional) – Percentile to define a category of cyclones. E.g. (perc=95, oper=’ge’) is the top 5% cyclones.

  • oper (str, optional) – Math operator to select track above or below the percentile threshold. Can be one of (lt|le|gt|ge).

Examples

Existing property: max_vort

>>> tr = TrackRun(path_to_directory_with_tracks)
>>> tr.is_categorised
False
>>> tr.categorise_by_percentile("max_vort", perc=90, oper="gt")
>>> tr.cat_labels
['max_vort__gt__90pc']
>>> tr.size()
71
>>> tr.size("max_vort__gt__90pc")
7

Custom function

>>> tr = TrackRun(path_to_directory_with_tracks)
>>> tr.is_categorised
False
>>> tr.categorise_by_percentile(by=("slp_min", lambda x: np.nanmin(x.slp.values)),
                                perc=20, oper="le")
>>> tr.cat_labels
['slp_min__le__20pc']
>>> tr.size("slp_min__le__10pc")
14

See also

octant.core.TrackRun.classify()

clear_categories(subset=None, inclusive=None)[source]

Clear TrackRun of its categories.

If categories are inclusive, it destroys child categories

Parameters

  • subset (str, optional) – If None (default), all categories are removed.

  • inclusive (bool or None, optional) – If supplied, is used instead of is_cat_inclusive attribute.

Examples

Inclusive categories

>>> tr = TrackRun(path_to_directory_with_tracks)
>>> tr.is_cat_inclusive
True
>>> tr.cat_labels
['pmc', 'max_vort__ge__90pc|pmc']
>>> tr.clear_categories(subset='pmc')
>>> tr.cat_labels
[]

Non-inclusive

>>> tr = TrackRun(path_to_directory_with_tracks)
>>> tr.cat_labels
['pmc', 'max_vort__ge__90pc|pmc']
>>> tr.clear_categories(subset='pmc', inclusive=False)
>>> tr.cat_labels
['max_vort__ge__90pc|pmc']
match_tracks(others, subset=None, method='simple', interpolate_to='other', thresh_dist=250.0, time_frac=0.5, return_dist_matrix=False, beta=100.0, r_planet=6371009.0)[source]

Match tracked vortices to a list of vortices from another data source.

Parameters

  • others (list or octant.core.TrackRun) – List of dataframes or a TrackRun instance

  • subset (str, optional) – Subset (category) of TrackRun to match. If not given, the matching is done for all categories.

  • method (str, optional) – Method of matching (intersection|simple|bs2000)

  • interpolate_to (str, optional) – Interpolate TrackRun times to other times, or vice versa

  • thresh_dist (float, optional) – Radius (km) threshold of distances between vortices. Used in ‘intersection’ and ‘simple’ methods

  • time_frac (float, optional) – Fraction of a vortex lifetime used as a threshold in ‘intersection’ and ‘simple’ methods

  • return_dist_matrix (bool, optional) – Used when method=’bs2000’. If True, the method returns a tuple of matching pairs and distance matrix used to calculate them

  • beta (float, optional) – Parameter used in ‘bs2000’ method E.g. beta=100 corresponds to 10 m/s average steering wind

  • r_planet (float, optional) – Radius of the planet in metres Default: EARTH_RADIUS

Returns

  • match_pairs (list) – Index pairs of other vortices matching a vortex in TrackRun in a form (<index of TrackRun subset>, <index of other>)

  • dist_matrix (numpy.ndarray) – 2D array, returned if return_dist_matrix=True

density(lon1d, lat1d, by='point', subset=None, method='cell', dist=222.0, exclude_first={'d': 1, 'm': 10}, exclude_last={'d': 30, 'm': 4}, grid_centres=True, weight_by_area=True, r_planet=6371009.0)[source]

Calculate different types of cyclone density for a given lon-lat grid.

  • point: all points of all tracks

  • track: each track only once for a given cell or circle

  • genesis: starting positions (excluding start date of tracking)

  • lysis: ending positions (excluding final date of tracking)

Parameters

  • lon1d (numpy.ndarray) – Longitude points array of shape (M,)

  • lat1d (numpy.ndarray) – Latitude points array of shape (N,)

  • by (str, optional) – Type of cyclone density (point|track|genesis|lysis)

  • subset (str, optional) – Subset (category) of TrackRun to calculate density from. If not given, the calculation is done for all categories.

  • method (str, optional) – Method to calculate density (radius|cell)

  • dist (float, optional) – Distance in km Used when method=’radius’ Default: ~2deg on Earth

  • exclude_first (dict, optional) – Exclude start date (month, day)

  • exclude_last (dict, optional) – Exclude end date (month, day)

  • grid_centres (bool, optional) – If true, the function assumes that lon (M,) and lat (N,) arrays are grid centres and calculates boundaries, arrays of shape (M+1,) and (N+1,) so that the density values refer to centre points given. If false, the density is calculated between grid points.

  • weight_by_area (bool, optional) – Weight result by area of grid cells.

  • r_planet (float, optional) – Radius of the planet in metres Default: EARTH_RADIUS

Returns

dens – Array of track density of shape (M, N) with useful metadata in attrs

Return type

xarray.DataArray