Tropycal

Key Highlights

- Recon data is now available back to 1989
- Improved summary plot methodology and plotting
- Numerous bug fixes

Contributors

tomerburg and contributed code to this release. splillo contributed code reviews to this release. kylejgillett contributed to issues that were resolved as part of this release.

New functionality

- Recon data can now be accessed back to 1989. This was previously available back to 2006.
- The default SSHWS colormap can now be used for flight-level wind as well as SFMR wind.
- A new utility function `utils.create_storm_dict()` is available to create storm dicts from custom user-input data.

Summary plot improvements

- Fixed NHC forecast initialization selection which was slightly offset from the actual time of the forecast issuance.
- Fixed bug in plotting cones crossing the international dateline.
- Function no longer crashes if a newly formed storm does not yet have a NHC/JTWC forecast issued.

Bug Fixes

- Erroneous recon HDOB obsevations are now removed by default.
- Fixed a bug in ``tracks.Storm.plot_ensembles()`` if coloring members by MSLP or sustained wind.
- Fixed a bug where JTWC forecasts for super typhoons displayed an extratropical marker.
- Fixed the operational ID for an East Pacific storm in 2020 that was classified as a TS in post-season analysis.
- Fixed bug in reading recon HDOBs which would crash if the HDOBs file from NHC's archive was improperly formatted (issue 173).
- Fixed incorrect return type in ``utils.get_hdobs_realtime()``.

This release consists of a few important bug fixes.

Contributors

tomerburg contributed code to this release. More-Grace contributed to an issue addressed in this release.

Bug fixes for ``TrackDataset.plot_summary()`` method:

- Fixed a bug where this function would crash if plotting a date where a storm had just formed.
- Changed the default plotting basin from global to the selected TrackDataset basin.
- Added the ability to plot TWOs between 2010 and 2014 using NHC's older TWO format.
- Added formation probability labels for TWO areas without an accompanying point label.
- Fixed display of storms with NaN forecast sustained wind.

Other bug fixes

- JTWC a-decks are now preferentially retrieved from NOAA SSD, falling back to UCAR if the former is not available. This extends the a-decks back to 2016 and adds many more models in realtime not available through the UCAR a-decks.
- Forecast dictionaries for invests retrieved from ``tracks.Storm.get_operational_forecasts()`` now remove a-deck data for previous designations of the same invest number.
- Fixed a bug in creating a TrackDataset instance using the JTWC Neumann reanalysis (Issue 168).
- ``utils.get_two_archive()`` no longer crashes if a TWO is not available for prior years.
- ``utils.get_two_archive()`` can now read in TWOs using NHC's older format between 2010 and 2014.

This release includes multiple bug fixes. Note that one of the changes in this update is not backwards compatible, and some of the functions were slightly revised to add features not included in the v0.5 release.

Contributors

tomerburg contributed code to this release. splillo contributed reviews to this release.

Non-backwards compatible changes

- In ``tracks.Storm.interp()``, the argument ``timeres`` is now ``hours``.

Modified functionality

- ``tracks.Storm.plot_ensembles()`` - the ``prop_members`` property dict has new keywords ``"color_var"`` ("vmax" or "mslp"), ``"cmap"``, and ``"levels"``, which allow to color the ensemble members by either maximum sustained wind or MSLP.
- ``tracks.Storm.interp()`` - a new "method" keyword argument is passed onto Scipy's interpolation method, allowing for non-linear interpolation methods such as "quadratic" or "cubic".
- ``tracks.Storm.plot_ensembles()`` and ``tracks.Storm.plot_models()`` now have a default "forecast=None" argument option, which plots the latest available forecast data. Provide a datetime object to plot any other forecast initialization time.
- ``tracks.TrackDataset.gridded_stats()`` has a "smooth" property to apply a spatial Gaussian filter. This feature existed before but was not included in the documentation until now.

Bug fixes

- Corrected an error where the "south_atlantic" basin was erroneously referenced to as "south_america", and added a plotting domain for this basin. This addresses issues 164 and 165.
- Corrected the source for custom Cyclone Catarina data.
- Added an option to specify ``basin="australia"`` when creating an instance of TrackDataset, which fetches the full IBTrACS dataset and subsets data within the Australian basin. This addresses issue 164 and older issue 85.
- Round JTWC sustained wind to the nearest increment of 5 where applicable.
- For ``tracks.Storm.plot_models()``, improved method for searching which model(s) are available for earlier years.
- Fixed bug in plotting recon dropsondes for earlier years.
- Fixed bug with plotting ensemble and model tracks and track density across the dateline. Note that the ensemble ellipse bug still exists in the dateline.
- Fixed bug where using any other window besides 1 hour for ``tracks.Storm.interp()`` resulted in inaccurate dvmax/dt, dmslp/dt and other derivatives.
- Improved colorbar plotting for some functions.
- Fixed bug in using ``fillcolor`` for plotting storm dots.

Key Highlights

- Added new realtime and mission-centric functionality to the recon module
- Recon data is now available back to 2006, and for the East and Central Pacific basins, with faster performance for reading in data
- Improved methodology of ``utils.get_basin()``, allowing for more accurate ACE calculations and Season objects within a basin
- New support for cross-basin storms between the North Atlantic and East Pacific basins
- New functionality to plot GEFS ensembles and operational models for Storm objects
- Added forecast wind radii for storms where this data is available

Contributors

tomerburg and splillo contributed code and code reviews to this release. GC-OCEAN, scaparotta and carolakaiser contributed to issues that were resolved as part of this release.

Non backwards compatible changes

- Previously deprecated function ``realtime.RealtimeStorm.get_nhc_discussion_realtime()`` has been removed. Use ``get_discussion_realtime()`` instead.
- ``tracks.TrackDataset.ace_climo()`` removed a previously non-functional argument "date_range" and replaced it with "month_range".

New classes

- `RealtimeRecon` - retrieves for the latest active recon missions and allows to retrieve a Mission object for each mission
- `Mission` - unlike ReconDataset and its accompanying subclasses (hdobs, dropsondes, vdms), Mission objects are not storm-centric, meaning there is no underlying storm track that recon observations are centered relative to. This means Mission objects have far fewer capabilities, but can be much quicker to use.
- Mission objects do have a new `status` variable for HDOBs that determines the status of the mission (e.g., "En Route", "In Storm"), and can be used to spatially subset the `Mission.plot_points()` method. The latest status of the Mission object can be retrieved using the `Mission.status()` method.

New functions

- `recon.hdobs.plot_time_series()` - plots time series of HDOB observations of one or two variables on the same axis
- `recon.ReconDataset.get_mission()` - retrieves a Mission object for a requested mission number
- `tracks.Storm.plot_ensembles()` - This function overhauls the now-removed `plot_gefs_ensembles()` function, fixing many bugs in data retrieval in that prior function and adding cumulative track density. This also addresses 123.
- `tracks.Storm.plot_models()` - This function plots all operational models initialized at a requested time, in addition to optionally overlaying Best Track verification.
- `tracks.Storm.get_recon()` - This function overhauls the previous iteration of this function, now set to retrieve all recon observations for the storm and store the resulting ReconDataset object as an attribute of Storm.
- `realtime.Realtime.update()` - updates Realtime objects with the latest data
- `utils.calc_ensemble_ellipse()` - This function calculates an ensemble location spread ellipse following the methodology of Hamill et al. (2011).

Code Improvements

- urllib3 is now used to read in recon data from NHC, substantially speeding up runtime
- Realtime objects now have attributes that can be accessed as a dictionary via the `attrs` attribute
- Added new `plot_gridlines` argument to the `map_prop` dict to disable/enable plotting gridlines
- Added an option of plotting wind barbs for recon `plot_points()` method
- Added a new colormap `category_recon` for select recon plots, detailed in the documentation, adding a new color between 50-64 knots
- VDMs can now be optionally plotted in ``Mission.plot_points()``
- Added a separate HDOBs parser for 2006 data, the ability to parse VDMs and dropsondes going back to 2006, and hard-code HDOBs URLs prior to 2014 to allow for recon data to be fully read in back to 2006
- Added the ability to read in recon missions in the East and Central Pacific basins
- Added the option to determine whether a recon mission is "in storm" based on height instead of pressure, as pressure data is not available prior to 2007
- Added shapefiles delineating the North Atlantic & East Pacific basins to more accurately reflect whether a tropical cyclone is in either basin. This improves the results from ``utils.get_basin()``. This now means cross-basin Storm objects no longer have a constant value for "wmo_basin" regardless of which basin they're in.
- If reading in TrackDataset with ``basin='both'``, cross-basin storms are merged into a single storm if they were previously split with 2 separate names (e.g., Cesar-Douglas 1996), and any cross-basin storm with duplicate entries (e.g., Otto 2016) is filtered with duplicates removed.
- Improved rounding of storm data with lat/lon rounded to nearest tenth, MSLP to nearest integer, and ACE to nearest 0.001.
- Season objects are now supported for global data (``basin='all'``) and for combined Atlantic/East Pacific data (``basin='both'``).
- ``tracks.TrackDataset.ace_climo()`` is now supported for IBTrACS in the West Pacific, North Indian & global basins. South Hemisphere only basins are not fully supported yet.

Bug Fixes

- Fixed bug where summary plots had a mismatch between the cone of uncertainty days
- Fixed bug where a newly formed tropical cyclone continued to carry TWO formation outlook probability
- Added pyshp as a requirement (Issue 156)
- Fixed bug where ReconDataset crashes for newly formed storms without any recon missions yet
- Fixed bug in summary plots where marker size wasn't included in `two_prop`
- Fixed bug where HDOBs weren't sorted by time for some storms
- Fixed bug where some VDMs and dropsondes weren't successfully parsed thus crashing the code
- Fixed bug where summary plots crash if using JTWC as source
- Re-added option to parse JTWC forecasts from NOAA SSD as JTWC server is experiencing issues again
- Fixed bug in parsing HDOBs where extra data in the file causes the parser to crash
- Fixed a bug where recon missions could not be read in for years where a storm was added to HURDATv2 post-operationally (e.g., 2006)
- Added a filter to set erroneous or missing SFMR observations to NaN
- Fixed a bug where dropsondes didn't plot in ``ReconDataset.plot_summary()`` for earlier years where no information on the top lat/lon is available
- Accumulated Cyclone Energy (ACE) is now calculated only within the selected basin(s). Previously storms that existed/entered a basin had their ACE from outside the basin incorrectly counted as part of that basin's ACE.
- For cross-basin storms, the ``Season.summary()`` method, and accordingly any function that relies on it (e.g., season statistics, basin climatology) now displays the cyclone statistics only within the selected basin(s). For example, if a storm peaked at 50 kt within the selected basin but intensified to 120 kt outside of the basin, its peak intensity within a Season object is now listed as 50 kt instead of 120 kt.
- Fixed a bug with erroneous "operational_id" values for Central Pacific storms.
- Add JTWC a-deck archived forecast retrieval from 2020 onwards
- Add multi-dimension support for `utils.accumulated_cyclone_energy()`
- Season objects now display the proper number of storms & storm ACE regardless of NaNs in wind data
- Manually removed references to an erroneous storm in the North Indian IBTrACS dataset
- Fixed functions relying on `tracks.Season.summary()` such as `tracks.TrackDataset.to_dataframe()` and `ace_climo()` where attempts to retrieve seasons without storms caused an error. This addresses 160.
- For `realtime.Realtime.plot_summary()`, forecasts are no longer plotted if they are outdated by over 12 hours
- Fixed season start date calculations for multi-basin TrackDataset instances

Both this update and the preceding v0.4.1 update incorporate important bug fixes.

Contributors

tomerburg contributed code to this release.

Bug fixes

- The original v0.4 release didn't properly remove invests from Realtime objects once they are classified as tropical/potential tropical cyclones. This was fixed with v0.4.1.
- JTWC source for Realtime objects is now functioning again
- Fixed a bug where some recon plots crash for potential tropical cyclones
- `tracks.TrackDataset.to_dataframe()` previously crashed if a season solely contains a potential tropical cyclone
- `recon.hdobs.plot_swath()` inadvertently removed a variable reference causing it to crash, which v0.4.2 fixed
- An infinite import loop was removed by rearranging numerous plotting functions

Key Highlights

- Overhauled the Recon module with a new data source and vastly expanded functionality
- Added historical tropical cyclone track analogs by point or shape functionality to TrackDataset
- Added new utility functions, including retrieving NHC Tropical Weather Outlook probabilities and matching these to realtime invests
- New functions to plot current or archived global/regional tropical cyclone activity summary plots
- Many new example scripts have been added to documentation, as well as overall improved documentation
- Updated support for newest Matplotlib and Cartopy versions, alongside many bug fixes

Contributors

tomerburg and splillo contributed code and code reviews to this release.

Non backwards compatible changes

- Attributes of Storm and RealtimeStorm objects were previously accessed via `storm.coords`. They are now accessed via `storm.attrs`.
- Variables/arguments previously named `doInterp` were renamed to `interpolate_data`. This will cause older code referring to `doInterp` to return an error.
- For `tropycal.tracks.TrackDataset.plot_storms()`, the keyword argument `labels` has been removed. This has now been replaced by a `plot_names` property option in the `prop` kwarg. This can now be used for plotting Season objects as well with the option to remove plotting storm names on the map.

Recon module

The recon module was completely overhauled with a new infrastructure replacing the old one. As part of this, recon data is now read in from the National Hurricane Center (NHC) instead of Tropical Atlantic. Available classes within recon include:

- recon.ReconDataset
- Storm and RealtimeStorm objects are initialized with an empty ReconDataset instance stored as an attribute. This can be used to plot a summary of all recon missions for this storm, find active missions for any given time, or initialize any of the following sub-classes.
- recon.dropsondes
- This class contains all dropsonde data for this storm. The primary methods include:
- `dropsondes.plot_points()` - plot all dropsonde points by variable on a map
- `dropsondes.plot_skewt()` - plot one or more skew-T's for this storm
- `dropsondes.to_pickle()` - convert to pickle file that can later be re-read instead of re-downloading data each time
- `dropsondes.sel()` - select dropsondes by various thresholds
- `dropsondes.update()` - update this object with the latest data for realtime missions
- recon.hdobs
- This class contains all High Density Observations (HDOBs) data for this storm. The primary methods include:
- `hdobs.plot_points()` - plot all HDOB points by variable on a map
- `hdobs.plot_hovmoller()` - plot an azimuthally averaged time-radius hovmoller derived from HDOBs
- `hdobs.plot_map()` - plot one or more map(s) of instantaneous HDOBs spatially interpolated to a grid
- `hdobs.plot_swath()` - plot spatial cumulative swath of HDOBs on a map
- `hdobs.gridded_stats()` - interpolate HDOB observations to a spatial grid
- `hdobs.to_pickle()` - convert to pickle file that can later be re-read instead of re-downloading data each time
- `hdobs.sel()` - select HDOBs by various thresholds
- `hdobs.update()` - update this object with the latest data for realtime missions
- recon.vdms
- This class contains all Vortex Data Messages (VDMs) for this storm. The primary methods include:
- `vdms.plot_points()` - plot all VDM points by variable on a map
- `vdms.to_pickle()` - convert to pickle file that can later be re-read instead of re-downloading data each time
- `vdms.sel()` - select VDMs by various thresholds
- `vdms.update()` - update this object with the latest data for realtime missions

New functions

- realtime.Realtime
- `Realtime.plot_summary()` - Plot summary of latest realtime tropical cyclone/invest/outlook activity
- realtime.RealtimeStorm
- `RealtimeStorm.get_realtime_formation_prob()` - Matches any invest in NHC's domain to NHC Tropical Weather Outlook (TWO) formation probability
- tracks.TrackDataset
- `TrackDataset.analogs_from_point()` - Retrieve storms within a radius of a point and their closest approach to the point
- `TrackDataset.analogs_from_shape()` - Retrieve storms within a bounded shape provided by a list of lat/lon coordinates
- `TrackDataset.plot_analogs_from_point()` - Plot output from `analog_from_point()`
- `TrackDataset.plot_analogs_from_shape()` - Plot output from `analog_from_shape()`
- `TrackDataset.plot_summary()` - Equivalent to `Realtime.plot_summary()` but for any archived date
- tracks.Storm
- `Storm.get_nhc_forecast_dict()` - Retrieve NHC official forecast dictionary by time
- utils
- `utils.get_two_current()` - Retrieve current NHC Tropical Weather Outlook (TWO) shapefiles
- `utils.get_two_archive()` - Retrieve archived NHC Tropical Weather Outlook (TWO) shapefiles