hurdat2parser -- v2.3.0.1

Interpreting the Hurdat2 Tropical Cyclone Dataset using Python

Hurdat2 (https://www.nhc.noaa.gov/data/#hurdat) is a text file containing extensive time-stamped data from individual Tropical Cyclones. The two primary Hurdat2 records are for the Atlantic (since 1850) and East/Central-Pacific Oceans (since 1949).

The purpose of this module is to provide a quick way to analyze the Hurdat2 datasets. It includes methods for retrieving, inspecting, ranking, or even exporting data for seasons, individual storms, or climatological eras.

PyPI Link: https://pypi.org/project/hurdat2parser/

Changes/Fixes in this Version (2.3 and 2.3.0.1)
Requirements, Installation, and getting the data
Importing the module
Hurdat2 Object Structure
Example Calls
Methods & Attributes
Note on Landfall Data
How to Use crosses()
- Included Coastlines with this Module
Note on Ranking Methods
Future/Under-Development/Unreleased Methods
Roadmap
Credits
Copyright/License

Changes in this Version (2.3 and 2.3.0.1)

for v2.3.0.1
- in from_map(), I ordered returned data to be in python's float form rather than of type numpy.float64 (probably from a newer version of mpl that I didn't have installed while developing).
- removed a __main__.py file that I use only for development/testing purposes.
Hurdat2 tweaks
- online retrieval now attempts to download to a local file.
  - IMPORTANT! Versions < 2.3 are not guaranteed to see the newest hurdat2 releases due to url-name structure change and too-strict regex code (my fault).
- Call/Retrieval improvements
  - Attribute-like access to individual cyclones
    - named cyclones (ex: atl.hugo, atl.rita, etc).
      - This will return the most recent cyclone assigned a particular name. This guarantees that most-notorious cyclones with retired names will be returned
    - Assigned ATCFID's (a basin prefix, cyclone number, and the season) ... (ex: atl.al171995 or atl.AL171995)
  - recognizance of interchangeable order of season and cyclone number (atl[1995,17] or atl[17,1995] return the same TropicalCyclone. In addition, ATCF-ids without the basin prefix are recognized (atl[171995] or atl[199517])
- added random() method that returns a random TropicalCyclone object.
- uniform rank_seasons() that allows part-season ranking
  - added method keyword that allows one to choose the desired ranking method. The options are D for dense rankings (default) (1,2,2,3) or C for competition-based ranking (1,2,2,4).
  - deprecated rank_seasons_thru() method.
- uniform _season_stats handler/wrapper method that supports printing to console or as str.
  - deprecated _season_stats_str method
- added from_map method that uses matplotlib to draw polylines, returning them as tupled coordinates.
  - added coastline coordinate constants
    - Click Here for a list of included coastlines.
  - the purpose for these are to be used with the <TropicalCyclone>.crosses method (also new this version).
Season tweaks
- updated stats() method to now report densely-based and competition-based rankings.
TropicalCyclone tweaks
- added vector info and saffir-simpson ratings to .summary()
- added crosses method that allows comparing a system's track to a coordinate list to see if it crossed the path. Click Here for a guide on how to use.
- removed/changed verbiage where I erroneously had indicated 50kt winds as "gale force".
- .info() temporal data are now status-based
- track_map() tweaks and improvements
  - legend is no longer draggable by default. See keyword below
  - removed auto-resizing that inadvertently required tkinter in previous versions.
  - tweaked placement of NaturalEarth accreditation
  - added keyboard shortcuts for Zooming (SHIFT + arrows) and Panning (CTRL + arrows) and toggle of legend (N)
  - temporal labels no longer inadvertently alter the size of the Axes when panning.
  - added some interaction. Clicking on a segment will reveal some basic TCRecordEntry (segment) information in the lower left corner of the display (may be buggy. Try toggling the maximize screen option and see if it appears).
  - default behavior more-so mimics the matplotlib (mpl) defaults
  - small visual improvements including default map extent, sub-tropical cyclone discrimination on map and legend, and bolder tracks for major hurricanes, and Natural Earth map citation
  - higher resolution maps
  - new supported keywords
    - removed aspect_ratio kw
    - added width, height; these are used in the figsize keyword when creating the figure.
    - added dpi, and block. These mimic their mpl counterparts
    - added draggable kw that indicates if the displayed legend should be able to be interacted with.
    - added extents kw that can show generalized quadrant-based TS, 50kt, and Hurricane force wind extents. As of the most recent hurdat2 release, this is only available for cyclones >= 2004.
    - added padding kw to allow modification of the default focal scope on the track itself. The higher this number, the more "zoomed-out" it will appear.
    - added saveonly kw that saves an image locally instead of showing the plot on screen. This also respects the aforementioned width, height, and dpi kw's
    - added backend to allow the user to dictate which mpl backend to use
TCRecordEntry tweaks
- formalized entrytimes as UTC/Zulu timezone (won't change calculated stats any)
- added category property as an alias for saffir_simpson
made small tweaks to Saffir-simpson scale to reflect data from . Some of the scale I had was off by one or two knots. As reported data is rounded to the nearest 20th (0, 5, 10, 15, 20, etc), the tweaks are inconsequential.
added gis keyword to _calculations.haversine. This allows the use of coordinates in (lon, lat) format (True; common in GIS programs) or (lat, lon) (False; default). In future releases, I may go to the (lon, lat) format as default and uniform throughout.
hurdat2() methods made uniform by returning a string. You can optionally use the original line from the database instead of the default of objectively-formed wind-extent data.
inclusion of BoundingBox and Coordinate classes in _gis module. These are what enable functionality to the from_map and crosses methods.

⇧ back to Contents

Installation

At the command prompt, run pip install hurdat2parser
- When installing, packages pyshp, geojson, and matplotlib will be downloaded as dependencies (if necessary). From scratch, it's around 30MB total of dependency downloads.

⇧ back to Contents

Importing the Module

Follow these commands for genesis!

>>> import hurdat2parser
#or if you're lazy like me...
>>> import hurdat2parser as hd2

Different ways to ingest data

There are a few different ways to load hurdat2 formatted files. These approaches can be mixed/matched too.

Local / Offline

If you want a local copy of a hurdat2file, got to https://www.nhc.noaa.gov/data/#hurdat to download. It's a text file. Hurdat2 files for the Atlantic Basin and East/Central Pacific Basins are available and compatible with the package. They are updated every year around the start of a new Hurricane Season. Hotfix updates can be released occasionally if there are typos/errors etc. found.

To read-in a local file:
>>> atl = hurdat2parser.Hurdat2("path_to_hurdat2.txt")

Online Retrieval

As of v2.2, datasets can be retrieved from online. As of v2.3, an attempt is made to save a copy locally.

The downside is versions prior to v2.3 won't be able to see the newest hurdat2 releases. So going forward, v2.3+ will be needed if using this feature. Otherwise, just follow instructions in the prior section to download and ingest a local copy. No biggie since, generally-speaking, the databases are updated once per year.

North Atlantic Basin
>>> atl = hurdat2parser.Hurdat2(basin="atl")
- Any of the following will be recognized: "al", "atl", or "atlantic"
NE/CEN Pacific Basin
>>> pac = hurdat2parser.Hurdat2(basin="pac")
- Any of the following will be recognized: "pac", "nepac", or "pacific"

Alternate URL (experimental)

If you are aware of a frequently updated dataset in Hurdat2 format, you can pass a URL and set the kwarg urlcheck to True and retrieval will be tried
>>> atl = hurdat2parser.Hurdat2("http://crazygonuts.aboutweatherstuff/myhurdat2file.txt", urlcheck=True)

If you want you could combine it with a local file also:

# Atlantic
>>> atl = hurdat2parser.Hurdat2("local_atl_hurdat2_filename.txt", "https://weblink/to/otherhurdat2file.txt", urlcheck=True)

Readable Object Names

For the Hurdat2 object, I highly recommend to use something shortened and readable for the parent object name (like atl or al for the Atlantic database and ep, cp, or pac for the East/Central Pacific)*

After a few seconds (a little longer if downloading) you'll be ready to dive into the data! Subsequent examples imply the use of the Atlantic Hurdat2 (atl).

⇧ back to Contents

Hurdat2 Object Structure

The structure of a Hurdat2 object is hierarchal. It has two primary dictionaries:
- <Hurdat2>.tc - A dictionary containing all TropicalCyclone objects compiled from the record.
- <Hurdat2>.season - A dictionary holding Season objects (yearly data).
  - A Season's data is accessed via a simple year key of type int.
    - atl[1995] retrieves the object associated with the 1995 hurricane season.
Season objects are a container for cyclones occurring in that particular year.
- <Season>.tc - mirroring its above counterpart, it is a dictionary that holds TropicalCyclones, keyed by their atcfid., specific to the year. Some different ways to call these objects:
TropicalCyclone objects represent an individual cyclone in the Hurdat2 record.
- <TropicalCyclone>.entry is a list containing temporal and, in some cases, event-based records
  - The members of the list are TCRecordEntrys
TCRecordEntrys represent a cyclone's data recorded at a specific time.
- These are what holds the actual data from the Hurdat2.
- Though the "lowest" class in the heirarchy, a large majority of attributes for TropicalCyclones and therefor Seasons depend on this class and are calculated and derived from these individual storm entries.

Example calls

Read-on to see several ways to invoke a call to a Season or TropicalCyclone objects. You'll also find these type of references throughout the document and even a large portion of docstrings.

Season objects (just the year)
- atl[1995]
TropicalCyclone objects
- by ATCFID
  - attribute-like access:
    - atl.al171995
  - ATCF number and season tuple (treated as dictionary keys)
    - atl[12,2005] or atl[2005,12]
  - leaving out the comma is ok too (just like in ACTFID's):
    - atl[122005] or atl[200512]
  - Storm starting letter (or name):
    - atl[1995, "o"] - This method works for most modern tropical storms, as they have been issued names. So in these cases, you wouldn't need to know the atcfid number. Also of note, because tropical depressions aren't issued names, the id numbers do not always correlate with the co-inciding letter of the alphabet. For example, Hurricane Andrew's ATCFID is AL041992.
- by Name
  - atl.rita or atl["_rita"], or atl["-rita"] -- Attribute-like access or beginning the name with an underscore or dash shows the most-recent storm named as such (this returns the most-notorious storms as well since storm names can be retired according to the destruction they cause).
  - atl["danny"] -- shows a list of storms in the record given the name of Danny (or something similar), allowing the user to select which one they desire
TCRecordEntry calls
- Example for the entry at index 29 (30th total entry) for Hurricane Allen
  - atl[1980,4,29] or atl.allen[29]

Other examples of calls of interest

Iterate through all cyclones
- >>> for tc in atl.tc.values():
- list comprehension form example grouping all Category 3+ cyclones:
  - [tc for tc in atl.tc.values() if tc.maxwind >= 96]
- all category 3+ cyclones occuring since 1967 that experienced a minimum MSLP of <= 910hPa
  - [tc for tc in atl.tc.values() if tc.year >= 1967 and tc.maxwind >= 96 and tc.minmslp <= 910]
- all cyclones which made a landfall as a Hurricane along the US Gulf Coast during October or later, since 1967
  - [tc for tc in atl.tc.values() if tc.year >= 1967 and tc.start_date.month >= 10 and tc.crosses(atl.us_gulf_coast, landfall=True, category=1, is_TC=True)]
Multi-Season Statistical Report (can also be used to get a climatology)
- atl.multi_season_info(1991, 2020) or atl[1991:2021].
  - if you use a slice, be aware it will behave like a list, and the end will be decremented by 1.

⇧ back to Contents

Methods and Attributes

Now that you know how to call a particular object of interest, you can now access its data, using methods and attributes. The docstrings (accessed via help()) are quite detailed and methods that take arguments have example calls listed. But here is a quick reference to what is available, along with some shortcuts and example calls to assist navigating while in this document.

Hurdat2 Methods & Attributes
Season and TropicalCyclone Shared Methods & Attributes
Season-only Methods & Attributes
TropicalCyclone-only Methods & Attributes
TCRecordEntry Attributes

`Hurdat2` Methods and Attributes

Attributes	Description	Examples
`rank_seasons(...)`	Print a report that lists a ranking of seasons based on an inquired attribute. Other details are included in the report as well, but they'll be ordered according to the attribute passed. Though not all attributes are represented in the printed report, the ordering will be correct based on the inquired attribute. It also takes positional keyword arguments for `year1=None` and `year2=None`, allowing optional ranking to limit the scope of the report to a range of years (this also applies to subsequent ranking methods).	`atl.rank_seasons(5, "track_distance_TS", 1971, 2000, True)`
`rank_seasons_thru(...)`	Print a ranking of seasons where you can use part of the season; a way to rank attributes up to or between certain dates. Special keyword arguments, `start` (internal default of `(1,1)`) and `thru` (default of `(12, 31)`), tuples representing a month and day, (ex. `(9,6)` for September 6) enable ranking of partial seasons. *As a side note, exclusion of these keywords just make this a wrapper for the above `rank_seasons` method.	`atl.rank_seasons_thru(10, "TSreach", 1967, thru=(9,30))`
`rank_climo(...)`	Yet another useful ranking method. This allows one to rank attributes assessed over several to many years (climatological periods) to one another. Optional keyword argument `climatology` (default is 30 years) controls the span of time that data is collected and `increment` (default is 5 years) dictates the temporal distance between periods	`atl.rank_climo(20,"track_distance_TC", climatology=10, increment=1)`
`rank_storms(...)`	Print a report that compares storms and their attributes to each other. Similar to the above methods, other data is included in the report. See the docstring for info on `coordextent` kw usage	`atl.rank_storms(20,"HDP",1967)`
`from_map()`	Displays an interactive map where the user can plot a polyline of geographic coordinates. When completed, the list of `lon, lat` tupled coordinates are returned. This method was designed to supplement and ease the use of the `<TropicalCyclone>.crosses` method. See docstring for keywords Use keyboard shortcuts to move around: Zoom: `SHIFT` + arrows Pan: `CTRL` + arrows `L` toggles `landfall_assist` arrows. If using `landfall=True` in the aforementioned `crosses()` method, the arrows will show you the general direction that a cyclone's path must cross the segment from to be guaranteed as a "landfall".	`atl.from_map()`
`multi_season_info(...)`	Prints a report a gathered statistics based on a range of years. This is similar to the `info()` methods referenced in the next section. This could be thought of as an info method for a climatological period	`atl.multi_season_info(1991, 2000)` `atl[2010, 2019]`
`storm_name_search(...)`	Search through the entire Hurdat2 record for storms issued a name. If the positional keyword `info` is `True`, the matching storm's info method will print.	`atl.storm_name_search("Hugo")`
`output_climo(...)`	outputs a .csv file using the `csv` package of 1-year incremented climatological periods. This csv file can then be opened in a spreadsheet program. To compare or rank, the spreadsheet GUI layout is much easier to use especially due to instant sorting and filtering. This accepts a positional keyword argument (`climatology=30`).	`atl.output_climo(15)`
`output_seasons_csv(...)`	Similar to the above, but for seasons. It takes no arguments. In other words, it would be redundant to run it multiple times, because as the `hurdat2parser` package doesn't natively allow modification of the data, it would just output the same data over and over. The only exception would be when the Hurdat2 database is updated by the NHC. With this in mind, it will automatically write-over the csv if it already exists (file-name is auto-generated within the method).	`atl.output_seasons_csv()`
`output_storms_csv(...)`	Similar to above, but for individual storms.	`atl.output_storms_csv()`
`random()`	Returns a random `TropicalCyclone` object	`atl.random()`
`climograph()`	displays a graph of the climatological tendency of a variable over multiple seasons (see docstring for a how-to)	`atl.climograph("ACE", 10, 1, year1=1967)`
`coord_contains(...)`	Takes 3 tupled lat-lon coordinates. The purpose is to inquire whether the first arg (the test coordinate) is contained within a bounding box formed by the other two coordinates passed (returns a `bool`. This is generally just accessed via the ranking methods	`atl.coord_contains(` `[30.4,-85.0]`, `[31.5, 86.0],` `[29.0, 84.0]` `) -> True`
`BASIN_DICT`	A dictionary containing abbreviations (keys) and definitions (values) of various basins around the world that hurricane data is kept. This is referenced via the `basin()` method. The data used to form this object came from IBTrACS	`atl.BASIN_DICT`
`basin(season=None)`	Interprets and returns a readable string identifying the TC basin based on the storms within the record. This allows support of dynamically-created singular OR multiple Hurdat2 datasets OR individual seasons (if a `Season` object is passed to the method). The data used to form this property came from IBTrACS	`atl.basin() -> "North Atlantic Basin"
`record_range`	Returns a tuple of the beginning year and end year of the Hurdat2 record	`atl.record_range -> (1851, 2020)`

⇧ back to Methods & Attributes

Shared Methods and Attributes for `Season` and `TropicalCyclone`

Attributes	Description	Examples
`ACE`, `HDP`, or `MHDP` `ace`, `hdp`, or `mhdp`	Returns the specified Energy Index reading associated with the season or storm. The formula is very similar to ACE and HDP but for major hurricanes	`atl[1966].HDP` `atl.ivan.MHDP`
`cat45reach` `cat5reach`	For `Season` objects, returns the quantity of storms that reached category 4+ status or category 5 status (respectively) For `TropicalCyclone` objects, returns a `bool`, indicating if the TC ever achieved cat 4+ or 5 status (respectively)	`atl[2020].cat45reach -> 5` `atl[2020].cat5reach -> 0` `atl[2020]["Iota"].cat5reach -> False`
`duration`	Returns the length of the Season or life of the cyclone (Of note, the `TropicalCyclone` property disregards storm status but there are additional status-based duration variables available for that)	`atl[2022].duration`
`end_date`	The ending date of the Season or storm	`atl[1954, 16].end_date`
`end_ordinal`	The quantified day of the year of the ending date of the Season or storm	`atl[1954].end_ordinal`
`hurdat2()`	This method returns stringified hurdat2-formatted output of the season or cyclone data. By default, the in-interpreter version (with objective wind-extent data) is used. But you can specify to use the original.	`atl[2005].hurdat2()`
`landfall_<STATUS>` -can be TC, TD, TS, HU, or MHU	`Season`: qty of TC's that made landfall as the inquired status; `TropicalCyclone`: `bool` indicating if the storm made landfall while the inquired status -CAUTION: These attrs are exclusive of landfalls made while of stronger designation-	`atl[1996].landfall_TS -> 2` `atl[2011]["I"].landfall_HU -> True`
`landfalls`	SEE DISCLAIMER FOR LANDFALL INFO Sum of all landfalls (remember, a storm can make multiple landfalls). `<Season>.landfalls` is also an unfiltered aggregate of its storms landfalls. At the seasonal level, you'd probably be more interested in the attribute `landfall_TC` (see following section)	`atl[1960]["doNnA"].landfalls`
`output_shp()`	Generate a GIS-compatible Shapefile using the `shapefile` package	`atl[1988]["Gilbert"].output_shp()`
`output_geojson()`	Generate a GIS-compatible and text-readable `.geojson` file via the `geojson` package; can also be used in GIS applications	`atl[2000].output_geojson()`
`start_date_entry` `genesis_entry`	The`TCRecordEntry` when the season or cyclone began	`atl[1938].start_date`
`start_date` `genesis`	The moment when the season's first tropical cyclone designation occurred or moment the `TropicalCyclone` became a TC	`atl[1938].start_date`
`start_ordinal`	The quantified day of the year of the beginning moment of the Season or storm	`atl[1938].start_ordinal`
`stats()`	This method will display typically-sought-for stats. For `Season`s, it will also report respective ranks compared to all, or a subset of, other seasons. Please run `help` on a season stats method to get an in-depth overview of keywords For `TropicalCyclone`s, it is just a wrapper for the `.info()` method	`atl[2020].stats(1967)` `atl.hugo.stats()`
`summary()`	Prints detailed statistics for the season or life of the TC	`atl[2019]["dorian"].summary()`
`tc_entries`	Returns a list of `TCRecordEntry`'s from where a storm was designated as a tropical cyclone	`atl["_katrina"].tc_entries`
`track_distance_<STATUS>` -can be TC, TD, TS, HU, or MHU	The distance traversed while storm(s) was(were) at least the status designation	`atl[1961].track_distance_MHU`
`track_distance`	The calculated distance (in nmi) for the entire track of the storm (or aggregate of the season), regardless of status	`atl[1954]["hazel"].track_distance`
`<STATUS>reach` -can be TS, HU, or MHU	`Season`: qty of TC's that reached at least the inquired status; `TropicalCyclone`: `bool` indicating if the storm ever was designated as the inquired status	`atl[2010].HUreach -> 12` `atl[1991]["danny"].HUreach -> False`
`year`	Simply the year of the `Season` or `TropicalCyclone`	...

⇧ back to Methods & Attributes

`Season` Only Methods and Attributes

Attribute	Description	Example
`output_shp_segmented()`	Generates a shapefile including each segment from each tropical-cyclone from a given season; each individual segment from each individual storm will be represented	`atl[1932].output_shp_segmented()`
`output_geojson_segmented()`	Generates a geojson including each segment from each tropical-cyclone from a given season; each individual segment from each individual storm will be representeds	`atl[2003].output_geojson_segmented()`
`<STATUS>only` -can be TD, TS, or HU	Returns the quantity of TC's from a season that made were given the inquired designation, but never strengthened beyond it. `HUonly` implies Category 1 and 2 storms only. To inquire about `MHU`, use the `MHUreach` attr	`atl[1950].TDonly` `atl[2017].HUonly`
`tracks`	Returns the quantity of tropical cyclones from a season	`atl[1995].tracks`

⇧ back to Methods & Attributes

`TropicalCyclone` Only Methods and Attributes

Attribute	Description	Example
`ACE_no_landfall`	Returns the ACE of the storm prior to any landfall made	`atl["_ivan"].ACE_no_landfall
`<EI>_per_nmi` -can be ACE, HDP, or MHDP	Returns the inquired energy index divided by the track distance covered while the energy index was being contributed to (`ACE` → `track_distance_TS` or `HDP` → `track_distance_HU` as examples). WARNING! These attributes do not have any kind of threshold controls, so storms which were short-lived can have high values	`atl[1964][10].HDP_per_nmi` `atl[2016]["matthew"].ACE_per_nmi`
`atcf_num` `storm_number`	The number part of the TC's ATCFID; does not necessarily coincide with the order of occurrence.	...
`atcfid`	The issued id consisting of the Basin code, unique zero-padded integer, and season (year) when it occurred	...
`bounding_box` `bounding_box_<STATUS>`	A `BoundingBox` instance comprising of the maximum/minimum lat/lon extents of the cyclone. With no status suffix, it considers the entire track. With a status suffix, it only considers points where the cyclone had acquired that particular status or greater	`atl.faith.bounding_box` `atl[3,1896].bounding_box`
`crosses()`	Takes a list of coordinates (think polyline) and compares the track of the system to a polyline formed by the coordinates and determines if the track crossed it. One can optionally specify a range of direction that the cyclone is traversing if a crossing is True. Landfalls can also be detected by formulating the polyline. This feature tests if crossing occurs from the same direction as a landfall would occur.	☆ See How to Use crosses() for an example.
`duration_<SUFFIX>` *<SUFFIX> can be TC, TS, HU, MHU	Returns the aggregated length in days that the cyclone spent as on of the given statuses. These do account for storm status loss and possible reaquisition	`atl["_irma"].duration_MHU`
`entry`	list of `TCRecordEntry`'s of the storm	...
`gps`	Returns a `list` of tupled latitude and Longitude coordinates	`atl[1998]["MITCH"].gps`
`<EI>_perc_ACE` → -can be HDP or MHDP `MHDP_perc_HDP`	Simply the storm's HDP or MHDP divided by ACE or the MHDP divided by the HDP. Look at this as the percentage (as a float between 0 and 1) of the storm's ACE or HDP that was contributed to while a Hurricane or Major Hurricane, respectively	`atl[2017]["IRMA"].HDP_perc_ACE`
`info()`	Prints basic stats for the tropical cyclone	`atl[2005][12].info()`
`max_maxwind_radius` `max_rmw`	The highest observed radius where maximum winds were observed. Remember that this value does not necessarily coincide with when the systems highest maximum winds were observed	`atl.ida.max_maxwind_radius`
`maxwind`	Returns the highest maximum sustained wind-speed observed in the tropical cyclone	`atl["_katrina"].maxwind`
`maxwind_mslp` `minmslp_wind`	Returns the MSLP (wind) occurring at the time of peak-winds (minimum MSLP) respectively. These attributes were included because peak winds and minimum MSLP do not necessarily occur at the same time.	`atl[2015]["joaquin"].maxwind_mslp -> 934` `atl[2015]["joaquin"].minmslp_wind -> 120` * This example was given as Joaquin's peak winds (135) were not observed at the time of Joaquin's minimum MSLP (931)
`minmslp`	Returns the lowest recorded pressure of the TC	`atl[1955][10].minmslp`
`name`	The name given to the cyclone if reaching Tropical Storm (inc. subtropical) or Hurricane status. Many qualifying cyclones were not issued names in the past. These simply have a name of "UNKNOWN"	...
`perc_ACE` `perc_HDP` `perc_MHDP`	Return the percentage (in decimal form) of the contribution of the storm's ACE, HDP, or MHDP value to the season's value	`atl["_matthew"].perc_MHDP`
`status_highest`	Returns a formal description of the highest designated status acquired by the cyclone	`atl.sandy.status_highest`
`statuses_reached`	A list of cyclone statuses (as appearing in the hurdat2 record) issued to the cyclone during its life	...
`track_map()`	Generates a map of the storm's track using `matplotlib`. Check the docstring for ways to modify the output to your liking. This method is compatible with `jupyter notbook`s. It is recommended to use `%matplotlib notebook` at the beginning of your notebook to preserve interactivity. Use keyboard shortcuts to move around: Zoom: `SHIFT` + arrows Pan: `CTRL` + arrows `L` toggles the legend (things won't work right with this shortcut if using `block=False`)	`atl["_katrina"].track_map()`
`track_<EI1>_perc_<EI2>` -<EI1> can be TS, HU, or MHU -<EI2> can be TC, TS, HU, or MHU	Returns the the storm's <EI2> track_distance divided by the track distance while of status <EI1>. <EI1> must be of higher hierarchal status than <EI2>	`atl[2005][25].track_HU_perc_TC` `atl[2003]["Fabian"].track_MHU_perc_TS`

⇧ back to Methods & Attributes

`TCRecordEntry` Attributes

Only the most-common attributes will be referenced in this document. A comprehensive list is available via help

Attribute	Description
`areal_extent_<SUFFIX>` Suffix can be `TS`, `TS50`, or `HU`	The calculated area covered by the extent of winds of specified strengths. This is just an addition of `pi * r^2` from all quadrants. Units are `nmi^2`. Of note, wind extents are only available for storms since 2004. Also it's not guaranteed to be even a remotely-accurate figure because it's possible that data can be missing for quadrants while being present for others
`avg_wind_extent_<SUFFIX>` Suffix can be `TS`, `TS50`, or `HU`	The statistical mean of the reported wind-extents (quadrants). Wind extents are only available for storms since 2004
`direction()`	Returns the heading in degrees that the storm is going. A readable cardinal direction can be returned if `True` is passed to the method
`entrytime`	A `datetime.datetime` object of the entry's timestamp.
`extent_<STATUS>` Status can be `TS`, `TS50` or `HU`	A list of the entry's respective tropical storm, 50kt, and hurricane NE, SE, SW, and NW wind extents
`hurdat2()`	Returns a reassembled Hurdat2-formatted string. If the keyword `original` is `True`, the returned string will be identical to the line from the actual record used.
`is_TC`	Returns `True` if the system is a designated tropical cyclone at the time of this entry
`lat` or `latitude` `lon` or `longitude`	the lat/lon in `float` format
`lat_str` `lon_str`	The lat/lon in `string` format, reflecting the hurdat2 output (ex. `80.6W`)
`location` `location_rev`	A tuple of the latitude/longitude coordinates; `location_rev` is reversed in order, a longitude/latitude tuple; seemingly favored for GIS use.
`maxwind_radius` `rmw`	The Radius of Maximum Winds. Currently, it is only available for storms since 2021, and is assumed that in subsequent releases, this variable will continue to be updated. Though unknown if this data for previous seasons will (or can) be back-filled, as of Feburary of 2024, select pre-2021 cyclones may have this data included.
`mslp`	The Mean Sea-Level Pressure (in hPa or mb) at the time of entry-recording
`previous_entry` `next_entry`	Returns the entry prior-to or after the `TCRecordEntry` that it is called from
`saffir_simpson` `category`	The cyclone's Saffir-Simpson category, based soley on wind-strength. Of note, the Saffir-Simpson Scale only goes from 1-5. But for consistency within the module, Tropical Storms will report `0` for this attribute while Depressions (and weaker) will report `-1`
`speed`	The average speed between the previous entry and this one in nm/h Of Note, remember that the `Hurdat2` spatial resolution is 0.1 degrees latitude/longitude. So some appreciable error may be present
`status`	The designated 2-letter abbreviation representing the storm's status (same format from hurdat2)
`track_distance` `track_distance_<SUFFIX>` Suffix can be `TC`, `TS`, `HU`, or `MHU`	returns the distance tracked by the system from its genesis to the point of the entry. The variables with suffixes do account for status in their calculations
`wind`	The maximum-sustained winds at the time of entry-recording

⇧ back to Methods & Attributes
⇧ back to Contents

Landfall Data

An important point to keep in mind when viewing data and ranking, Hurdat2's landfall data is incomplete. It is progressively being updated in conjunction with the yearly release of the dataset. Please see the documentation Hurdat2 Format Guide for more detail on currently-available landfall data temporal scope.

⇧ back to Contents

How to use `.crosses()`

The crosses() method of TropicalCyclone objects tests if an intersection occurs between the cyclone's track and a polyline formed from a coordinate list. For the following test case, Hurricane Hugo (atl.hugo or atl[1989,11]) will be used. Click here for some pre-made coastlines available.

Formulate coordinate list

Using the convenient from_map method simplifies the creation of a custom polyline which can be immediately fed into the <TropicalCyclone>.crosses method.

>>> c = atl.from_map()

We know that Hugo made landfall along the South Carolina coast. Draw a polyline that parallels the coastline (Hold down Alt + Left-click to add points; Alt + Right-click removes points). You should see some arrows. These are "landfall assistants" to help you draw the segments in a way that will return True if using with the landfall=True keyword in the crosses method.

If testing for landfall or direction-dependent crossing, draw the polyline in a way where the arrows are pointing towards land or imaginary barrier

When finished, press Q. The list of coordinates will be stored in the c variable. Go ahead and check it out:

>>> c
[(-78.58, 33.865), (-78.954, 33.612), (-79.216, 33.191), (-79.816, 32.769), (-80.116, 32.582), (-80.378, 32.498), (-80.49, 32.348), (-80.865, 32.03)]
>>> _

It is a list of longitude, latitude tuples. Now we are ready to use the crosses method.

Run the crosses method on the `TropicalCyclone` of interest

To inquire if Hugo's track crossed the polyline, pass the coordinate list to the crosses method:

>>> atl.hugo.crosses(c)
True

It is important to note, with no landfall keyword in the crosses call, it was going to return True regardless if you drew it North-to-South or South-to-North. Add the landfall keyword.

>>> atl.hugo.crosses(c, landfall=True)
True

To show the difference that the keyword makes, draw the polyline again, but this time, draw from the GA border, north to the NC border. Notice how the arrows now point off-shore (below I simply cheated and reversed the polyline I had already made)

Now run the above code again.

>>> atl.hugo.crosses(reversed(c), landfall=True)
False

It returns False because the cyclone's track does not go from on-to-off shore, as indicated by the arrows.

If the arrows get in your way of making your line, feel free to pass True to the from_map method or simply toggle them off/on at any time by pressing N. They are more of a guide anyway.

The use of this method can be quite versatile. The general workflow when creating your own (or a pre-made list) goes like this:

use from_map method to get a coordinate path or use a pre-made coast list (next section).
- Do you care from what direction the crossing occurred (are you testing for landfall)?
iterate through all cyclones and use the crosses method:

>>> for tc in atl.tc.values():
        if tc.crosses(my_coordinates, landfall=True):
		    print(tc)

or generate a list that you can reference:

>>> cyclones = [tcyc for tcyc in atl.tc.values() if tcyc.crosses(my_coordinates, landfall=True)]

Included Coastlines with this Module

As a convenience, I included some polyline lists representing coastlines of interest intended to be used with the crosses method. They were prepared with the landfall=True of the crosses method in mind. These attributes belong to any Hurdat2 object, regardless of basin. Of note, these are primarily traces of the respective mainland, excluding many small islands. These were prepared with maps from NaturalEarth being a guide.

Coastline	Attribute Name
Eastern US (Maine to South Florida)	`us_east_coast`
US Gulf of Mexico border (South Florida to TX)	`us_gulf_coast`
Western US	`us_west_coast`
Eastern Mexico	`mexico_east_coast`
Western Mexico	`mexico_west_coast`
Eastern Central America	`centam_east_coast`
Western Central America	`centam_west_coast`
Cuba	`cuba_coast`
Jamaica	`jamaica_coast`
Hispaniola (Haiti and DR)	`hispaniola_coast`
Puerto Rico	`puerto_rico_coast`
Bermuda	`bermuda_coast`

⇧ back to Contents

Note on Ranking Methods

In the methods <Hurdat2>.rank_seasons and <Season>.stats, ranks are displayed via different methods. In particular, the differences are based on how ties (same values) are communicated and treated.

Dense Rankings

Dense ranking numbers are strictly value-based. Seasons with the highest value have a rank of #1. Seasons with the 2nd highest value have a rank of #2, no matter how many seasons are tied for #1, and so forth. This is understood briefly as 1-2-2-3 rankings.

Competition Rankings

I loosely call these "golf rankings". Ranking numbers are based upon the quantity of seasons that have a higher value than a respective member (in this case, a Season). So a season may have a value that is the 3rd highest (dense ranking of #3), but could have competition rank of #20, implying that 19 seasons had a higher value than it. This is understood as 1-2-2-4 rankings.

Prior to v2.3, only dense rankings were reported. The inclusion of competition rankings gives context and more understanding to dense rankings. For more info on ranking types, click here: Ranking Methods (via Wikipedia)

⇧ back to Contents

Access to Future Methods

In _future.py, I have some stuff that I've started to develop no where near ready to release. The methods are functional, but should be considered very unstable and perhaps even unreliable, as I don't maintain it much. The quickest way of accessing it is:

>>> import hurdat2parser._future as future

Valid classes reflect those of the main hurdat2parser object, namely future.Hurdat2, future.Season, future.TropicalCyclone, or future.TCRecordEntry. They'll be empty if I don't have anything I'm currently developing for that respective class/object. You can see what methods I have available by running dir() on the class.

When calling, you will need to manually pass a valid object (a substitute for self). For example:

>>> future.Season.track_map(atl[1984])

⇧ back to Contents

Roadmap

⇧ back to Contents

Credits

HURDAT Reference: Landsea, C. W. and J. L. Franklin, 2013: Atlantic Hurricane Database Uncertainty and Presentation of a New Database Format. Mon. Wea. Rev., 141, 3576-3592.
Haversine Formula (via Wikipedia)
Bell, et. al. Climate Assessment for 1999. Bulletin of the American Meteorological Society. Vol 81, No. 6. June 2000. S19.
G. Bell, M. Chelliah. Journal of Climate. Vol. 19, Issue 4. pg 593. 15 February 2006.
Hurdat2 Format Guide (PDF)
Natural Earth GIS Data (data extracted there-from to display maps)
Ranking Methods (via Wikipedia)

⇧ back to Contents

Copyright

⇧ back to Contents

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
hurdat2parser		hurdat2parser
CHANGES.md		CHANGES.md
LICENSE.txt		LICENSE.txt
README.md		README.md
hurdat2parser-2.3.0.1-py3-none-any.whl		hurdat2parser-2.3.0.1-py3-none-any.whl

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

hurdat2parser -- v2.3.0.1

Interpreting the Hurdat2 Tropical Cyclone Dataset using Python

Contents

Changes in this Version (2.3 and 2.3.0.1)

Installation

Importing the Module

Different ways to ingest data

Local / Offline

Online Retrieval

Alternate URL (experimental)

Readable Object Names

Hurdat2 Object Structure

Example calls

Methods and Attributes

`Hurdat2` Methods and Attributes

Shared Methods and Attributes for `Season` and `TropicalCyclone`

`Season` Only Methods and Attributes

`TropicalCyclone` Only Methods and Attributes

`TCRecordEntry` Attributes

Landfall Data

How to use `.crosses()`

Formulate coordinate list

Run the crosses method on the `TropicalCyclone` of interest

Included Coastlines with this Module

Note on Ranking Methods

Dense Rankings

Competition Rankings

Access to Future Methods

Roadmap

Credits

Copyright

About

Releases 2

Packages

Languages

License

ksgwxfan/hurdat2parser

Folders and files

Latest commit

History

Repository files navigation

hurdat2parser -- v2.3.0.1

Interpreting the Hurdat2 Tropical Cyclone Dataset using Python

Contents

Changes in this Version (2.3 and 2.3.0.1)

Installation

Importing the Module

Different ways to ingest data

Local / Offline

Online Retrieval

Alternate URL (experimental)

Readable Object Names

Hurdat2 Object Structure

Example calls

Methods and Attributes

Hurdat2 Methods and Attributes

Shared Methods and Attributes for Season and TropicalCyclone

Season Only Methods and Attributes

TropicalCyclone Only Methods and Attributes

TCRecordEntry Attributes

Landfall Data

How to use .crosses()

Formulate coordinate list

Run the crosses method on the TropicalCyclone of interest

Included Coastlines with this Module

Note on Ranking Methods

Dense Rankings

Competition Rankings

Access to Future Methods

Roadmap

Credits

Copyright

About

Resources

License

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

`Hurdat2` Methods and Attributes

Shared Methods and Attributes for `Season` and `TropicalCyclone`

`Season` Only Methods and Attributes

`TropicalCyclone` Only Methods and Attributes

`TCRecordEntry` Attributes

How to use `.crosses()`

Run the crosses method on the `TropicalCyclone` of interest

Packages