PyThea 0.12.0__tar.gz → 0.14.0__tar.gz

{pythea-0.12.0 → pythea-0.14.0}/CHANGELOG.md

@@ -1,3 +1,27 @@
+# v0.14.0 (03-Oct-2024)
+
+## Features
+ - Adds imaging data from Solar Orbiter EUI and METIS.
+ - Implements offline fits file loading from local database.
+
+## Minor Changes
+ - Simplifies the configuration of the database directory.
+ - Improves Parker Spiral visualization.
+
+# v0.13.0 (14-Jul-2024)
+
+## Features
+ - Adds imaging data from PSP/WISPR.
+ - Implements new feature of Parker spiral and HEK events visualization on the images.
+ - Adds a method to get directly the geometrical model from model_fittings.
+ - Adds tests for extensions, WISPR imaging.
+ - Adds and improves docstrings in utilities, modules, and geometrical models.
+ - Adds GCS and kinematic plots in documentation
+ - Adds function reference in the documentation
+
+## Minor Changes
+ - Changes some optional inputs for get_hek_flare, make_figure, plot_bodies, and plot_solar_reference_lines to be better utilised.
+
 # v0.12.0 (09-Jun-2024)
 
 ## Features

{pythea-0.12.0 → pythea-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyThea
-Version: 0.12.0
+Version: 0.14.0
 Summary: PyThea: A software package to reconstruct the 3D structure of CMEs and shock waves
 Home-page: https://github.com/AthKouloumvakos/PyThea
 Author: Athanasios Kouloumvakos
@@ -20,15 +20,16 @@ Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.8, <3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: numpy
+Requires-Dist: numpy==1.26.4
 Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: aiapy
-Requires-Dist: astropy
+Requires-Dist: astropy==6.0.0
 Requires-Dist: astroquery
 Requires-Dist: jplephem
 Requires-Dist: numexpr
 Requires-Dist: sunpy==5.1.2
+Requires-Dist: sunpy_soar
 Requires-Dist: parfive==2.1.0
 Requires-Dist: pooch
 Requires-Dist: matplotlib

{pythea-0.12.0 → pythea-0.14.0}/PyThea/PyThea_app.py

@@ -39,6 +39,7 @@ from PyThea.modules import (date_and_event_selection, figure_streamlit,
 from PyThea.sunpy_dev.map.maputils import get_closest, maps_clims
 from PyThea.utils import (download_fits, load_fits, model_fittings,
                           plot_fitting_model, single_imager_maps_process)
+from PyThea.utils_database import get_fits_filenames_from_database
 from PyThea.version import version
 
 
@@ -82,7 +83,9 @@ def footer_text():
                 """)
     st.info('''
             More imaging data have been added:
-            - SDO/AIA images from 211A channel have been added.
+            - SDO/AIA images from 211A channel.
+            - PSP/WISPR inner and outer telescope images.
+            - SolO/EUI and METIS images.
             ''', icon='ℹ️')
     st.warning('''
            **NOTE: From PyThea >0.8.1 the JSON fitting files will be slightly different from the old ones.**
@@ -197,7 +200,7 @@ def run():
                                                           key='imaging_time_range')
         select_timerange_form.form_submit_button(label='Submit',
                                                  on_click=delete_from_state,
-                                                 kwargs={'vars': ['map', 'map_', 'imagers_list_']})
+                                                 kwargs={'vars': ['map', 'map_', 'imagers_list_', 'hek_responses']})
 
     with st.sidebar.expander('Processing Options'):
         procoption_container = st.container()
@@ -222,32 +225,59 @@ def run():
         plotviewopt_container = st.container()
         plotviewopt_container.checkbox('Clip plot on image limits', value=True, key='clip_model')
         plt_supp_imagers = plotviewopt_container.checkbox('Supplementary Imaging', value=False)
-        plotviewopt_container.checkbox('View Bodies or s/c', key='star_field')
-        if st.session_state.star_field:
-            plotviewopt_container.multiselect('Select Bodies', options=selected_bodies.bodies_dict.keys(),
-                                              default=['Mercury', 'Venus', 'Jupiter'],
-                                              key='bodies_list')
-        plotviewopt_container.checkbox('View Limb and Meridians', key='plot_solar_reference_lines_')
-        if st.session_state.plot_solar_reference_lines_:
-            markdown = '''
-                **Limb**: plots the solar limb as observed  # noqa
-                for the selected observers.  # noqa
-                **Central Meridian**: plots the central meridian  # noqa
-                observed for the selected observers.  # noqa
-                **CR Meridan+Equator**: plots the primary meridian  # noqa
-                and equator of Carrington coordinate system.  # noqa
-                '''.strip()
-            plotviewopt_container.selectbox('Select plot option',
-                                            options=['Limb from Obs.', 'Central Meridian from Obs.', 'Carr. Prime Meridian+Solar Equator',
-                                                     'Stonyhurst Grid', 'Carrington Grid'],
-                                            help=markdown,
-                                            key='plot_solar_reference_lines_mode')
-            disabled = False if st.session_state.plot_solar_reference_lines_mode in ['Limb from Obs.', 'Central Meridian from Obs.'] else True
-            plotviewopt_container.multiselect('Select Bodies',
-                                              label_visibility='collapsed',
-                                              options=selected_bodies.bodies_dict.keys(),
-                                              default=['Earth'], disabled=disabled,
-                                              key='plot_solar_reference_lines_bodies_list')
+
+    #############################################################
+    # Magnetic Connectivity
+    st.sidebar.markdown('## Overlays')
+    with st.sidebar.expander('Bodies or s/c Location'):
+        bodies_container = st.container()
+        bodies_container.checkbox('View Bodies or s/c', key='star_field')
+        bodies_container.multiselect('Select Bodies', options=selected_bodies.bodies_dict.keys(),
+                                     default=['Mercury', 'Venus', 'Jupiter'],
+                                     key='bodies_list',
+                                     disabled=not st.session_state.star_field)
+    with st.sidebar.expander('Limb and Meridians'):
+        limb_meridians_container = st.container()
+        limb_meridians_container.checkbox('View Limb and Meridians', key='plot_solar_reference_lines_')
+        markdown = '''
+            **Limb**: plots the solar limb as observed
+            for the selected observers.
+            **Central Meridian**: plots the central meridian
+            observed for the selected observers.
+            **CR Meridan+Equator**: plots the primary meridian
+            and equator of Carrington coordinate system.
+            '''.strip()
+        limb_meridians_container.selectbox('Select plot option',
+                                           options=['Limb from Obs.', 'Central Meridian from Obs.', 'Carr. Prime Meridian+Solar Equator',
+                                                    'Stonyhurst Grid', 'Carrington Grid'],
+                                           help=markdown,
+                                           key='plot_solar_reference_lines_mode',
+                                           disabled=not st.session_state.plot_solar_reference_lines_)
+        disabled = False if (st.session_state.plot_solar_reference_lines_) and \
+            (st.session_state.plot_solar_reference_lines_mode in ['Limb from Obs.', 'Central Meridian from Obs.']) else True
+        limb_meridians_container.multiselect('Select Bodies',
+                                             label_visibility='collapsed',
+                                             options=selected_bodies.bodies_dict.keys(),
+                                             default=['Earth'], disabled=disabled,
+                                             key='plot_solar_reference_lines_bodies_list')
+    with st.sidebar.expander('Magnetic Connectivity'):
+        connectivity_container = st.container()
+        connectivity_container.checkbox('Plot Parker spirals', key='plot_parker_spirals')
+        connectivity_container.multiselect('Select bodies/spacecraft', options=selected_bodies.bodies_dict.keys(),
+                                           default=['Earth'], key='mag_bodies_list',
+                                           disabled=not st.session_state.plot_parker_spirals)
+        st.session_state.sw_speed_select = {}
+        for body in st.session_state.mag_bodies_list:
+            connectivity_container.number_input(f'{body} solar wind speed', min_value=200, max_value=800, value=350, step=50,
+                                                key=f'sw_speed_select_{body}',
+                                                disabled=not st.session_state.plot_parker_spirals)
+            st.session_state.sw_speed_select[body] = st.session_state[f'sw_speed_select_{body}'] * (u.km/u.second)
+    with st.sidebar.expander('HEK feature/events'):
+        hek_container = st.container()
+        hek_container.checkbox('Plot HEK feature/events', key='plot_hek', on_change=delete_from_state,
+                               kwargs={'vars': ['hek_responses', ]})
+        hek_container.multiselect('Select HEK feature/events', options=['Active Regions', 'Coronal Holes', 'Flares'],
+                                  default=['Flares'], key='hek_list', disabled=not st.session_state.plot_hek)
 
     #############################################################
     # Download and Process the Images
@@ -267,7 +297,15 @@ def run():
             if imager not in st.session_state.map_:
                 timerange = a.Time(st.session_state.date_process + datetime.timedelta(hours=imaging_time_range[0]),
                                    st.session_state.date_process + datetime.timedelta(hours=imaging_time_range[1]))
-                downloaded_files = download_fits(timerange, imager)
+
+                if st.session_state.offline_mode is False:
+                    downloaded_files = download_fits(timerange, imager)
+                elif st.session_state.offline_mode is True:
+                    progress_bar.desc = f'Load {imager} images from local database.'
+                    event_id = st.session_state.event_selected.replace('-', '').replace(':', '').replace('|', 'D').replace('.', 'p') \
+                        + 'M' + st.session_state.geometrical_model
+                    downloaded_files = get_fits_filenames_from_database(event_id, timerange, imager)
+
                 st.session_state.map_[imager] = load_fits(downloaded_files)
                 st.session_state.map_[imager] = single_imager_maps_process(st.session_state.map_[imager],
                                                                            **selected_imagers.imager_dict[imager]['process'],
@@ -299,13 +337,14 @@ def run():
     col1, col2 = st.columns((1, 3))
     imager_select = col1.selectbox('Select an imager',
                                    options=st.session_state.imagers_list_,
-                                   on_change=delete_from_state, kwargs={'vars': ['clim', 'clim_manual_low', 'clim_manual_high']})
+                                   on_change=delete_from_state, kwargs={'vars': ['clim', 'clim_manual_low', 'clim_manual_high', 'hek_responses']})
 
     maps_date = [getattr(maps, 'date_average', None) or getattr(maps, 'date', None) for maps in st.session_state.map[imager_select]]
     if len(maps_date) > 1:
         running_map_date = col2.select_slider('Slide to the image time',
                                               options=maps_date, value=maps_date[0],
-                                              key='running_map_date')
+                                              key='running_map_date',
+                                              on_change=delete_from_state, kwargs={'vars': ['hek_responses']})
     else:
         running_map_date = maps_date[0]
 
@@ -368,6 +407,15 @@ def run():
     fig, axis = figure_streamlit(st, running_map, image_mode, imager_select, model)
     st.pyplot(fig)
 
+    if st.session_state.plot_hek and st.session_state.hek_responses['Flares']:
+        st.markdown('**HEK Flare List:**')
+        st.write(st.session_state.hek_responses['Flares'].to_pandas())
+        st.markdown('*Flares with no location have been removed from the table.')
+    if st.session_state.plot_hek and st.session_state.hek_responses['Active Regions']:
+        st.markdown('**HEK Active Regions List:**')
+        st.write(st.session_state.hek_responses['Active Regions'].to_pandas())
+        st.markdown('*Active Regions without NOAA number have been removed from the table.')
+
     if plt_supp_imagers:
         if len(st.session_state.imagers_list_) < 3:
             other_element = [element for element in st.session_state.imagers_list_ if element != imager_select][0]

{pythea-0.12.0 → pythea-0.14.0}/PyThea/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.12.0'
-__version_tuple__ = version_tuple = (0, 12, 0)
+__version__ = version = '0.14.0'
+__version_tuple__ = version_tuple = (0, 14, 0)

{pythea-0.12.0 → pythea-0.14.0}/PyThea/callbacks.py

@@ -3,10 +3,24 @@ from sunpy.coordinates import frames
 
 
 def load_or_delete_fittings(st):
+    """
+    Load or delete fitting parameters from the model fittings based on user selection.
+
+    Parameters
+    ----------
+    st : Streamlit session state object
+        Streamlit session state object for managing UI components.
+
+    Returns
+    -------
+    None
+    """
     selected_row = str(st.session_state.fitting_select)
     dataframe = st.session_state.model_fittings.parameters
+
     if st.session_state.fit_action == 'Select':
         pass
+
     elif st.session_state.fit_action == 'Load':
         if st.session_state.coord_system == 'HGS':
             st.session_state.longit = float(dataframe.loc[selected_row, 'hgln'])
@@ -27,6 +41,7 @@ def load_or_delete_fittings(st):
                 # del st.session_state[key]
                 st.session_state[key] = float(dataframe.loc[selected_row, key])
         del st.session_state.fit_action
+
     elif st.session_state.fit_action == 'Delete':
         st.session_state.model_fittings.parameters = dataframe.drop(st.session_state.fitting_select)
         del st.session_state.fitting_select
@@ -36,6 +51,18 @@ def load_or_delete_fittings(st):
 
 
 def change_long_lat_sliders(st):
+    """
+    Update longitude and latitude sliders based on the selected coordinate system.
+
+    Parameters
+    ----------
+    st : Streamlit session state object
+        Streamlit session state object for managing UI components.
+
+    Returns
+    -------
+    None
+    """
     if st.session_state.coord_system == 'HGS':
         center_ = st.session_state.center.transform_to(frames.HeliographicStonyhurst)
     elif st.session_state.coord_system == 'HGC':
@@ -46,9 +73,22 @@ def change_long_lat_sliders(st):
 
 
 def change_fitting_sliders(st):
+    """
+    Update fitting sliders based on the selected fitting method.
+
+    Parameters
+    ----------
+    st : Streamlit session state object
+        Streamlit session state object for managing UI components.
+
+    Returns
+    -------
+    None
+    """
     st.session_state.startup['fitting'] = False
     fit_opt = st.session_state.fit_args_prime
     st.session_state.fit_mode = fit_opt['type']
+
     if fit_opt['type'] == 'polynomial':
         st.session_state.polyfit_order = fit_opt['order']
     elif fit_opt['type'] == 'spline':

{pythea-0.12.0 → pythea-0.14.0}/PyThea/config/__init__.py

@@ -1,3 +1,8 @@
+import os
+from pathlib import Path
+
 from PyThea.config.config_sliders import *
 from PyThea.config.selected_bodies import *
 from PyThea.config.selected_imagers import *
+
+database_dir_default = os.path.join(Path.home(), 'PyThea')

{pythea-0.12.0 → pythea-0.14.0}/PyThea/config/selected_imagers.py

@@ -4,6 +4,7 @@
 
 '''
 import astropy.units as u
+import sunpy_soar  # noqa
 from sunpy.net import attrs as a
 
 imager_dict = {}
@@ -63,3 +64,19 @@ imager_dict['HI2A'] = {'fido': (a.Source('STEREO_A'), a.Detector.hi2),
 imager_dict['HI2B'] = {'fido': (a.Source('STEREO_B'), a.Detector.hi2),
                        'process': {'dimensions': (1024*u.pixel, 1024*u.pixel), 'superpixel': 2},
                        'source': 'STEREO_B', 'instrument': 'SECCHI', 'detector': 'HI2'}
+
+imager_dict['WISPR1'] = {'fido': (a.Instrument.wispr, a.Detector.inner),
+                         'process': {'dimensions': (960*u.pixel, 1024*u.pixel), 'processing_level': 3, 'superpixel': 2},
+                         'source': 'PSP', 'instrument': 'WISPR', 'detector': 'Inner'}
+
+imager_dict['WISPR2'] = {'fido': (a.Instrument.wispr, a.Detector.outer),
+                         'process': {'dimensions': (960*u.pixel, 1024*u.pixel), 'processing_level': 3, 'superpixel': 2},
+                         'source': 'PSP', 'instrument': 'WISPR', 'detector': 'Outer'}
+
+imager_dict['EUI-FSI'] = {'fido': (a.Instrument('EUI'), a.soar.Product('EUI-FSI174-IMAGE'), a.Level(2)),
+                          'process': {'superpixel': 1},
+                          'source': 'SOLO', 'instrument': 'EUI-FSI', 'wavelength': '174'}
+
+imager_dict['METIS'] = {'fido': (a.Instrument('METIS'), a.soar.Product('METIS-VL-TB'), a.Level(2)),
+                        'process': {'dimensions': (1024*u.pixel, 1024*u.pixel), 'superpixel': 2},
+                        'source': 'SOLO', 'instrument': 'METIS', 'detector': 'VLD', 'wavelength': 'TB'}

{pythea-0.12.0 → pythea-0.14.0}/PyThea/data/sample_data.py

@@ -1,13 +1,13 @@
 import os
-from pathlib import Path
 
 import pooch
 
-database_dir = os.path.join(Path.home(), 'PyThea')
+from PyThea.config import database_dir_default
+
 github_main_url = 'https://github.com/AthKouloumvakos/PyThea-sample-data'
 
 aia_sample_data = pooch.create(
-    path=os.path.join(database_dir, 'sample_data'),  # The cache folder
+    path=os.path.join(database_dir_default, 'sample_data'),  # The cache folder
     base_url=f'{github_main_url}/raw/main/data/',  # The remote data url on Github
     registry={
         'aia_lev1_1600a_2012_06_06t04_07_29_12z_image_lev1.fits': 'sha256:7e88d8a277ad3dd111c1bcff3c3936d6d5ef5186e05b4bfa7749ee43c05577d5',
@@ -16,7 +16,7 @@ aia_sample_data = pooch.create(
 )
 
 stereo_sample_data = pooch.create(
-    path=os.path.join(database_dir, 'sample_data'),  # The cache folder
+    path=os.path.join(database_dir_default, 'sample_data'),  # The cache folder
     base_url=f'{github_main_url}/raw/main/data/',  # The remote data url on Github
     registry={
         '20120622_235400_d4c2a.fts': 'sha256:940680fe8bea754c9859170585d8299b9b049b631155435a31ecacf5b702d9cf',
@@ -26,8 +26,17 @@ stereo_sample_data = pooch.create(
     },
 )
 
+wispr_sample_data = pooch.create(
+    path=os.path.join(database_dir_default, 'sample_data'),  # The cache folder
+    base_url=f'{github_main_url}/raw/main/data/',  # The remote data url on Github
+    registry={
+        'psp_l3_wispr_20210808t103707_v1_1211.fits': 'sha256:85035693c4677e8fa8a3e61b8051d6f0a46e96806b5b0cbdb3efa77652308bda',
+        'psp_l3_wispr_20210808t104010_v1_2222.fits': 'sha256:5e55e17f1aed7dc96f88b79f092947c58e6ee0def1b72822dbf1a696d8df7e6f'
+    },
+)
+
 json_fitting_file_sample_data = pooch.create(
-    path=os.path.join(database_dir, 'sample_data'),  # The cache folder
+    path=os.path.join(database_dir_default, 'sample_data'),  # The cache folder
     base_url=f'{github_main_url}/raw/main/data/',  # The remote data url on Github
     registry={
         'FLX1p0D20211028T153500MEllipsoid.json': 'sha256:34fced8530875110117ba27a73541d3acd0c90bc8fca99367c1ec4cdfc05ce86',

pythea-0.14.0/PyThea/extensions/Parker_spirals/__init__.py

@@ -0,0 +1,62 @@
+import astropy.units as u
+import numpy as np
+from astropy.coordinates import SkyCoord
+
+
+def spiral(pos, sw_speed, date, omega=360. * u.degree / (25.38 * 24 * 60 * 60 * u.second)):
+    """
+    Calculates the Parker spiral coordinates based on the input position, solar wind speed, and date.
+
+    Parameters
+    ----------
+    pos : astropy.coordinates.SkyCoord
+        The initial position in heliographic Carrington coordinates.
+    sw_speed : astropy.units.Quantity
+        The solar wind speed (should be in velocity units, e.g., km/s).
+    date : astropy.time.Time
+        The observation time.
+    omega : astropy.units.Quantity, optional
+        The solar rotation rate in radians per second (default is sidereal period).
+
+    Returns
+    -------
+    astropy.coordinates.SkyCoord
+        The calculated spiral coordinates in heliographic Carrington coordinates.
+    """
+    r = np.arange(1, pos.radius.to_value(u.R_sun), 0.1)
+    r = np.append(r, pos.radius.to_value(u.R_sun)) * u.R_sun
+    alpha = omega * ((pos.radius - r) / sw_speed)
+    hg_coord = SkyCoord(pos.lon + alpha, pos.lat, r,
+                        frame='heliographic_carrington',
+                        observer='earth',
+                        obstime=date)
+    return hg_coord
+
+
+def footpoint(pos, sw_speed, date, r=1*u.R_sun, omega=360. * u.degree / (25.38 * 24 * 60 * 60 * u.second)):
+    """
+    Calculates the footpoint location based on the input position, solar wind speed, and date.
+
+    Parameters
+    ----------
+    pos : astropy.coordinates.SkyCoord
+        The initial position in heliographic Carrington coordinates.
+    sw_speed : astropy.units.Quantity
+        The solar wind speed (should be in velocity units, e.g., km/s).
+    date : astropy.time.Time
+        The observation time.
+    r : astropy.units.Quantity, optional
+        The radial distance for the footpoint (default is 1 solar radius).
+    omega : astropy.units.Quantity, optional
+        The solar rotation rate in radians per second (default is 2.7e-6 rad/s).
+
+    Returns
+    -------
+    astropy.coordinates.SkyCoord
+        The calculated footpoint coordinates in heliographic Carrington coordinates.
+    """
+    alpha = omega * ((pos.radius - r) / sw_speed)
+    hg_coord = SkyCoord(pos.lon + alpha, pos.lat, r,
+                        frame='heliographic_carrington',
+                        observer='earth', obstime=date)
+    return hg_coord

pythea-0.14.0/PyThea/extensions/Parker_spirals/utils.py

@@ -0,0 +1,45 @@
+import astropy.units as u
+from sunpy.coordinates import frames, get_horizons_coord
+
+from PyThea.config.selected_bodies import bodies_dict
+from PyThea.extensions import Parker_spirals
+
+
+def plot_parker_spiral(axis, map, bodies, sw_speed=350 * (u.km / u.second)):
+    """
+    Plot Parker spiral for specified bodies on the given map axis.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes.Axes
+        The axis on which to plot the Parker spiral.
+    map : sunpy.map.Map
+        The solar map on which the Parker spiral will be plotted.
+    bodies : list of str
+        List of bodies for which to plot the Parker spiral.
+    sw_speed : Quantity, optional
+        Solar wind speed for the Parker spiral (default: 350 km/s).
+
+    Returns
+    -------
+    None
+    """
+    for body in bodies:
+        pos = get_horizons_coord(bodies_dict[body][0], map.date_average, 'id')
+        pos = pos.transform_to(frames.HeliographicCarrington(observer='Earth', obstime=map.date_average))
+
+        spiral_coord = Parker_spirals.spiral(pos, sw_speed[body], map.date_average)
+
+        hpc_frame = frames.Helioprojective(observer=map.observer_coordinate, obstime=map.date_average)
+
+        spiral_coord_visible_index = spiral_coord.transform_to(hpc_frame).is_visible()
+
+        axis.plot_coord(spiral_coord[spiral_coord_visible_index], markersize=0, linewidth=1, color=bodies_dict[body][1])
+        if spiral_coord_visible_index[1]:
+            axis.plot_coord(spiral_coord[0], markersize=16, linewidth=10, marker='+', color=bodies_dict[body][1])
+        else:
+            axis.plot_coord(spiral_coord[0], markersize=16, linewidth=10, marker='+', color='white')
+
+        axis.plot_coord(spiral_coord[0], markersize=3, linewidth=4, marker='s', color=bodies_dict[body][1])
+
+        axis.plot_coord(spiral_coord[-1], markersize=8, linewidth=6, marker='x', color=bodies_dict[body][1])

pythea-0.14.0/PyThea/extensions/hek/utils.py

@@ -0,0 +1,118 @@
+import astropy.units as u
+import numpy as np
+from astropy.coordinates import SkyCoord
+from astropy.time import Time, TimeDelta
+from sunpy.coordinates import frames
+from sunpy.net import attrs as a
+from sunpy.net import hek
+from sunpy.physics.differential_rotation import solar_rotate_coordinate
+from sunpy.time import parse_time
+
+
+def plot_hek(axis, map, mode, time_range=[-2, 2], hek_responses=None):
+    """
+    Plots HEK (Heliophysics Event Knowledgebase) events on a given axis.
+
+    This function fetches and plots HEK events, such as Active Regions, Coronal Holes, or Flares, on a provided
+    matplotlib axis using data from a SunPy map object.
+
+    Parameters
+    ----------
+    axis : matplotlib.axes._subplots.AxesSubplot
+        The matplotlib axis to plot on.
+    map : sunpy.map.Map
+        The SunPy map object containing the data.
+    mode : str
+        The type of HEK events to plot ('Active Regions', 'Coronal Holes', or 'Flares').
+    time_range : list, optional
+        Time range in hours around the map date to search for events (default is [-2, 2]).
+    hek_responses : dict, optional
+        Pre-fetched HEK responses (default is None).
+
+    Returns
+    -------
+    responses: list
+        The list of HEK event responses.
+    """
+    hek_client = hek.HEKClient()
+    start_time = map.date_average + TimeDelta(time_range[0] * u.hour)
+    end_time = map.date_average + TimeDelta(time_range[1] * u.hour)
+
+    if mode == 'Active Regions':
+        if hek_responses is None or not hek_responses['Active Regions']:
+            responses = hek_client.search(a.Time(start_time, end_time),
+                                          a.hek.AR, a.hek.FRM.Name == 'HMI SHARP')
+
+            responses.keep_columns(['ar_noaanum', 'ar_mcintoshcls', 'ar_mtwilsoncls', 'hgs_x', 'hgs_y', 'event_starttime'])
+            indx = [i for i, x in enumerate(responses['ar_noaanum']) if x is None]
+            responses.remove_rows(indx)
+            responses = responses[['ar_noaanum', 'ar_mcintoshcls', 'ar_mtwilsoncls', 'hgs_x', 'hgs_y', 'event_starttime']]
+            dates = Time(responses['event_starttime'])
+            time_diff = np.abs(dates - map.date_average)
+            time_diff_seconds = np.array([td.sec for td in time_diff])
+            if len(np.unique(time_diff_seconds)) > 1:
+                responses.remove_rows(np.where(time_diff_seconds == np.max(time_diff_seconds)))
+
+            responses_ = hek_client.search(a.Time(start_time, end_time),
+                                           a.hek.AR, a.hek.FRM.Name == 'NOAA SWPC Observer')
+            responses_.keep_columns(['ar_noaanum', 'ar_mcintoshcls', 'ar_mtwilsoncls', 'hgs_x', 'hgs_y'])
+
+            responses['ar_mcintoshcls'] = np.full(responses['ar_noaanum'].shape[0], None)
+            responses['ar_mtwilsoncls'] = np.full(responses['ar_noaanum'].shape[0], None)
+
+            for rn, clm, clw in zip(responses_['ar_noaanum'], responses_['ar_mcintoshcls'], responses_['ar_mtwilsoncls']):
+                i = np.argwhere(responses['ar_noaanum'] == rn)
+                responses['ar_mcintoshcls'][i] = clm
+                responses['ar_mtwilsoncls'][i] = clw
+            print(responses)
+        else:
+            responses = hek_responses['Active Regions']
+
+        for i, response in enumerate(responses):
+            axis.annotate(i, (float(response['hgs_x']), float(response['hgs_y'])),
+                          xytext=(float(response['hgs_x']), float(response['hgs_y'])),
+                          xycoords=axis.get_transform('heliographic_stonyhurst'),
+                          backgroundcolor='none',
+                          color='tab:blue',
+                          fontsize=8,
+                          horizontalalignment='center', verticalalignment='center')
+    elif mode == 'Coronal Holes':
+        if hek_responses is None or not hek_responses['Coronal Holes']:
+            responses = hek_client.search(a.Time(start_time, end_time),
+                                          a.hek.CH, a.hek.FRM.Name == 'SPoCA')
+        else:
+            responses = hek_responses['Coronal Holes']
+
+        for response in responses:
+            p1 = response['hpc_boundcc'][9:-2]
+            p2 = p1.split(',')
+            p3 = [v.split(' ') for v in p2]
+            ch_date = parse_time(response['event_starttime'])
+            ch_boundary = SkyCoord(
+                [(float(v[0]), float(v[1])) * u.arcsec for v in p3],
+                obstime=ch_date, observer='earth',
+                frame=frames.Helioprojective)
+            rotated_ch_boundary = solar_rotate_coordinate(ch_boundary, time=map.date_average)
+            axis.plot_coord(rotated_ch_boundary, color='c')
+    elif mode == 'Flares':
+        if hek_responses is None or not hek_responses['Flares']:
+            responses = hek_client.search(a.Time(start_time, end_time),
+                                          a.hek.FL, a.hek.FRM.Name == 'SWPC')
+            responses.keep_columns(['event_starttime', 'event_peaktime', 'fl_goescls', 'hgs_x', 'hgs_y', 'ar_noaanum'])
+            responses.remove_rows(np.where((responses['hgs_x'] == 0) & (responses['hgs_y'] == 0)))
+            responses = responses[['event_starttime', 'event_peaktime', 'fl_goescls', 'hgs_x', 'hgs_y', 'ar_noaanum']]
+        else:
+            responses = hek_responses['Flares']
+
+        for i, response in enumerate(responses):
+            axis.annotate(i, (float(response['hgs_x']), float(response['hgs_y'])),
+                          xytext=(float(response['hgs_x']), float(response['hgs_y'])),
+                          xycoords=axis.get_transform('heliographic_stonyhurst'),
+                          backgroundcolor='none',
+                          color='tab:red',
+                          fontsize=8,
+                          horizontalalignment='center', verticalalignment='center')
+    else:
+        raise ValueError(f"Unsupported mode: {mode}. Use 'Coronal Holes' or 'Flares'.")
+
+    return responses