Tropycal

This release of Tropycal includes many bug fixes, plus an overhauling of the recon interpolation functionality to more accurately interpolate data, include new options to control the method of interpolation, and fix outstanding bugs.

Key Highlights

- Overhauling of recon interpolation algorithm
- Many underlying bug fixes discussed in more detail below

New functionality

- `tracks.TrackDataset.ace_climo()` - added a new optional argument `maximum_bounds` that calculates maximum ACE records for a separate year range than `climo_bounds` (e.g., climatology is calculated from 1950-2020, but extremes from 1900-2020)
- `tracks.TrackDataset.plot_models_wind()` - added the COAMPS model as an option.
- `utils.dynamic_map_extent()` - added more options to control the aspect ratio

Recon interpolation updates

- **Hovmollers, maps, and wind swaths**: these functions no longer use observations above 475 hPa
- **Hovmollers & wind swaths**: added a new `missing_window` argument to ignore interpolation where data is missing beyond a certain hour threshold (default is 24 hours)
- **Hovmollers, maps, and wind swaths**: added a new `filter_outer_obs` argument to ignore radii where only a single data point is available, as this interpolates that data point azimuthally even in portions of the cyclone where no data is available
- **Maps**: Selecting a single time vs. a time range now create identical maps, whereas previously the maps varied depending on the time or time ranges passed.
- **Maps**: Added an optional `output_interval` argument to control how often to plot data in minutes, when plotting multiple maps. Plotting multiple maps now avoids a previous bug where output file names drifted off of the output interval.
- `recon.hdobs.plot_points()` - added option to filter plots by pressure levels

Bug Fixes

- `tracks.TrackDataset.hurricane_days_climo()` - fixed to correctly handle storms crossing multiple basins
- `tracks.TrackDataset.analogs_from_point()` - fixed bug in km to mile conversion
- Fixed a bug with plotting geography order
- Fixed a bug with filtering recon data which sometimes caused the interpolation to fail
- Fixed a bug with reading latitudes for recon missions pre-1992
- Fixed a plotting bug where potential tropical cyclones were improperly labeled as post-tropical TCs
- Improved the method to correctly assign the correct basin to cross-dateline Pacific storms
- Optimized efficiency of reading in realtime JTWC storms from the JTWC ATCF
- Fixed a recon bug where time duplicates led to the interpolation failing
- Fixed a bug with reading IBTrACS data for the North Indian basin (209)
- Fixed a bug with non-default map projections in gridded_stats (207)
- Added NHC 2024 cone of uncertainty radii

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()`.