Tropycal

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

Highlights

- Many bug fixes and underlying code cleanup.

Contributors

tomerburg contributed code to this release. splillo contributed code reviews to this release. brianmapes and cdeciampa contributed to issues that were addressed in this release.

New Functions

The NHC cone generation code was previously internal only. This has now been split into two functions accessible via utils:
- `utils.nhc_cone_radii()` - returns a dict of NHC cone of uncertainty radii by basin, year and forecast hour(s).
- `utils.generate_nhc_cone()` - returns a gridded NHC cone of uncertainty given a forecast dict, basin, year and days.

Specific Bug Fixes

- The newest versions of matplotlib changed the syntax for certain legend axes functionality. This bug fix adds a check that should work for both newer and older versions of matplotlib (Issue 146).
- SSL certificate verification continues to be an issue with JTWC data. The previous release didn't address this for real-time forecasts from JTWC, which this update does.
- A few storms in the Atlantic HURDATv2 basin were affected by a bug that returned incorrect longitudes east of the Prime Meridian. This has been fixed with this release.
- Rain dataset objects previously had a hard-coded URL to WPC's database. This fix now allows users to input their own rainfall database (Issue 141).
- `utils.get_basin()` previously incorrectly returned 'North Pacific' instead of 'East Pacific'.
- A bug fix was added for the time frame before the start of the hurricane season when the previous year's Best Track files were removed from the main ATCF directory, but have not yet been added into HURDATv2. This now reads in these storms from UCAR's archived best track repository to fill in that gap.

Highlights

- This urgent bug fix adds a workaround to recent issues with accessing data via the JTWC real-time server.

Contributors

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

Specific Bug Fixes

- Recent troubles with accessing real-time data from the JTWC server caused Tropycal code to crash when creating an instance of a Realtime object. This fix adds the option of adding a ``ssl_certificate=False`` argument when creating an instance of a realtime.Realtime object to get around this issue.
- Some invests in the JTWC area of responsibility are assigned tropical depression status even if they haven't been classified as such. This bug fix ensures storm types are classified as "invest" for these cases.
- Some files in the JTWC real-time server include "future" storms (e.g., a file containing dates a year in the future). This bug fix removes these cases from being read into realtime.Realtime objects.

Highlights

- Many bug fixes and cleaning up underlying code.

Contributors

tomerburg contributed code to this release. splillo contributed code reviews to this release. srmullens and raybellwaves contributed to issues that were addressed in this release.

Specific Bug Fixes

- Invest functionality was added previously to Realtime objects, but not to global invests. This update adds global invests.
- Geopy was removed as a dependence a while back, but was not entirely removed from the package configuration script. This bug fix removes any remaining Geopy mention.
- Fix a bug with storm ID length in the utility get_basin() function.
- Identified and fixed a bug where storms at the end of a calendar year in the Southern Hemisphere that had an ID for the following year (e.g., "SH012022" in November 2021) weren't identified in Realtime objects.
- Fixed a bug that prevented multiple functions from using the same axis.
- Fixed a bug with the Cartopy lat/lon label syntax that was changed in newer Cartopy versions.
- Hard-coded a fix for reading HURDATv2 data, as a recent change to the default URL used for HURDATv2 inadvertently created duplicate entries
- SPC's tornado database hasn't updated through 2020 nor 2021, as 2019 remains the most recent year available. This change to TornadoDataset ensures the last 5 years are checked for the most recent year containing tornado data.

Highlights

- Many bug fixes and cleaning up underlying code.
- Multiple functions from ``tropycal.tracks.TrackDataset`` were previously inadvertently deleted, and have been restored with this update.

Contributors

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

Specific Bug Fixes

- Some post-tropical cyclones have had their storm type incorrectly assigned as a tropical cyclone in ``realtime.RealtimeStorm.get_realtime_info()``. This has been changed to "Post-Tropical Cyclone".
- Storm plotting functions are split between dashed lines for non-tropical cyclones and solid lines for tropical cyclones. The immediate timestep before a TC forms was plotted with a solid black line, but has been changed to a thin black line.
- When adding invest handling capability for Tropycal v0.3, a case that wasn't considered is a tropical cyclone which became post-tropical, then re-assigned as an invest to monitor the potential for re-transitioning into a tropical cyclone. The resulting unintended behavior was for Realtime objects to re-assign those as active tropical cyclones, even though no operational products are produced for such cases. This bug fix reassigns any post-tropical cyclone that has not been tropical for 18+ hours as an invest.
- Realtime objects now delete invests after 9 hours of inactivity, vs. 18 hours for tropical cyclones. In the future this can be optimized further to automatically delete invests that were re-classified as tropical cyclones.
- When reading in JTWC data into a Realtime object, the "TY" typhoon storm type is reassigned to "HU" (hurricane) for continuity purposes between different basins. For some data sources, a Super Typhoon "ST" storm type is included, which was previously not accounted for, resulting in an incorrect classification as an extratropical cyclone. This bug fixes ensures super typhoons are also reassigned to a "HU" storm type.
- When plotting a RealtimeStorm object via ``realtime.RealtimeStorm.plot()``, the displayed name treated invests and post-tropical cyclones equally. This has now been fixed such that invests will have their names displayed following invest naming conventions (e.g., "Invest 91L"), while post-tropical cyclones that have been re-designated as invests retain their original name (e.g., "Tropical Storm Peter").
- Central Pacific storms can now have their previous operational forecast data (from the a-deck) accessed.
- The function ``tracks.Storm.sel()`` only accepted hard int or float types, and crashed if any other variation of int or float types (e.g., numpy.int32) were input. This bug fix ensures any type of integer or float, including all numpy variations, can be accepted as arguments.
- Several functions from tracks.TrackDataset were discovered to have been inadvertedly removed in a PR last year, and were re-added:
- ``tracks.TrackDataset.to_dataframe()``
- ``tracks.TrackDataset.climatology()``
- ``tracks.TrackDataset.season_composite()``

Highlights

- New Rain module is available, incorporating the tropical cyclone rainfall database provided by the Weather Prediction Center (WPC).
- New Cartopy plotting utility is available for quickly plotting storms on an existing axes instance.
- Major bug fixes, some non-backwards compatible changes (more details below), and cleaned up underlying code.
- ``tropycal.realtime`` now provides multiple options for reading in data from the Joint Typhoon Warning Center (JTWC) given recent problems with this data source in Summer 2021.
- ``tropycal.realtime`` now includes invest handling capabilities for areas under the National Hurricane Center (NHC)'s area of responsibility.
- Documentation has now been updated and improved, with more sample code included.
- Tropycal can now be installed via conda-forge.

Contributors

tomerburg, TomerAberbach, raybellwaves and splillo contributed code to this release.

Specifics

Non backwards compatible changes:
- Plotting functions no longer have a ``return_ax`` argument, except for Tornado and Recon. By default, the axes instance is now returned, along with additional information if specified in the arguments where applicable.
- All plotting functions that had the argument "plot_all" have been renamed to "plot_all_dots" to make the name more intuitive. If true, then all location dots of a tropical cyclone's observed location are plotted even if they fall outside of the standard 0/6/12/18z 6-hour increments.
- All plotting functions now have a "save_path" argument, to allow for saving the image generated. Some of these were previously a mix of only specifying the directory path or including the file name as part of the path; as of v0.3, this now expects to receive a relative or full path that includes the file name, making this consistent across all functions.

New modules:
- tropycal.rain
- Created a new module to read in, interpolate, and plot tropical cyclone rainfall data from the database provided by the Weather Prediction Center (WPC).

New features and updates:
- tropycal.realtime.Realtime:
- Added several options for reading in JTWC data, or to not read it in at all, when initializing an instance of Realtime.
- Invests from the NHC area of responsibility can now be read in.

- tropycal.utils:
- New Cartopy utilities were added, to allow for quick plotting of Storm objects on existing axes.

- General plotting capability
- New options were added for customizing plotting storm tracks, such as using a customized colormap or coloring by wind or minimum pressure
- Storm track labels can now be added for ``TrackDataset.plot_storms()``

Notable bug fixes:
- Fixed bug in filter_storms where lon values were only accepted from 0 to 360
- Fixed bug in storm plotting options where extratropical points were a mix of solid and dash line
- Removed arguments from multiple functions that were either unused or would break the code if not used in a very specific manner (the latter can be added back later after more thorough testing)
- Fixed bug when plotting seasons directly from an instance of Season