Replace Swift afterglow data retrieval with swifttools API

docs/installation.txt

@@ -77,31 +77,17 @@ phantomjs sometimes will not work with macOS or give a warning that it is no lon
 In the short term, you can locate the file in your finder and right click to open it. Doing so once will allow the app to be used.
 Note phantomjs is not required for any other functionality of redback.
 
-Phantomjs is now replaced with ChromeDriver through selenium.
+Phantomjs and ChromeDriver are now replaced with the swifttools API.
 
-Install :code:`chromedriver` and :code:`selenium`
+Install :code:`swifttools`
 -------------------------
 
-In you want to use :code:`redback` functionality to download Swift data you now need to have Google Chrome installed and update selenium.
-:code:`redback` is tested with Selenium 4.18.1 so please make sure you have this version or higher.
-
-To test if your selenium/chrome installation is ready.
-Please try the following code block.
-
-.. code-block:: console
-
-    $ python
-    >>> from selenium import webdriver
-    >>> driver = webdriver.Chrome()
-    >>> driver.get("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
-
-If a page opens, then you are ready to start using :code:`redback` to download Swift data.
-
-If nothing happens, you may need to install the ChromeDriver separately. You can do this via brew on MacOS
+If you want to use :code:`redback` functionality to download Swift data, you need to install the swifttools package.
+This is included in the optional requirements.
 
 .. code-block:: console
 
-    $ brew install --cask chromedriver
+    $ pip install swifttools
 
-And on Linux and Windows you can download the ChromeDriver and add it to your path from the official chromedriver webpage.
-Note you do not have to do this ideally, as the ChromeDriver is included in the latest selenium package.
+The swifttools package provides direct API access to Swift data from the UK Swift Science Data Centre, 
+eliminating the need for web scraping with Selenium or PhantomJS.

redback/get_data/__init__.py

@@ -37,21 +37,28 @@ def get_xrt_afterglow_data_from_swift(grb: str, data_mode: str = None, **kwargs:
     return get_swift_data(grb=grb, transient_type='afterglow', data_mode=data_mode, instrument="XRT")
 
 
-def get_bat_xrt_afterglow_data_from_swift(grb: str, data_mode: str, **kwargs: None) -> pd.DataFrame:
+def get_bat_xrt_afterglow_data_from_swift(
+        grb: str, data_mode: str, snr: Union[int, str] = 4, force_download: bool = False, **kwargs: None) -> pd.DataFrame:
     """Get BAT+XRT afterglow data from Swift. Creates a directory structure and saves the data.
     Returns the data, though no further action needs to be taken by the user.
 
     :param grb: Telephone number of GRB, e.g., 'GRB140903A' or '140903A' are valid inputs.
     :type grb: str
     :param data_mode: Data mode must be from `redback.get_data.swift.SwiftDataGetter.VALID_DATA_MODES`.
     :type data_mode: str
+    :param snr: BAT Burst Analyser SNR choice (e.g., 4, 5, 6, 7).
+    :type snr: int or str
+    :param force_download: If True, re-download data from API even if cached files exist. (Default value = False)
+    :type force_download: bool, optional
     :param kwargs: Placeholder to prevent TypeErrors.
     :type kwargs: dict
 
     :return: The processed data.
     :rtype: pandas.DataFrame
     """
-    return get_swift_data(grb=grb, transient_type='afterglow', data_mode=data_mode, instrument="BAT+XRT")
+    return get_swift_data(
+        grb=grb, transient_type='afterglow', data_mode=data_mode, instrument="BAT+XRT", 
+        snr=snr, force_download=force_download)
 
 
 def get_prompt_data_from_swift(grb: str, bin_size: str = "1s", **kwargs: None) -> pd.DataFrame:
@@ -74,7 +81,7 @@ def get_prompt_data_from_swift(grb: str, bin_size: str = "1s", **kwargs: None) -
 
 def get_swift_data(
         grb: str, transient_type: str, data_mode: str = 'flux', instrument: str = 'BAT+XRT',
-        bin_size: str = None, **kwargs: None) -> pd.DataFrame:
+        bin_size: str = None, snr: Union[int, str] = 4, force_download: bool = False, **kwargs: None) -> pd.DataFrame:
     """Catch all data getting function for Swift.  Creates a directory structure and saves the data.
     Returns the data, though no further action needs to be taken by the user.
 
@@ -90,6 +97,10 @@ def get_swift_data(
     :param bin_size: Bin size. Must be from `redback.get_data.swift.SwiftDataGetter.SWIFT_PROMPT_BIN_SIZES`.
                      (Default value = None)
     :type bin_size: str, optional
+    :param snr: BAT Burst Analyser SNR choice (e.g., 4, 5, 6, 7).
+    :type snr: int or str
+    :param force_download: If True, re-download data from API even if cached files exist. (Default value = False)
+    :type force_download: bool, optional
     :param kwargs: Placeholder to prevent TypeErrors.
     :type kwargs: None
 
@@ -98,7 +109,7 @@ def get_swift_data(
     """
     getter = SwiftDataGetter(
         grb=grb, transient_type=transient_type, data_mode=data_mode,
-        bin_size=bin_size, instrument=instrument)
+        bin_size=bin_size, instrument=instrument, snr=snr, force_download=force_download)
     return getter.get_data()
 
 

redback/get_data/directory.py

@@ -32,7 +32,7 @@ def spectrum_directory_structure(transient: str) -> DirectoryStructure:
     return DirectoryStructure(
         directory_path=directory_path, raw_file_path=raw_file_path, processed_file_path=processed_file_path)
 
-def afterglow_directory_structure(grb: str, data_mode: str, instrument: str = 'BAT+XRT') -> DirectoryStructure:
+def afterglow_directory_structure(grb: str, data_mode: str, instrument: str = 'BAT+XRT', snr: str = None) -> DirectoryStructure:
     """Provides directory structure for Swift afterglow data.
 
     :param grb: Name of the GRB, e.g. GRB123456.
@@ -41,6 +41,8 @@ def afterglow_directory_structure(grb: str, data_mode: str, instrument: str = 'B
     :type data_mode: str
     :param instrument: Must be in ['BAT+XRT', 'XRT'], default is 'BAT+XRT' (Default value = 'BAT+XRT')
     :type instrument: str, optional
+    :param snr: BAT SNR selection (e.g., 'SNR4', 'SNR5'). If provided, included in file path. (Default value = None)
+    :type snr: str, optional
 
     :return: The directory structure, with 'directory_path', 'raw_file_path', and 'processed_file_path'
     :rtype: namedtuple
@@ -50,13 +52,17 @@ def afterglow_directory_structure(grb: str, data_mode: str, instrument: str = 'B
     check_directory_exists_and_if_not_mkdir(directory_path)
 
     path = f'{directory_path}{grb}'
+
+    # Raw file should NOT include SNR - it contains all data
+    # Processed file SHOULD include SNR - it's filtered data
+    snr_suffix = f'_{snr}' if snr else ''
 
     if instrument == 'XRT':
         raw_file_path = f'{path}_xrt_rawSwiftData.csv'
-        processed_file_path = f'{path}_xrt.csv'
+        processed_file_path = f'{path}_xrt{snr_suffix}.csv'
     else:
         raw_file_path = f'{path}_rawSwiftData.csv'
-        processed_file_path = f'{path}.csv'
+        processed_file_path = f'{path}{snr_suffix}.csv'
 
     return DirectoryStructure(
         directory_path=directory_path, raw_file_path=raw_file_path, processed_file_path=processed_file_path)