User Guide

Installation

To install the package, you can use pip:

pip install huracanpy

This can fail with older python versions due to issues with installing cartopy through pip. If this happens, use conda to install cartopy first (e.g. conda install -c conda-forge cartopy), then install huracanpy as normal

Usage

The idea of this package is to be a standard way for working with cyclone track data. We were all working on track data, but in slightly different ways which makes sharing code more difficult. The method chosen here is to treat a set of tracks as an xarray.Dataset with a minimal number of assumed variables (track_id, lon, lat, time). e.g. running

import huracanpy

tracks = huracanpy.load(huracanpy.example_csv_file)
minimal_tracks = tracks[["track_id", "lon", "lat", "time"]]

print(minimal_tracks)

gives

<xarray.Dataset>
Dimensions:   (record: 99)
Coordinates:
  * record    (record) int64 0 1 2 3 4 5 6 7 8 9 ... 89 90 91 92 93 94 95 96 97 98
Data variables:
    track_id  (record) int64 0 0 0 0 0 0 0 0 0 0 0 0 0 ... 2 2 2 2 2 2 2 2 2 2 2 2
    lon       (record) float64 120.5 119.0 119.0 119.2 ... 57.5 58.5 60.25 62.25
    lat       (record) float64 -14.25 -14.75 -15.0 -15.0 ... -39.25 -42.0 -45.5
    time      (record) datetime64[ns] 1980-01-06T06:00:00 ... 1980-01-30T18:00:00

where each “record” corresponds to a TC point (time, lon, lat). All variables that were present in your file are variables in the loaded dataset.

Note that the data is one dimensional but represents multiple tracks. This is done rather than having track_id as an additional dimension to avoid having to add a bunch of extra blank data to each track when they are not the same length. The groupby function allows us to easily loop over or index tracks in this format.

import huracanpy

tracks = huracanpy.load(huracanpy.example_csv_file)

track_groups = tracks.groupby("track_id")

# Selecting track by ID
# The track_id is not necessarily an integer, it follows whatever you have loaded
# e.g. could be a string for IBTrACS
track_id1 = track_groups[1]

# Iterating over all tracks
# Each track will be a subset of the xarray Dataset with a unique track_id
for track_id, track in track_groups:
    # Do something with the track

csv tracks data

If you tracks are stored in csv (including if they were outputed from TempestExtremes’ StitchNodes), you can specify the tracker="csv" argument, or, if your filename ends with csv, it will be detected automatically.

TRACK tracks data

If your tracks are in TRACK format, use the tracker=”TRACK” option