pyxecm 1.6__py3-none-any.whl → 2.0.1__py3-none-any.whl

pyxecm/customizer/nhc.py

@@ -0,0 +1,1169 @@
+"""NHC stands for National Hurricane Center.
+
+It is a comprehensive data source for tropical storms around the US (Atlantic + Pacific basin).
+
+See: https://www.nhc.noaa.gov
+"""
+
+__author__ = "Dr. Marc Diefenbruch"
+__copyright__ = "Copyright (C) 2024-2025, OpenText"
+__credits__ = ["Kai-Philip Gatzweiler"]
+__maintainer__ = "Dr. Marc Diefenbruch"
+__email__ = "mdiefenb@opentext.com"
+
+import logging
+import multiprocessing
+import os
+import tempfile
+import threading
+import time
+
+from pyxecm.helper import Data
+
+default_logger = logging.getLogger("pyxecm.customizer.nhc")
+
+try:
+    import pandas as pd
+
+    pandas_installed = True
+except ModuleNotFoundError:
+    default_logger.warning(
+        "Module pandas is not installed. Customizer will not support bulk workspace creation.",
+    )
+    pandas_installed = False
+
+try:
+    import matplotlib as mpl
+    from tropycal import rain, tracks
+
+    mpl.use("Agg")
+    tropycal_installed = True
+except ModuleNotFoundError:
+    default_logger.warning(
+        "Module tropycal is not installed. Customizer will not support NHC storm data source.",
+    )
+    tropycal_installed = False
+
+STORM_IMAGE_BASE_PATH = "nhc/images/"
+STORM_DATA_BASE_PATH = "nhc/data/"
+STORM_IMAGE_PLOT_MAX_RETRY = 7
+
+STORM_NUMBERS = {
+    "01": "ONE",
+    "02": "TWO",
+    "03": "THREE",
+    "04": "FOUR",
+    "05": "FIVE",
+    "06": "SIX",
+    "07": "SEVEN",
+    "08": "EIGHT",
+    "09": "NINE",
+    "10": "TEN",
+    "11": "ELEVEN",
+    "12": "TWELVE",
+    "13": "THIRTEEN",
+    "14": "FOURTEEN",
+    "15": "FIFTEEN",
+    "16": "SIXTEEN",
+    "17": "SEVENTEEN",
+    "18": "EIGHTEEN",
+    "19": "NINETEEN",
+    "20": "TWENTY",
+    "21": "TWENTY-ONE",
+    "22": "TWENTY-TWO",
+    "23": "TWENTY-THREE",
+    "24": "TWENTY-FOUR",
+    "25": "TWENTY-FIVE",
+    "26": "TWENTY-SIX",
+    "27": "TWENTY-SEVEN",
+    "28": "TWENTY-EIGHT",
+    "29": "TWENTY-NINE",
+    "30": "THIRTY",
+    "31": "THIRTY-ONE",
+    "32": "THIRTY-TWO",
+    "33": "THIRTY-THREE",
+    "34": "THIRTY-FOUR",
+    "35": "THIRTY-FIVE",
+    "36": "THIRTY-SIX",
+    "37": "THIRTY-SEVEN",
+    "38": "THIRTY-EIGHT",
+    "39": "THIRTY-NINE",
+    "40": "FORTY",
+    "41": "FORTY-ONE",
+    "42": "FORTY-TWO",
+    "43": "FORTY-THREE",
+    "44": "FORTY-FOUR",
+    "45": "FORTY-FIVE",
+    "46": "FORTY-SIX",
+    "47": "FORTY-SEVEN",
+    "48": "FORTY-Eight",
+    "49": "FORTY-Nine",
+    "50": "FIFTY",
+    "51": "FIFTY-ONE",
+    "52": "FIFTY-TWO",
+    "53": "FIFTY-THREE",
+    "54": "FIFTY-FOUR",
+    "55": "FIFTY-FIVE",
+    "56": "FIFTY-SIX",
+    "57": "FIFTY-SEVEN",
+    "58": "FIFTY-EIGHT",
+    "59": "FIFTY-NINE",
+    "60": "SIXTY",
+    "61": "SIXTY-ONE",
+    "62": "SIXTY-TWO",
+    "63": "SIXTY-THREE",
+    "64": "SIXTY-FOUR",
+    "65": "SIXTY-FIVE",
+    "66": "SIXTY-SIX",
+    "67": "SIXTY-SEVEN",
+    "68": "SIXTY-EIGHT",
+    "69": "SIXTY-NINE",
+    "70": "SEVENTY",
+    "71": "SEVENTY-ONE",
+    "72": "SEVENTY-TWO",
+    "73": "SEVENTY-THREE",
+    "74": "SEVENTY-FOUR",
+    "75": "SEVENTY-FIVE",
+    "76": "SEVENTY-SIX",
+    "77": "SEVENTY-SEVEN",
+    "78": "SEVENTY-EIGHT",
+    "79": "SEVENTY-NINE",
+    "80": "EIGHTY",
+    "81": "EIGHTY-ONE",
+    "82": "EIGHTY-TWO",
+    "83": "EIGHTY-THREE",
+    "84": "EIGHTY-FOUR",
+    "85": "EIGHTY-FIVE",
+    "86": "EIGHTY-SIX",
+    "87": "EIGHTY-SEVEN",
+    "88": "EIGHTY-EIGHT",
+    "89": "EIGHTY-NINE",
+    "90": "NINETY",
+    "91": "NINETY-ONE",
+    "92": "NINETY-TWO",
+    "93": "NINETY-THREE",
+    "94": "NINETY-FOUR",
+    "95": "NINETY-FIVE",
+    "96": "NINETY-SIX",
+    "97": "NINETY-SEVEN",
+    "98": "NINETY-EIGHT",
+    "99": "NINETY-NINE",
+}
+
+
+class NHC:
+    """Class NHC is used to retrieve data from National Hurricane Center."""
+
+    logger: logging.Logger = default_logger
+
+    _basin: str | None = None
+    _basin_data = None  # don't use tropycal specific data types here - this clashes if the module is not installed!
+    _rain_data: pd.DataFrame
+    # currently the rain data source seems to only go from ... to 2020
+    _rain_min_year: int | None = None
+    _rain_max_year: int | None = None
+    _session = None
+
+    _download_dir_images: str
+    _download_dir_data: str
+
+    _strom_plot_exclusions = None
+
+    def __init__(
+        self,
+        basin: str = "both",
+        source: str = "hurdat",
+        load_rain_data: bool = True,
+        include_btk: bool = True,
+        storm_plot_exclusions: list | None = None,
+        download_dir_images: str = STORM_IMAGE_BASE_PATH,
+        download_dir_data: str = STORM_DATA_BASE_PATH,
+        logger: logging.Logger = default_logger,
+    ) -> None:
+        """Initialize the NHC object.
+
+        Args:
+            basin (str, optional):
+                The name of the basin. Possible values:
+                - "north_atlantic" (using HURDAT2 and IBTrACS data source)
+                - "east_pacific" (using HURDAT2 and IBTrACS data source)
+                - "both" ("north_atlantic" & "east_pacific" combined)
+                - "west_pacific" (using IBTrACS data source)
+                - "north_indian" (using IBTrACS data source)
+                - "south_indian" (using IBTrACS data source)
+                - "australia" (using IBTrACS* : special case)
+                - "south_pacific" (using IBTrACS)
+                - "south_atlantic" (using IBTrACS)
+                - "all" (suing all IBTrACS)
+            source (str, optional):
+                Data source to read in. Default is HURDAT2.
+                Possible values:
+                "hurdat" - HURDAT2 data source for the North Atlantic and East/Central Pacific basins
+                "ibtracs" - ibtracs data source for regional or global data
+            load_rain_data (bool ,optional):
+                Controls whether or not the rain data is loaded as well.
+                This usees a Pandas data frame.
+            include_btk (bool, optional):
+                If True, the best track data from NHC for the most recent years where it doesn't
+                exist in HURDAT2 will be added into the dataset. Valid for “north_atlantic” and
+                “east_pacific” basins. Default is True.
+            storm_plot_exclusions (list | None, optional):
+                An optional list of storms to exclude from plotting. Defaults to None.
+                Use the storm codes like "AL022018" as values for the exclusion list.
+            download_dir_images (str, optional):
+                Where to store the downloaded storm images. It can be a relative or absolute path.
+                If it is a relative path the default tmp path of the operating system will be used
+                as a prefix.
+            download_dir_data (str, optional):
+                Where to store the downloaded storm data files. It can be a relative or absolute path.
+                If it is a relative path the default tmp path of the operating system will be used
+                as a prefix.
+            logger (logging.Logger, optional):
+                The logging object to use for all log messages. Defaults to default_logger.
+
+        """
+
+        if logger != default_logger:
+            self.logger = logger.getChild("nhc")
+            for logfilter in logger.filters:
+                self.logger.addFilter(logfilter)
+
+        # Store the credentials and parameters in a config dictionary:
+
+        if basin:
+            # Load the storm basin dataset
+            self._basin_data = tracks.TrackDataset(basin=basin, source=source, include_btk=include_btk)
+            self._basin = basin
+
+        # rain data from Weather Prediction Center (WPC) data source
+        if load_rain_data:
+            self._rain_data = rain.RainDataset()
+            if self._rain_data:
+                self._rain_min_year = int(self._rain_data.rain_df["Year"].min())
+                self._rain_max_year = int(self._rain_data.rain_df["Year"].max())
+        else:
+            self._rain_data = None
+
+        self._data = Data(logger=self.logger)
+
+        self._download_dir_images = download_dir_images
+        self._download_dir_data = download_dir_data
+
+        self._strom_plot_exclusions = storm_plot_exclusions
+
+    # end method definition
+
+    def get_data(self) -> Data:
+        """Get the Data object that holds all processed PHT products.
+
+        Returns:
+            Data:
+                Datastructure with all processed NHC storm data.
+
+        """
+
+        return self._data
+
+    # end method definition
+
+    def get_basin_data(self) -> tracks.TrackDataset:
+        """Return the tracks data set.
+
+        Returns:
+            tracks.TrackDataset:
+                The track data set for the basin(s).
+
+        """
+
+        return self._basin_data
+
+    # end method definition
+
+    def get_rain_data(self) -> pd.DataFrame | None:
+        """Get the complete rainfall data.
+
+        Returns:
+            pd.DataFrame:
+                Rain data from Weather Prediction Center (WPC) data source.
+                None in case there's no data.
+
+        """
+
+        if not self._rain_data:
+            self._rain_data = rain.RainDataset()
+
+        return self._rain_data.rain_df
+
+    # end method definition
+
+    def get_season(self, year: int, basin: str = "both", source: str = "hurdat") -> tracks.Season | None:
+        """Get data on a storm season (all stroms in a particular year).
+
+        See: https://tropycal.github.io/tropycal/api/generated/tropycal.tracks.TrackDataset.html
+
+        Args:
+            year (int):
+                The year of the storm, e.g. 2005.
+            basin (str, optional):
+                The basic of the storm, values can be:
+                * "north_atlantic" (using HURDAT2 and IBTrACS data source)
+                * "east_pacific" (using HURDAT2 and IBTrACS data source)
+                * "both" ("north_atlantic" & "east_pacific" combined)
+                * "west_pacific" (using IBTrACS data source)
+                * "north_indian" (using IBTrACS data source)
+                * "south_indian" (using IBTrACS data source)
+                * "australia" (using IBTrACS* : special case)
+                * "south_pacific" (using IBTrACS)
+                * "south_atlantic" (using IBTrACS)
+                * "all" (suing all IBTrACS)
+            source (str, optional):
+                Data source to read in. Default is HURDAT2.
+                Possible values:
+                "hurdat" - HURDAT2 data source for the North Atlantic and East/Central Pacific basins
+                "ibtracs" - ibtracs data source for regional or global data
+
+        Returns:
+            tracks.Season:
+                Season data object or None in case of an error.
+
+        """
+
+        # Load the storm basin dataset
+        if not self._basin_data:
+            self._basin_data = tracks.TrackDataset(basin=basin, source=source)
+
+        # Get storm data by name and year
+        try:
+            season_data = self._basin_data.get_season(year=year)
+        except ValueError as e:
+            self.logger.info(
+                "Cannot find season data for year -> %s!; error -> %s",
+                str(year),
+                str(e),
+            )
+            return None
+
+        return season_data
+
+    # end method definition
+
+    def get_storm(
+        self,
+        name: str | None = None,
+        year: int | None = None,
+        storm_id: str | None = None,
+        basin: str = "both",
+    ) -> tracks.Storm:
+        """Get data on a particular storm.
+
+        Args:
+            name (str):
+                The nickname of the storm, like 'Katrina'.
+            year (int):
+                The year of the storm, e.g. 2005.
+            storm_id (str):
+                Alternatively to name and year you can provide the id of the storm
+            basin (str):
+                The basic of the storm, values can be:
+                * "north_atlantic" (using HURDAT2 and IBTrACS data source)
+                * "east_pacific" (using HURDAT2 and IBTrACS data source)
+                * "both" ("north_atlantic" & "east_pacific" combined)
+                * "west_pacific" (using IBTrACS data source)
+                * "north_indian" (using IBTrACS data source)
+                * "south_indian" (using IBTrACS data source)
+                * "australia" (using IBTrACS* : special case)
+                * "south_pacific" (using IBTrACS)
+                * "south_atlantic" (using IBTrACS)
+                * "all" (suing all IBTrACS)
+
+        Returns:
+            dict:
+                The storm data or None in case of an error.
+
+        """
+
+        # Load the storm basin dataset
+        if not self._basin_data:
+            self._basin_data = tracks.TrackDataset(basin=basin)
+
+        # Get storm data by name and year
+        try:
+            storm_data = (
+                self._basin_data.get_storm(storm=storm_id)
+                if storm_id
+                else self._basin_data.get_storm(storm=(name, year))
+            )
+        except (ValueError, KeyError) as e:
+            self.logger.info(
+                "Cannot find storm data for storm -> '%s'%s; error -> %s",
+                name if name else storm_id,
+                " and year -> {}".format(str(year)) if year else "",
+                str(e),
+            )
+            return None
+
+        return storm_data
+
+    # end method definition
+
+    def get_storm_rainfall(self, storm_data: tracks.Storm) -> pd.DataFrame:
+        """Get the rainfall data of a given storm.
+
+        Args:
+            storm_data (tracks.Storm): Storm data. This needs to be retrieved
+                                       with get_storm() before.
+
+        Returns:
+            pd.DataFrame: Pandas data frame with the storm rain data.
+
+        """
+
+        if not self._rain_data:
+            self._rain_data = rain.RainDataset()
+
+        try:
+            storm_rain = self._rain_data.get_storm_rainfall(storm_data)
+        except RuntimeError as re:
+            self.logger.info(
+                "Cannot find rain data for storm -> '%s' in year -> %s; message -> %s",
+                storm_data["name"],
+                str(storm_data["season"]),
+                str(re),
+            )
+            return None
+
+        return storm_rain
+
+    # end method definition
+
+    def get_storm_image_path(self) -> str:
+        """Get the path to the filesystem directory where storm plot images should be saved.
+
+        Returns:
+            str:
+                The path to the filesystem directory where storm plot images should be saved.
+
+        """
+
+        return os.path.join(tempfile.gettempdir(), self._download_dir_images)
+
+    # end method definition
+
+    def get_storm_data_path(self) -> str:
+        """Get the path to the filesystem directory where storm data should be saved.
+
+        Returns:
+            str:
+                The path to the filesystem directory where storm data should be saved.
+
+        """
+
+        return os.path.join(tempfile.gettempdir(), self._download_dir_data)
+
+    # end method definition
+
+    def get_storm_file_name(self, storm_id: str, file_type: str, suffix: str = "") -> str:
+        """Determine the save path and filename of the plot image or data files of a given storm.
+
+        Args:
+            storm_id (str):
+                The ID of the storm.
+            file_type (str):
+                The file type. Can be "svg", "png", "json", ...
+            suffix (str, optional):
+                For special image files (like rain) we want to add a special name suffix.
+
+        """
+
+        file_name = storm_id
+        # Add a suffix for special cases:
+        if suffix:
+            file_name += suffix
+        file_name += "." + file_type
+
+        return file_name
+
+    # end method definition
+
+    def save_storm_track_image(
+        self,
+        storm_data: tracks.Storm,
+        image_path: str,
+        domain: str | dict = "dynamic",
+    ) -> tuple[bool, str]:
+        """Save an image (map) file of a given storm track.
+
+        Args:
+            storm_data (tracks.Storm):
+                The storm data.
+            image_path (str):
+                Where to store the image file.  If the directory
+                does not exist it is created.
+            domain (str | dict, optional):
+                Zoom area in geo coordinates. Defaults to "dynamic".
+
+        Returns:
+            bool:
+                True = success
+                False = error (at least issues
+            str:
+                Error / warning message.
+
+        """
+
+        retries = 0
+
+        # Loop for retries:
+        while True:
+            try:
+                storm_data.plot(
+                    domain=domain,
+                    save_path=image_path,
+                )
+            except Exception as plot_error:
+                if retries > STORM_IMAGE_PLOT_MAX_RETRY:
+                    return (False, str(plot_error))
+                retries += 1
+            else:
+                return (True, "Success" if retries == 0 else "Success after {} retries".format(retries))
+
+    # end method definition
+
+    def save_storm_track_data(
+        self,
+        storm_data: tracks.Storm,
+        data_path: str,
+        save_general_storm_attributes: bool = False,
+    ) -> None:
+        """Save a data file of a given storm track (this is a data series over time).
+
+        Args:
+            storm_data (tracks.Storm):
+                The storm object (retreived by get_storm() before).
+            data_path (str):
+                Where to store the data file.
+            save_general_storm_attributes (bool, optional):
+                Do we want to have (repeatedly) the
+                general storm attributes in the data set?
+
+        """
+
+        data = Data(
+            storm_data.to_dataframe(attrs_as_columns=save_general_storm_attributes),
+            logger=self.logger,
+        )
+        if not data:
+            return
+        if ("basin" not in data.get_columns() or []) and ("wmo_basin" in data.get_columns() or []):
+            data.rename_column(old_column_name="wmo_basin", new_column_name="basin")
+        data.drop_columns(
+            column_names=["extra_obs", "special", "operational_id", "wmo_basin"],
+        )
+        data.rename_column(old_column_name="lat", new_column_name="latitude")
+        data.rename_column(old_column_name="lon", new_column_name="longitude")
+        if data_path.endswith("json"):
+            result = data.save_json_data(json_path=data_path)
+        elif data_path.endswith("xlsx"):
+            result = data.save_excel_data(excel_path=data_path)
+        else:
+            self.logger.error("Illegal file type for storm track data!")
+            return
+
+        # We try to be nice to memory consumption:
+        del data
+
+        if result:
+            self.logger.info(
+                "Successfully saved track data of storm -> '%s' (%s) to file -> '%s'",
+                storm_data["name"],
+                storm_data["id"],
+                data_path,
+            )
+        else:
+            self.logger.error(
+                "Failed to save track data of storm -> '%s' (%s) to file -> '%s'",
+                storm_data["name"],
+                storm_data["id"],
+                data_path,
+            )
+
+    # end method definition
+
+    def save_storm_rain_image(
+        self,
+        storm_data: tracks.Storm,
+        image_path: str,
+        domain: str | dict = "dynamic",
+    ) -> tuple[bool, str]:
+        """Save an image file for a given storm rainfall.
+
+        Args:
+            storm_data (tracks.Storm):
+                The storm object (retreived by get_storm() before).
+            image_path (str):
+                Where to store the image file. If the directory
+                does not exist it is created.
+            domain (str | dict, optional):
+                Zoom area in geo coordinates. Defaults to "dynamic".
+
+        Returns:
+            bool:
+                True = success
+                False = error (at least issues
+            str:
+                Error / warning message.
+
+        """
+
+        retries = 0
+
+        # Loop for retries:
+        while True:
+            try:
+                # Interpolate to grid
+                grid = self._rain_data.interpolate_to_grid(storm_data, return_xarray=True)
+                levels = [1, 2, 4, 8, 12, 16, 20, 30, 40, 50, 60]
+                self._rain_data.plot_rain_grid(
+                    storm_data,
+                    grid,
+                    levels,
+                    domain=domain,
+                    save_path=image_path,
+                )
+            except Exception as plot_error:
+                if retries > STORM_IMAGE_PLOT_MAX_RETRY:
+                    return (False, str(plot_error))
+                retries += 1
+            else:
+                return (True, "Success" if retries == 0 else "Success after {} retries".format(retries))
+
+    # end method definition
+
+    def save_storm_rain_data(
+        self,
+        storm_data: tracks.Storm,
+        data_path: str,
+    ) -> None:
+        """Save a data file for a given storm rainfall.
+
+        Args:
+            storm_data (tracks.Storm):
+                The storm object (retreived by get_storm() before).
+            data_path (str):
+                Where to store the data file.
+
+        """
+
+        data = Data(self._rain_data.get_storm_rainfall(storm_data), logger=self.logger)
+        if not data:
+            return
+        if data_path.endswith("json"):
+            result = data.save_json_data(json_path=data_path)
+        elif data_path.endswith("xlsx"):
+            result = data.save_excel_data(excel_path=data_path)
+        else:
+            self.logger.error("Illegal file type!")
+            return
+
+        if result:
+            self.logger.info(
+                "Successfully saved rainfall data of storm -> '%s' (%s) to file -> '%s'",
+                storm_data["name"],
+                storm_data["id"],
+                data_path,
+            )
+        else:
+            self.logger.error(
+                "Failed to save rainfall data of storm -> '%s' (%s) to file -> '%s'",
+                storm_data["name"],
+                storm_data["id"],
+                data_path,
+            )
+
+    # end method definition
+
+    def load_storms(
+        self,
+        year_start: int,
+        year_end: int,
+        save_track_images: list | None = None,
+        save_track_data: list | None = None,
+        save_rain_images: list | None = None,
+        save_rain_data: list | None = None,
+        skip_existing_files: bool = True,
+        load_async: bool = True,
+        async_processes: int = 8,
+    ) -> bool:
+        """Load storm into a data frame and save files for storm tracks and rainfall (data and image files).
+
+        Args:
+            year_start (int):
+                The start year (season).
+            year_end (int):
+                The end year (season).
+            save_track_images (list, optional):
+                A list of image types, e.g. ["svg", "png"], to save the storm track.
+            save_track_data (list, optional):
+                A list of data types, e.g. ["json", "xlsx"], to save the storm track.
+            save_rain_images (list, optional):
+                A list of image types, e.g. ["svg", "png"], to save the storm rainfall.
+            save_rain_data (list, optional):
+                A list of data types, e.g. ["json", "xlsx"], to save the storm rainfall.
+            skip_existing_files (bool, optional):
+                Skip files that have been saved before.
+            load_async (bool, optional):
+                Whether or not we want the plot method to run asynchronous. Default
+                is True. In case of issues or deadlocks you may want to set it to False.
+            async_processes (int, optional):
+                Number of async processes to generate the plot files.
+                Default is 5.
+
+        """
+
+        data = self.get_data()
+        image_dir = self.get_storm_image_path()
+        # Create folder if it does not exist
+        if not os.path.exists(image_dir):
+            os.makedirs(image_dir)
+        data_dir = self.get_storm_data_path()
+        # Create folder if it does not exist
+        if not os.path.exists(data_dir):
+            os.makedirs(data_dir)
+
+        self.logger.info(
+            "Loading data from National Hurricane Center from year -> %s to year -> %s for basin -> '%s'",
+            year_start,
+            year_end,
+            self._basin,
+        )
+
+        if save_track_images:
+            self.logger.info("Generate track plot files -> %s", str(save_track_images))
+        if save_track_data:
+            self.logger.info("Generate track data files -> %s", str(save_track_data))
+        if save_rain_images:
+            self.logger.info("Generate rain plot files -> %s", str(save_rain_images))
+        if save_rain_data:
+            self.logger.info("Generate rain data files -> %s", str(save_rain_data))
+        self.logger.info("Existing plot files will %sbe reused.", "" if skip_existing_files else "not ")
+
+        if load_async:
+            self.logger.info("Initiate plot storm worker pool of size -> %d (asynchronous)...", async_processes)
+        else:
+            self.logger.info("Initiate plot storm worker pool of size -> %d (synchronous)...", async_processes)
+
+        # Create the pool with a given number of processes.
+        # maxtasksperchild=1 makes sure that the processes really
+        # terminate after the called method completes. We want
+        # to do this to really free up the memory as the plot()
+        # methods tend to "memory leak" and pods will be evicted
+        # over time.
+        pool = multiprocessing.Pool(processes=async_processes, maxtasksperchild=1)
+        # Collect the results of the processes in this list:
+        results = []
+
+        if load_async:
+            done_event = threading.Event()
+
+            # Start the result collector thread before submitting plot tasks.
+            # This thread is used for printing success or failure messages.
+            # We don't want to do this in the actual plot files as this
+            # causes issues (deadlock) if printing log messages in the process
+            # worker methods.
+            collector_thread = threading.Thread(
+                name="NHC Result Collector",
+                target=self.result_collector,
+                args=(results, done_event),
+            )
+            self.logger.info("Start collector thread for logging plot process results...")
+            collector_thread.start()
+
+        for year in range(year_start, year_end + 1):
+            season = self.get_season(year=year)
+            data.append(season.to_dataframe())
+            for storm_id, storm_value in season.dict.items():
+                storm_name = storm_value["name"]
+                storm_operational_id = storm_value.get("operational_id", storm_id)
+                if storm_operational_id and storm_operational_id != storm_id:
+                    self.logger.info(
+                        "Storm '%s' has an operational ID -> '%s' which is different from the storm ID -> '%s",
+                        storm_name,
+                        storm_operational_id,
+                        storm_id,
+                    )
+                storm_data = self.get_storm(storm_id=storm_id)
+                if not storm_data:
+                    self.logger.debug("Cannot get storm data form storm -> '%s' (%s)", storm_name, storm_id)
+                    return False
+                storm_dict = storm_data.to_dict()
+                if storm_name == "UNNAMED":
+                    # Tropycal (based on HURDAT) has unnamed storms with name "UNNAMED"
+                    # while most other data sources have them as English number names
+                    # like "Two" or "Eight". For this reason we change the name of unnamed
+                    # storms here as well and write it back into the data frame and
+                    # the storm data structure:
+                    storm_name = STORM_NUMBERS[storm_id[2:4]]
+                    storm_data["name"] = storm_name
+                    data.set_value(
+                        column="name",
+                        value=storm_name,
+                        condition=(data["id"] == storm_id),  # this is a boolean pd.Series
+                    )
+                self.logger.info(
+                    "Processing storm -> '%s' (%s) in year -> %s...",
+                    storm_name,
+                    storm_id,
+                    year,
+                )
+                # The category ("type") of the storm is a time series as the storm has
+                # a different category over time. We want the peak category:
+                type_series = storm_dict.get("type", None)
+                if type_series:
+                    peak_index = storm_data.dict["vmax"].index(
+                        max(storm_data.dict["vmax"]),
+                    )
+                    storm_type = type_series[peak_index]
+
+                    # Add storm type as this is not included in season.to_dataframe():
+                    if "type" not in data.get_columns():
+                        data.add_column(new_column="type", data_type="string")
+                    data.set_value(
+                        column="type",
+                        value=storm_type,
+                        condition=(data["id"] == storm_id),  # this is a boolean pd.Series
+                    )
+
+                # Add year as this is not included in season.to_dataframe():
+                if "year" not in data.get_columns():
+                    data.add_column(new_column="year", data_type="Int64")
+                data.set_value(
+                    column="year",
+                    value=year,
+                    condition=(data["id"] == storm_id),
+                )
+                # Add basin as this is not included in season.to_dataframe():
+                if "basin" not in data.get_columns():
+                    data.add_column(new_column="basin", data_type="string")
+                data.set_value(
+                    column="basin",
+                    value=storm_data["basin"],
+                    condition=(data["id"] == storm_id),  # boolean pd.Series
+                )
+                # Add counter (number of storm in season) as this is not included in season.to_dataframe():
+                if "counter" not in data.get_columns():
+                    data.add_column(new_column="counter", data_type="string")
+                data.set_value(
+                    column="counter",
+                    value=storm_data["id"][2:4],
+                    condition=(data["id"] == storm_id),  # boolean pd.Series
+                )
+                # Add counter (number of storm in season) as this is not included in season.to_dataframe():
+                if "source_info" not in data.get_columns():
+                    data.add_column(new_column="source_info", data_type="string")
+                data.set_value(
+                    column="source_info",
+                    value=storm_data["source_info"],
+                    condition=(data["id"] == storm_id),  # boolean pd.Series
+                )
+
+                if not self._strom_plot_exclusions or storm_id not in self._strom_plot_exclusions:
+                    # Create the image files of the storm track:
+                    for image_type in save_track_images or []:
+                        image_file = self.get_storm_file_name(storm_id=storm_data["id"], file_type=image_type)
+                        data.set_value(
+                            column="image_file_" + image_type,
+                            value=image_file,
+                            condition=(data["id"] == storm_id),  # boolean pd.Series
+                        )
+                        image_path = os.path.join(image_dir, image_file)
+                        if skip_existing_files and os.path.exists(image_path):
+                            self.logger.info(
+                                "Storm track image file -> '%s' has been saved before - skipping...",
+                                image_path,
+                            )
+                            continue
+                        self.logger.info(
+                            "Plot storm track image file -> '%s'%s...",
+                            image_path,
+                            " (replace existing file)" if os.path.exists(image_path) else "",
+                        )
+                        success_message = (
+                            "Successfully saved track image for storm -> '{}' ({}) to file -> '{}'".format(
+                                storm_name,
+                                storm_data["id"],
+                                image_path,
+                            )
+                        )
+                        failure_message = (
+                            "Issues while plotting track image for storm -> '{}' ({}) to file -> '{}'".format(
+                                storm_name,
+                                storm_data["id"],
+                                image_path,
+                            )
+                        )
+                        if load_async:
+                            result = pool.apply_async(self.save_storm_track_image, args=(storm_data, image_path))
+                            results.append(
+                                (
+                                    result,
+                                    success_message,
+                                    failure_message,
+                                    "image_file_" + image_type,
+                                    storm_id,
+                                    image_path,
+                                ),
+                            )
+                        else:
+                            result = pool.apply(self.save_storm_track_image, args=(storm_data, image_path))
+                            if result:
+                                self.logger.info(success_message)
+                            else:
+                                self.logger.warning(failure_message)
+                                continue
+                    # end for image_type in save_track_images or []
+                # end if not self._strom_plot_exclusions or storm_key not in self._strom_plot_exclusions
+
+                # Create the data files of the storm track:
+                for data_type in save_track_data or []:
+                    data_file = self.get_storm_file_name(storm_id=storm_data["id"], file_type=data_type)
+                    data.set_value(
+                        column="data_file_" + data_type,
+                        value=data_file,
+                        condition=(data["id"] == storm_id),  # boolean pd.Series
+                    )
+                    data_path = os.path.join(data_dir, data_file)
+                    if skip_existing_files and os.path.exists(data_path):
+                        self.logger.info(
+                            "Storm track data file -> '%s' has been saved before - skipping...",
+                            data_path,
+                        )
+                        continue
+                    self.save_storm_track_data(
+                        storm_data=storm_data,
+                        data_path=data_path,
+                    )
+
+                # Sadly, rain data is only available up to year 2020.
+                if year < self._rain_min_year or year > self._rain_max_year:
+                    self.logger.debug(
+                        "There's no rain data for year -> %s. Skipping rain plots for this year...",
+                        year,
+                    )
+                    continue
+
+                storm_rain_data = self.get_storm_rainfall(storm_data=storm_data)
+                if storm_rain_data is None:
+                    self.logger.debug(
+                        "There's no rain data for storm -> '%s' in year -> %s. Skipping rain plots for this storm...",
+                        storm_name,
+                        year,
+                    )
+                    continue
+
+                if not self._strom_plot_exclusions or storm_id not in self._strom_plot_exclusions:
+                    # Create the images of the storm rain:
+                    for image_type in save_rain_images or []:
+                        image_file_rain = self.get_storm_file_name(
+                            storm_id=storm_data["id"],
+                            file_type=image_type,
+                            suffix="-rainfall",
+                        )
+                        data.set_value(
+                            column="image_file_rain_" + image_type,
+                            value=image_file_rain,
+                            condition=(data["id"] == storm_id),  # boolean pd.Series
+                        )
+                        image_path_rain = os.path.join(image_dir, image_file_rain)
+                        if skip_existing_files and os.path.exists(image_path_rain):
+                            self.logger.info(
+                                "Storm rain image file -> '%s' has been saved before - skipping...",
+                                image_path_rain,
+                            )
+                            continue
+                        self.logger.info(
+                            "Plot storm rain image file -> '%s'...",
+                            image_path_rain,
+                        )
+                        success_message = "Successfully saved rain image for storm -> '{}' ({}) to file -> '{}'".format(
+                            storm_data["name"],
+                            storm_data["id"],
+                            image_path_rain,
+                        )
+                        failure_message = (
+                            "Issues while plotting rain image for storm -> '{}' ({}) to file -> '{}'".format(
+                                storm_data["name"],
+                                storm_data["id"],
+                                image_path_rain,
+                            )
+                        )
+                        if load_async:
+                            result = pool.apply_async(self.save_storm_rain_image, args=(storm_data, image_path_rain))
+                            results.append(
+                                (
+                                    result,
+                                    success_message,
+                                    failure_message,
+                                    "image_file_rain_" + image_type,
+                                    storm_id,
+                                    image_path_rain,
+                                ),
+                            )
+                        else:
+                            result = pool.apply(self.save_storm_rain_image, args=(storm_data, image_path_rain))
+                            if result:
+                                self.logger.info(success_message)
+                            else:
+                                self.logger.warning(failure_message)
+                                continue
+                    # end for image_type in save_rain_images or []
+                # end if not self._strom_plot_exclusions or storm_key not in self._strom_plot_exclusions
+
+                # Create the data files of the storm rain:
+                for data_type in save_rain_data or []:
+                    data_file_rain = self.get_storm_file_name(
+                        storm_id=storm_data["id"],
+                        file_type=data_type,
+                        suffix="-rainfall",
+                    )
+                    data.set_value(
+                        column="data_file_rain_" + data_type,
+                        value=data_file_rain,
+                        condition=(data["id"] == storm_id),  # boolean pd.Series
+                    )
+                    data_path_rain = os.path.join(data_dir, data_file_rain)
+                    if skip_existing_files and os.path.exists(data_path_rain):
+                        self.logger.info(
+                            "Storm rain data file -> '%s' has been saved before - skipping...",
+                            data_path_rain,
+                        )
+                        continue
+                    self.save_storm_rain_data(
+                        storm_data=storm_data,
+                        data_path=data_path_rain,
+                    )
+                # end for data_type in save_rain_data
+            # end for storm_key, storm_value in season.dict.items()
+        # end for year in range(year_start, year_end + 1)
+
+        # Add a column with the image directory and the data directory
+        # (value is the same for all rows that's why we do it outside the loop):
+        data.set_value(
+            column="image_dir",
+            value=image_dir,
+        )
+        data.set_value(
+            column="data_dir",
+            value=data_dir,
+        )
+
+        self.logger.info("Close plot storm worker pool...")
+        pool.close()  # Close the pool to new tasks
+        self.logger.info("Plot storm worker pool is closed.")
+
+        if load_async:
+            self.logger.info("Send 'done' event to collector thread...")
+            done_event.set()
+
+            # Wait for the collector thread to finish (this will be after pool join)
+            self.logger.info("Waiting for plot collector thread to finish...")
+            collector_thread.join()
+            self.logger.info("Plot collector thread is finished.")
+
+        # Run the termination and cleanup in a daemon thread to not block the code if
+        # a worker process refuses to terminate:
+        daemon_thread = threading.Thread(
+            name="NHC Termination & Cleanup",
+            target=self.terminate_and_cleanup,
+            args=(pool,),
+        )
+        daemon_thread.daemon = True  # Set as a daemon thread, so it won't block program exit
+        daemon_thread.start()
+
+        return True
+
+    # end method definition
+
+    def result_collector(self, results: list, done_event: threading.Event) -> None:
+        """Collect results from async processes and logs them.
+
+        Args:
+            results (list):
+                A list of tuples containing task metadata, async results, and pre-baked log messages.
+            done_event (threading.Event):
+                Event signaling that no more tasks will be submitted.
+
+        """
+
+        self.logger.info("Collector thread for plot results started...")
+
+        # Keep running while results remain or not signalled 'done':
+        while not done_event.is_set() or results:
+            # Iterate over a copy of the list of tuples:
+            for result in results[:]:
+                # Unpack the result tuple:
+                async_result, success_message, failure_message, column_name, storm_id, image_file = result
+                # Check if the process has finished:
+                if async_result.ready():
+                    try:
+                        # Retrieve result (ensuring no exception):
+                        success, message = async_result.get()
+                        if success:
+                            self.logger.info(
+                                "%s. %s",
+                                success_message,
+                                "Plot result: " + message if message else "",
+                            )
+                        elif os.path.exists(image_file):
+                            self.logger.warning(
+                                "%s. %s",
+                                failure_message,
+                                "Plot result: " + message if message else "",
+                            )
+                        else:
+                            self.logger.warning("%s. %s", failure_message, "Plot result: " + message if message else "")
+                            self.get_data().set_value(
+                                column=column_name,
+                                value="",  # set to empty to make sure the bulk loader are not trying to find the non-existing file
+                                condition=(self.get_data()["id"] == storm_id),  # boolean pd.Series
+                            )
+                    except Exception:
+                        self.logger.warning(failure_message)
+                    # Remove logged result:
+                    results.remove(result)
+            # Prevent excessive CPU usage:
+            time.sleep(0.5)
+
+        self.logger.info("Collector thread for plot results got 'done' event and no further results to process.")
+
+    # end method definition
+
+    def terminate_and_cleanup(self, pool: multiprocessing.pool.Pool) -> None:
+        """Terminate and clean up the worker pool in a daemon thread.
+
+        Args:
+            pool (multiprocessing.pool.Pool):
+                The pool of worker processes to terminate.
+
+        """
+
+        for worker in pool._pool or []:  # noqa: SLF001
+            if not worker.is_alive() and worker.exitcode is None:
+                self.logger.warning("Worker with PID -> %s is defunct (zombie state).", worker.pid)
+            elif worker.is_alive():
+                self.logger.warning("Worker with PID -> %s is still alive.", worker.pid)
+            else:
+                self.logger.info(
+                    "Worker with PID -> %s finished with exit code -> %s.",
+                    worker.pid,
+                    str(worker.exitcode),
+                )
+
+        self.logger.info("Terminating the worker pool due to potentially hanging tasks...")
+        pool.terminate()  # Terminate the pool to stop all workers
+        self.logger.info("Plot storm worker pool terminated.")
+
+        self.logger.info("Joining plot storm worker pool...")
+        pool.join()  # Timeout after 10 seconds
+        self.logger.info("Plot storm worker pool is finished (joined).")
+
+    # end method definition