Tropycal

This release of Tropycal includes bug fixes primarily applied to the rain and recon modules.


Underlying Code Improvements

- Users now need to provide an SSL certificate chain when attempting to access JTWC's ATCF server for realtime objects. The preferable method of accessing JTWC realtime data is using `source="ucar"`.
- Realtime invests linked to TWO areas can now have their name labeled in the `realtime.Realtime.plot_summary()` function via the `two_prop` keyword argument.
- Using `pkwnd` for recon now allows for use of the default category windmap.
- Removed redundant attempt to fetch online URL for storm objects when creating recon instances.
- Optimized code for the placement of the map legend in `recon.ReconDataset.hdobs.plot_points()` to avoid obscuring data as much as possible.

Bug Fixes

- Improved methodology to find the latest available multi-model forecast
- Recon wind speed colors, both dots and barbs, were previously incorrectly plotted for `recon.ReconDataset.hdobs.plot_points()`. This has now been corrected.
- Fixed improper zorder of latitude & longitude lines for rain plots.
- Better filter out improper rain entries.
- Functions that require interpolated recon data now remove flagged entries.

This release of Tropycal includes many bug fixes, some as a result of Hurricane Dora which crossed the international dateline in real time, while adding some new functionality.

It should be noted that due to an error in uploading this release to PyPI, version 1.1 was skipped such that this is the latest version.

Key Highlights

- The minimum Pandas requirement was changed from v0.23.0 to v1.3
- New SHIPS analyzing functionality was added to Storm objects
- Many underlying bug fixes discussed in more detail below

Contributors

Thanks to those that opened issues or PRs that were resolved with this release: lisalenorelowe gameskip mguzelevich

New functionality

- Several new functions were added:
- `tracks.Storm.plot_models_wind()` - makes a plot of multi-model forecast sustained wind.
- `tracks.Storm.get_ships_analysis()` - constructs a Storm object consisting of SHIPS analyses and their associated storm environmental parameters.
- `realtime.RealtimeStorm.get_ships_realtime()` - fetches a SHIPS object containing the latest available SHIPS analysis for this storm.
- `recon.hdobs.gridded_stats()` - this function now properly works after fixing numerous bugs, and rearranging plotting code to avert a circular import error from the recon module.
- The function `utils.generate_nhc_cone()` now allows the user to select a custom cone grid resolution. This has further been added as a customization option for `tracks.Storm.plot_nhc_forecast()` and `realtime.RealtimeStorm.plot_forecast_realtime()`.
- For the previously mentioned two plotting functions, new options are available for displaying the valid storm time in various time zones.

Underlying Code Improvements

- Improved time efficiency for creating multiple summary plots from a realtime object by storing all storm forecasts and TWO shapefiles within the object.
- Substantially cleaned up underlying plotting code, and removed file `plot.py` in the Rain module as this functionality is now handled through the Tracks module. This fix also ensures all plotting functions have access to the same `prop` arguments, such as the visibility of latitude & longitude lines.

Bug Fixes

- Due to Pandas removing a previously deprecated argument, the minimum Pandas version requirement has changed from v0.23.0 to v1.3 (Issue 188 and PR 187).
- Fixed bug where the setting to substitute in HURDATv2 data for Atlantic & Pacific basins within IBTrACS objects raised an error (Issue 190).
- Fixed a bug in plotting realtime JTWC forecasts which previously raised an error.
- Fixed a bug where providing custom properties for modifying the NHC cone would not modify the cone in `tracks.Storm.plot_nhc_forecast()` and `realtime.RealtimeStorm.plot_forecast_realtime()`.
- Tweaked the threshold for shifting longitudes for plotting cross-dateline storms as a result of fast-moving Hurricane Dora.
- Fixed two bugs in `realtime.RealtimeStorm.get_realtime_info()`:
- Storms which had just been initiated by NHC but without the public advisory files having been uploaded to ATCF would raise an error.
- If a storm only has a single coordinate to date, a value of N/A is now returned for the forward motion direction and speed.
- The `"basin"` attribute of realtime storms in JTWC's area of responsibility now represents its current basin, not its basin of origin.
- Fixed several bugs for storms in JTWC's area of responsibility that crossed over from the East Pacific but retain an East Pacific identifier of "EP", as a result of Hurricane Dora.
- Improved error catching for parsing some erroneous a-deck files.
- Fixed bug where `tracks.TrackDataset.gridded_stats()` did not correctly interpolate some percentile thresholds.
- Fixed bug for realtime JTWC invests through UCAR's archive such that for a given invest ID, previous invests with the same ID but from months earlier are discarded.
- Fixed bug in plotting multiple storms (e.g., `tracks.TrackDataset.plot_storms()` or `tracks.TrackDataset.plot_analogs_from_shape()` such that passing a prop key and value of `"plot_names":True` now displays the storm label within the plot if the start and end points are outside of the plot domain.
- All arguments of "save_path" now have consistent behavior (Issue 188).

This is an critical bug fix release due to failure of numerous functions to correctly plot the NHC cone of uncertainty.

This minor release includes numerous bug fixes.

Contributors

tomerburg contributed code to this release.

Bug Fixes

- SHIPS parser now reads the storm name and forecast initialization directly from the provided text content.
- Fixed bug in plotting cross-dateline forecast track for SHIPS summary plot.
- Added Oceanic Heat Content (OHC) unit label in SHIPS summary plot.
- Fixed bug in summary plots where some Tropical Weather Outlook (TWO) probability labels would fail to plot.
- Increase distance threshold required to link invests to TWO points for rare cases where the point's coordinates are well removed from the most recent invest coordinates.
- Improved method to delineate North Atlantic vs. East Pacific basin for rare cases of multiple Central America landfalls from different basins, affecting a handful of storms (e.g., Julia 2022).
- Fixed bug in computing track density for `tracks.Storm.plot_ensembles()`.
- Some unnamed storms (e.g., AL012023) previously named "INVEST" are now named "UNNAMED".
- Add credit to plots previously missing it.

This is the first major release of Tropycal. From this point onward, following semantic versioning, major releases (e.g., v2.0, v3.0) will consist of non-backwards compatible changes.

Key Highlights

- Non-backwards compatible changes include changing `date` to `time`, and changing numerous function arguments
- Added new module to read and analyze SHIPS data
- Added new standalone Cartopy plotting functionality
- Numerous major bug fixes, including NHC's new 7-day tropical weather outlooks and improved handling of IBTrACS data

Contributors

tomerburg contributed code to this release. splillo contributed code reviews to this release. Additional thanks to Jack Beven of the National Hurricane Center for feedback used to prepare this release, and to Matthew Onderlinde for help with the updated Tropical Weather Outlook (TWO) archive.

Additional thanks to those that opened issues that were resolved with this release: Justin5999, bmaschino, lpulmano, kylejgillett

Non-backwards compatible changes

- All attributes and function arguments of `date` have been changed to `time`. For example, `storm.date` is now `storm.time`.
- Numerous functions have arguments such as `year_range`. These have been changed to `climo_bounds`.
- Plotting functions in `tracks.TrackDataset` no longer have a `plot=True` argument, instead returning the axes by default.

New module

A new `ships.Ships` class was added, aiding in storing and analyzing SHIPS data. These can be retrieved from Storm objects, which now have two new methods to assist with this:

- `tracks.Storm.search_ships()` - search for all available initialization times SHIPS is available.
- `tracks.Storm.get_ships()` - retrieve instance of Ships for the requested initialization time.

New functionality

- The new HAFS-A and HAFS-B models became operational in June 2023. These models are now available in the `tracks.TrackDataset.plot_models()` function.
- `tracks.TrackDataset.ace_climo()` plots can now be subset by month ranges.
- Attributes are now available for `tracks.TrackDataset` objects.
- Several new functions were added:
- `tracks.TrackDataset.search_time()` - search for all storms that existed at a requested time.
- `utils.plot_two()` - standalone Cartopy functionality now allows for plotting Tropical Weather Outlooks (TWOs) on an axes instance.
- `utils.plot_cone()` - standalone Cartopy functionality to plot a cone of uncertainty.
- `utils.ships_parser()` - parse SHIPS text into formatted dictionaries.

Functionality Improvements

- By default, `tracks.TrackDataset` now automatically searches for the latest HURDATv2 dataset published on NHC's website, replacing the HRD version as the default HURDATv2 dataset.
- Acceptable storm types now include 'TY' and 'ST', which are used in place of 'HU' outside of NHC's area of responsibility.
- Applied a fix to TrackDataset to attempt to objectively determine potential tropical cyclones that never became TCs.

Underlying Code Improvements

- Overhauled test scripts and added sample data to be used for tests.
- Consolidated duplicated functionality such as ACE calculations and custom storm dictionaries to use functions in the `utils` module.
- Removed unused imports, deprecated imports, and applied basic autoformatting.
- Moved custom storm tracks such as Cyclone Catarina to a standalone text file format, allowing for potential future additions of custom storm data.

Major Bug Fixes

- A change to NHC's website in 2023 resulted in a change in where archived TWOs are stored. Tropycal code now uses their new locations on the website.
- NHC added new 7-day TWOs operationally in 2023. Summary plots now use these instead of expecting a 5-day TWO.
- `tracks.Season.summary()` now displays the correct number of overall storms that formed. Count of named storms, hurricanes and major hurricanes were not affected by this bug.
- South Hemisphere basin handling was added for obtaining `tracks.Season` objects, as well as the following functions:
- `tracks.TrackDataset.ace_climo()`
- `tracks.TrackDataset.hurricane_days_climo()`
- `tracks.TrackDataset.climatology()`
- `tracks.TrackDataset.season_composite()`
- `tracks.TrackDataset.ace_climo()` now correctly calculates global ACE per calendar year.
- Corrected the current basin for realtime storms in JTWC's area of responsibility.
- Corrected IBTrACS parsing which in rare instances read duplicate entries, incorrectly merged storms and displayed incorrect storm IDs.
- `tracks.TrackDataset.plot_summary()` now works for IBTrACS datasets, and fixed a bug in cross-dateline storms.
- Removed outdated references that caused plots in the `rain` module to fail.
- Fixed an intermittent bug in parsing realtime JTWC forecasts.
- Analog functions now correctly use inclusive date ranges.
- `tracks.TrackDataset.rank_storm()` now correctly returns only the ACE for the requested date range and domain.

Minor Bug Fixes

- `tracks.Storm.plot_ensembles()` now works for times before a tropical cyclone officially formed.
- Removed references to recently deprecated `np.int` that caused bugs with newer version of numpy.
- Fixed a bug in plotting storms that completely lack sustained wind data.
- Fixed a bug in plotting cross-dateline storms.
- Fixed a bug in plotting `tracks.TrackDataset.wind_pres_relationship()` that had syntax deprecated in Python 3.11.
- Using the `basin='both'` argument when creating an instance of `tracks.TrackDataset` now correctly recognizes it as a basin in NHC's area of responsibility.
- Correctly retrieve the most recent NHC discussion in `tracks.TrackDataset.get_nhc_discussion()`.

This release consists of a few bug fixes & cleaned up documentation, as well as new example code for Realtime using the active September 2022 Atlantic basin.

Contributors

tomerburg contributed code to this release.

Bug fixes and underlying code revisions

- Used new function to greatly speed up ensemble track density calculations, allowing changing of the ``tracks.Storm.plot_ensembles()`` function to a default argument of ``interpolate=True``
- Fix plotting ensemble track density for South Hemisphere cyclones, which previously failed to plot
- JTWC Best Track data adds tropical cyclone storm types (e.g., sub/tropical depression or storm) to active invests (e.g., Invest 97S). This fix ensures when plotting the storm track, the storm type in the title is "Invest" for such cases
- Fix storm type in the storm track plot title for IBTrACS using WMO data (``ibtracs_mode="wmo"``) for storms that lack a conventional ID string