A python package for working with various forms of feature tracking data, including but not restricted to cyclone tracks.

Why HuracanPy? The idea of this package is to provide a unified tool for working with cyclone track data. In particular, HuracanPy can read tracks from many different sources/trackers. It also provides useful functions to analyse these tracks, including many common diagnostics. Our goal is to make track data analysis more accessible, and to promote good reproducibility practices.

Getting started

You can follow user guide, try out some of the examples, or follow the steps below (taken from the user guide).

Install

You can install huracanpy with conda

conda install -c conda-forge huracanpy

or pip

python -m pip install huracanpy

To install the most up-to-date version of huracanpy, you can install directly from the repository with

python -m pip install "huracanpy@git+https://github.com/Huracan-project/huracanpy"

Basic usage

The first step is to load in some tracks. HuracanPy can load track data from various sources as an xarray.Dataset with a minimal number of assumed variables (track_id, lon, lat, time) e.g.

import huracanpy

tracks = huracanpy.load(huracanpy.example_csv_file)
print(tracks)

<xarray.Dataset> Size: 7kB
Dimensions:   (record: 99)
Dimensions without coordinates: record
Data variables:
    track_id  (record) int64 792B 0 0 0 0 0 0 0 0 0 0 0 ... 2 2 2 2 2 2 2 2 2 2
    i         (record) int64 792B 482 476 476 477 478 ... 229 230 234 241 249
    j         (record) int64 792B 417 419 420 420 422 ... 501 509 517 528 542
    lon       (record) float64 792B 120.5 119.0 119.0 119.2 ... 58.5 60.25 62.25
    lat       (record) float64 792B -14.25 -14.75 -15.0 ... -39.25 -42.0 -45.5
    slp       (record) float64 792B 9.988e+04 9.981e+04 ... 9.747e+04 9.754e+04
    zs        (record) float64 792B -10.71 -16.11 -40.21 ... -218.5 -211.5
    wind10    (record) float64 792B 14.65 13.99 13.7 17.98 ... 23.69 23.96 23.4
    time      (record) datetime64[ns] 792B 1980-01-06T06:00:00 ... 1980-01-30...

Each "record" corresponds to a TC point (time, lon, lat).

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 blank data to each track when they are not the same length. The groupby function, built in to xarray, allows us to easily loop over tracks in this format.

# Iterating over all tracks
# Each track will be a subset of the xarray Dataset with a unique track_id
# The track_id is not necessarily an integer, it follows whatever you have loaded
# e.g. could be a string for IBTrACS
for track_id, track in tracks.groupby("track_id"):
    # Do something with the track
    print(track_id, len(track.time))

0 31
1 20
2 48

With the data loaded, we can apply the functions from HuracanPy. The example below is using the hrcn accessor from HuracanPy. See the accessor page for more details.

# Quickly view the tracks
tracks.hrcn.plot_tracks(intensity_var_name="wind10")

# Add a new variable to the tracks and plot this instead
tracks = tracks.hrcn.add_is_land()
tracks.hrcn.plot_tracks(intensity_var_name="is_land")

Contact

Please use GitHub's functions to communicate with HuracanPy's developers.

• Use Issues for feature requests or bug reporting
• Use the Discussions for Q&A and general feedback
• Do not forget HuracanPy is an open-source project, and you can also contribute to it.

Subscribe for updates

1. Most specific: Subscribe to this discussion for further updates.
2. Less specific: "Watch" the repo by clicking the button on the top-right of this page. Select "custom" then tick "discussions". You can always go back if there turns out to be too much emails. (We wish there was a better way for you to subscribe to announcements. If you agree with us, please up this issue.)