spectre-core 0.0.9__py3-none-any.whl → 0.0.11__py3-none-any.whl

spectre_core/spectrograms/{analytical.py → _analytical.py}

@@ -2,17 +2,21 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Callable, Any
+from typing import Callable
 from dataclasses import dataclass
 
 import numpy as np
 
-from spectre_core.file_handlers.configs import CaptureConfig
-from spectre_core.spectrograms.spectrogram import Spectrogram
-from spectre_core.spectrograms.array_operations import is_close
+from spectre_core.capture_configs import CaptureConfig, PNames
 from spectre_core.exceptions import ModeNotFoundError
+from ._spectrogram import Spectrogram
+from ._array_operations import is_close
 
-
+__all__ = [
+    "get_analytical_spectrogram",
+    "validate_analytically",
+    "TestResults"
+]
 
 @dataclass
 class TestResults:
@@ -36,7 +40,7 @@ class TestResults:
         return len(self.spectrum_validated) - self.num_validated_spectrums
     
 
-    def jsonify(self) -> dict[str, Any]:
+    def to_dict(self) -> dict[str, bool | dict[float, bool]]:
         return {
             "times_validated": self.times_validated,
             "frequencies_validated": self.frequencies_validated,
@@ -72,14 +76,13 @@ class _AnalyticalFactory:
         by parameters in the corresponding capture config and the number of spectrums
         in the output spectrogram.
         """
-        receiver_name, test_mode = capture_config['receiver'], capture_config['mode']
 
-        if receiver_name != "test":
+        if capture_config.receiver_name != "test":
             raise ValueError(f"Input capture config must correspond to the test receiver")
         
-        builder_method = self.builders.get(test_mode)
+        builder_method = self.builders.get(capture_config.receiver_mode)
         if builder_method is None:
-            raise ModeNotFoundError(f"Test mode not found. Expected one of {self.test_modes}, but received {test_mode}")
+            raise ModeNotFoundError(f"Test mode not found. Expected one of {self.test_modes}, but received {capture_config.receiver_mode}")
         return builder_method(num_spectrums, 
                               capture_config)
     
@@ -88,14 +91,14 @@ class _AnalyticalFactory:
                         num_spectrums: int,
                         capture_config: CaptureConfig) -> Spectrogram:
         # Extract necessary parameters from the capture configuration.
-        window_size = capture_config['window_size']
-        samp_rate = capture_config['samp_rate']
-        amplitude = capture_config['amplitude']
-        frequency = capture_config['frequency']
-        hop = capture_config['hop']
-
+        window_size      = capture_config.get_parameter_value(PNames.WINDOW_SIZE)
+        sample_rate      = capture_config.get_parameter_value(PNames.SAMPLE_RATE)
+        amplitude        = capture_config.get_parameter_value(PNames.AMPLITUDE)
+        frequency        = capture_config.get_parameter_value(PNames.FREQUENCY)
+        window_hop       = capture_config.get_parameter_value(PNames.WINDOW_HOP)
+        center_frequency = capture_config.get_parameter_value(PNames.CENTER_FREQUENCY)
         # Calculate derived parameters a (sampling rate ratio) and p (sampled periods).
-        a = int(samp_rate / frequency)
+        a = int(sample_rate / frequency)
         p = int(window_size / a)
 
         # Create the analytical spectrum, which is constant in time.
@@ -111,11 +114,11 @@ class _AnalyticalFactory:
         analytical_dynamic_spectra = np.ones((window_size, num_spectrums)) * spectrum[:, np.newaxis]
 
         # Compute time array.
-        sampling_interval = 1 / samp_rate
-        times = np.arange(num_spectrums) * hop * sampling_interval
+        sampling_interval = 1 / sample_rate
+        times = np.arange(num_spectrums) * window_hop * sampling_interval
 
         # compute the frequency array.
-        frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval))
+        frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval)) + center_frequency
 
         # Return the spectrogram.
         return Spectrogram(analytical_dynamic_spectra,
@@ -129,11 +132,11 @@ class _AnalyticalFactory:
                         num_spectrums: int,
                         capture_config: CaptureConfig) -> Spectrogram:
         # Extract necessary parameters from the capture configuration.
-        window_size = capture_config['window_size']
-        min_samples_per_step = capture_config['min_samples_per_step']
-        max_samples_per_step = capture_config['max_samples_per_step']
-        step_increment = capture_config['step_increment']
-        samp_rate = capture_config['samp_rate']
+        window_size          = capture_config.get_parameter_value(PNames.WINDOW_SIZE)
+        min_samples_per_step = capture_config.get_parameter_value(PNames.MIN_SAMPLES_PER_STEP)
+        max_samples_per_step = capture_config.get_parameter_value(PNames.MAX_SAMPLES_PER_STEP)
+        step_increment       = capture_config.get_parameter_value(PNames.STEP_INCREMENT)
+        samp_rate            = capture_config.get_parameter_value(PNames.SAMPLE_RATE)
 
         # Calculate step sizes and derived parameters.
         num_samples_per_step = np.arange(min_samples_per_step, max_samples_per_step + 1, step_increment)
@@ -152,11 +155,10 @@ class _AnalyticalFactory:
 
         # Compute time array
         num_samples_per_sweep = sum(num_samples_per_step)
-        midpoint_sample = sum(num_samples_per_step) // 2
         sampling_interval = 1 / samp_rate
         # compute the sample index we are "assigning" to each spectrum
         # and multiply by the sampling interval to get the equivalent physical time
-        times = np.array([ midpoint_sample + (i * num_samples_per_sweep) for i in range(num_spectrums) ]) * sampling_interval
+        times = np.array([(i * num_samples_per_sweep) for i in range(num_spectrums) ]) * sampling_interval
 
         # Compute the frequency array
         baseband_frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval))

spectre_core/spectrograms/{array_operations.py → _array_operations.py}

@@ -6,6 +6,53 @@ from datetime import datetime
 
 import numpy as np
 
+def average_array(array: np.ndarray, average_over: int, axis=0) -> np.ndarray:
+
+    # Check if average_over is an integer
+    if type(average_over) != int:
+        raise TypeError(f"average_over must be an integer. Got {type(average_over)}")
+
+    # Get the size of the specified axis which we will average over
+    axis_size = array.shape[axis]
+    # Check if average_over is within the valid range
+    if not 1 <= average_over <= axis_size:
+        raise ValueError(f"average_over must be between 1 and the length of the axis ({axis_size})")
+    
+    max_axis_index = len(np.shape(array)) - 1
+    if axis > max_axis_index: # zero indexing on specifying axis, so minus one
+        raise ValueError(f"Requested axis is out of range of array dimensions. Axis: {axis}, max axis index: {max_axis_index}")
+
+    # find the number of elements in the requested axis
+    num_elements = array.shape[axis]
+
+    # find the number of "full blocks" to average over
+    num_full_blocks = num_elements // average_over
+    # if num_elements is not exactly divisible by average_over, we will have some elements left over
+    # these remaining elements will be padded with nans to become another full block
+    remainder = num_elements % average_over
+    
+    # if there exists a remainder, pad the last block
+    if remainder != 0:
+        # initialise an array to hold the padding shape
+        padding_shape = [(0, 0)] * array.ndim
+        # pad after the last column in the requested axis
+        padding_shape[axis] = (0, average_over - remainder)
+        # pad with nan values (so to not contribute towards the mean computation)
+        array = np.pad(array, padding_shape, mode='constant', constant_values=np.nan)
+    
+    # initalise a list to hold the new shape
+    new_shape = list(array.shape)
+    # update the shape on the requested access (to the number of blocks we will average over)
+    new_shape[axis] = num_full_blocks + (1 if remainder else 0)
+    # insert a new dimension, with the size of each block
+    new_shape.insert(axis + 1, average_over)
+    # and reshape the array to sort the array into the relevant blocks.
+    reshaped_array = array.reshape(new_shape)
+    # average over the newly created axis, essentially averaging over the blocks.
+    averaged_array = np.nanmean(reshaped_array, axis=axis + 1)
+    # return the averaged array
+    return averaged_array
+
 
 def is_close(ar: np.ndarray, 
              ar_comparison: np.ndarray,
@@ -15,7 +62,6 @@ def is_close(ar: np.ndarray,
                              ar_comparison, 
                              atol=absolute_tolerance))
 
-
 def find_closest_index(
     target_value: float | datetime, 
     array: np.ndarray, 

spectre_core/spectrograms/{spectrogram.py → _spectrogram.py}

@@ -2,18 +2,18 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-import os
-from typing import Optional, Any
+from typing import Optional
 from warnings import warn
 from datetime import datetime, timedelta
 from dataclasses import dataclass
+import os
 
 import numpy as np
 from astropy.io import fits
 
-from spectre_core.file_handlers.configs import FitsConfig
-from spectre_core.cfg import DEFAULT_DATETIME_FORMAT, get_chunks_dir_path
-from spectre_core.spectrograms.array_operations import (
+from spectre_core.capture_configs import CaptureConfig, PNames
+from spectre_core.config import get_chunks_dir_path, TimeFormats
+from ._array_operations import (
     find_closest_index,
     normalise_peak_intensity,
     compute_resolution,
@@ -21,6 +21,14 @@ from spectre_core.spectrograms.array_operations import (
     subtract_background,
 )
 
+__all__ = [
+    "FrequencyCut",
+    "TimeCut",
+    "TimeTypes",
+    "SpectrumTypes",
+    "Spectrogram"
+]
+
 @dataclass
 class FrequencyCut:
     time: float | datetime
@@ -35,8 +43,21 @@ class TimeCut:
     times: np.ndarray
     cut: np.ndarray
     spectrum_type: str
+
+
+@dataclass(frozen=True)
+class TimeTypes:
+    SECONDS  : str = "seconds"
+    DATETIMES: str = "datetimes"
     
 
+@dataclass(frozen=True)
+class SpectrumTypes:
+    AMPLITUDE: str = "amplitude"
+    POWER    : str = "power"
+    DIGITS   : str = "digits"
+
+
 class Spectrogram:
     def __init__(self, 
                  dynamic_spectra: np.ndarray, # holds the spectrogram data
@@ -54,6 +75,9 @@ class Spectrogram:
         self._dynamic_spectra_as_dBb: Optional[np.ndarray] = None # cache
 
         # assigned times and frequencies
+        if times[0] != 0:
+            raise ValueError(f"The first spectrum must correspond to t=0 [s]")
+        
         self._times = times
         self._datetimes: Optional[list[datetime]] = None # cache
         self._frequencies = frequencies
@@ -141,7 +165,7 @@ class Spectrogram:
     @property
     def chunk_start_datetime(self) -> datetime:
         if self._chunk_start_datetime is None:
-            self._chunk_start_datetime = datetime.strptime(self.chunk_start_time, DEFAULT_DATETIME_FORMAT)
+            self._chunk_start_datetime = datetime.strptime(self.chunk_start_time, TimeFormats.DATETIME)
         return self._chunk_start_datetime
 
 
@@ -181,9 +205,9 @@ class Spectrogram:
             # Suppress divide by zero and invalid value warnings for this block of code
             with np.errstate(divide='ignore'):
                 # Depending on the spectrum type, compute the dBb values differently
-                if self._spectrum_type == "amplitude" or self._spectrum_type == "digits":
+                if self._spectrum_type == SpectrumTypes.AMPLITUDE or self._spectrum_type == SpectrumTypes.DIGITS:
                     self._dynamic_spectra_as_dBb = 10 * np.log10(self._dynamic_spectra / background_spectra)
-                elif self._spectrum_type == "power":
+                elif self._spectrum_type == SpectrumTypes.POWER:
                     self._dynamic_spectra_as_dBb = 20 * np.log10(self._dynamic_spectra / background_spectra)
                 else:
                     raise NotImplementedError(f"{self.spectrum_type} unrecognised, uncertain decibel conversion!")
@@ -203,12 +227,12 @@ class Spectrogram:
     
     
     def _update_background_indices_from_interval(self) -> None:
-        start_background = datetime.strptime(self._start_background, DEFAULT_DATETIME_FORMAT)
+        start_background = datetime.strptime(self._start_background, TimeFormats.DATETIME)
         self._start_background_index = find_closest_index(start_background, 
                                                           self.datetimes, 
                                                           enforce_strict_bounds=True)
         
-        end_background = datetime.strptime(self._end_background, DEFAULT_DATETIME_FORMAT)
+        end_background = datetime.strptime(self._end_background, TimeFormats.DATETIME)
         self._end_background_index = find_closest_index(end_background, 
                                                         self.datetimes, 
                                                         enforce_strict_bounds=True)
@@ -229,16 +253,13 @@ class Spectrogram:
         
 
     def save(self) -> None:
-        fits_config = FitsConfig(self._tag)
-        fits_config = fits_config if fits_config.exists else {}
-
-        chunk_start_datetime = self.chunk_start_datetime
-        chunk_parent_path = get_chunks_dir_path(year = chunk_start_datetime.year,
-                                                month = chunk_start_datetime.month,
-                                                day = chunk_start_datetime.day)
+        chunk_parent_path = get_chunks_dir_path(year  = self.chunk_start_datetime.year,
+                                                month = self.chunk_start_datetime.month,
+                                                day   = self.chunk_start_datetime.day)
         file_name = f"{self.chunk_start_time}_{self._tag}.fits"
-        write_path = os.path.join(chunk_parent_path, file_name)
-        _save_spectrogram(write_path, self, fits_config)
+        write_path = os.path.join(chunk_parent_path, 
+                                  file_name)
+        _save_spectrogram(write_path, self)
     
 
     def integrate_over_frequency(self, 
@@ -266,7 +287,7 @@ class Spectrogram:
         # exactly to one of the times assigned to each spectrogram. So, we compute the nearest achievable,
         # and return it from the function as output too.
         if isinstance(at_time, str):
-            at_time = datetime.strptime(at_time, DEFAULT_DATETIME_FORMAT)
+            at_time = datetime.strptime(at_time, TimeFormats.DATETIME)
             index_of_cut = find_closest_index(at_time, 
                                               self.datetimes, 
                                               enforce_strict_bounds = True)
@@ -306,7 +327,7 @@ class Spectrogram:
                      dBb: bool = False,
                      peak_normalise = False, 
                      correct_background = False, 
-                     return_time_type: str = "seconds") -> TimeCut:
+                     return_time_type: str = TimeTypes.SECONDS) -> TimeCut:
         
         # it is important to note that the "at frequency" specified by the user likely does not correspond
         # exactly to one of the physical frequencies assigned to each spectral component. So, we compute the nearest achievable,
@@ -316,9 +337,9 @@ class Spectrogram:
                                           enforce_strict_bounds = True)
         frequency_of_cut = self.frequencies[index_of_cut]
 
-        if return_time_type == "datetimes":
+        if return_time_type == TimeTypes.DATETIMES:
             times = self.datetimes
-        elif return_time_type == "seconds":
+        elif return_time_type == TimeTypes.SECONDS:
             times = self.times
         else:
             raise ValueError(f"Invalid return_time_type. Got {return_time_type}, expected one of 'datetimes' or 'seconds'")
@@ -359,10 +380,16 @@ def _seconds_of_day(dt: datetime) -> float:
 
 # Function to create a FITS file with the specified structure
 def _save_spectrogram(write_path: str, 
-                      spectrogram: Spectrogram, 
-                      fits_config: FitsConfig | dict[str, Any]) -> None:
-    if spectrogram.chunk_start_time is None:
-        raise ValueError(f"Spectrogram must have a defined chunk_start_time. Received {spectrogram.chunk_start_time}")
+                      spectrogram: Spectrogram) -> None:
+    
+    capture_config = CaptureConfig(spectrogram.tag)
+    ORIGIN    = capture_config.get_parameter_value(PNames.ORIGIN)
+    INSTRUME  = capture_config.get_parameter_value(PNames.INSTRUMENT)
+    TELESCOP  = capture_config.get_parameter_value(PNames.TELESCOPE)
+    OBJECT    = capture_config.get_parameter_value(PNames.OBJECT)
+    OBS_ALT   = capture_config.get_parameter_value(PNames.OBS_ALT)
+    OBS_LAT   = capture_config.get_parameter_value(PNames.OBS_LAT)
+    OBS_LON   = capture_config.get_parameter_value(PNames.OBS_LON)
     
     # Primary HDU with data
     primary_data = spectrogram.dynamic_spectra.astype(dtype=np.float32) 
@@ -397,10 +424,10 @@ def _save_spectrogram(write_path: str,
 
     primary_hdu.header.set('DATE', start_date, 'time of observation')
     primary_hdu.header.set('CONTENT', f'{start_date} dynamic spectrogram', 'title of image')
-    primary_hdu.header.set('ORIGIN', f'{fits_config.get("ORIGIN")}')
-    primary_hdu.header.set('TELESCOP', f'{fits_config.get("TELESCOP")} tag: {spectrogram.tag}', 'type of instrument')
-    primary_hdu.header.set('INSTRUME', f'{fits_config.get("INSTRUME")}') 
-    primary_hdu.header.set('OBJECT', f'{fits_config.get("OBJECT")}', 'object description')
+    primary_hdu.header.set('ORIGIN', f'{ORIGIN}')
+    primary_hdu.header.set('TELESCOP', f'{TELESCOP}', 'type of instrument')
+    primary_hdu.header.set('INSTRUME', f'{INSTRUME}') 
+    primary_hdu.header.set('OBJECT', f'{OBJECT}', 'object description')
 
     primary_hdu.header.set('DATE-OBS', f'{start_date}', 'date observation starts')
     primary_hdu.header.set('TIME-OBS', f'{start_time}', 'time observation starts')
@@ -424,17 +451,17 @@ def _save_spectrogram(write_path: str,
     primary_hdu.header.set('CTYPE2', 'Frequency [Hz]', 'title of axis 2')
     primary_hdu.header.set('CDELT2', spectrogram.frequency_resolution, 'step between first and second element in axis')
 
-    primary_hdu.header.set('OBS_LAT', f'{fits_config.get("OBS_LAT")}', 'observatory latitude in degree')
+    primary_hdu.header.set('OBS_LAT', f'{OBS_LAT}', 'observatory latitude in degree')
     primary_hdu.header.set('OBS_LAC', 'N', 'observatory latitude code {N,S}')
-    primary_hdu.header.set('OBS_LON', f'{fits_config.get("OBS_LON")}', 'observatory longitude in degree')
+    primary_hdu.header.set('OBS_LON', f'{OBS_LON}', 'observatory longitude in degree')
     primary_hdu.header.set('OBS_LOC', 'W', 'observatory longitude code {E,W}')
-    primary_hdu.header.set('OBS_ALT', f'{fits_config.get("OBS_ALT")}', 'observatory altitude in meter asl')
+    primary_hdu.header.set('OBS_ALT', f'{OBS_ALT}', 'observatory altitude in meter asl')
 
 
     # Wrap arrays in an additional dimension to mimic the e-CALLISTO storage
     times_wrapped = np.array([spectrogram.times.astype(np.float32)])
     # To mimic e-Callisto storage, convert frequencies to MHz
-    frequencies_MHz = spectrogram.frequencies *1e-6
+    frequencies_MHz = spectrogram.frequencies * 1e-6
     frequencies_wrapped = np.array([frequencies_MHz.astype(np.float32)])
     
     # Binary Table HDU (extension)

spectre_core/spectrograms/{transform.py → _transform.py}

@@ -5,59 +5,19 @@
 import numpy as np
 from datetime import datetime, timedelta
 from typing import Optional
+from math import floor
 
-from spectre_core.spectrograms.array_operations import find_closest_index
-from spectre_core.spectrograms.spectrogram import Spectrogram
-from spectre_core.cfg import DEFAULT_DATETIME_FORMAT
-
-
-def _average_array(array: np.ndarray, average_over: int, axis=0) -> np.ndarray:
-
-    # Check if average_over is an integer
-    if type(average_over) != int:
-        raise TypeError(f"average_over must be an integer. Got {type(average_over)}")
-
-    # Get the size of the specified axis which we will average over
-    axis_size = array.shape[axis]
-    # Check if average_over is within the valid range
-    if not 1 <= average_over <= axis_size:
-        raise ValueError(f"average_over must be between 1 and the length of the axis ({axis_size})")
-    
-    max_axis_index = len(np.shape(array)) - 1
-    if axis > max_axis_index: # zero indexing on specifying axis, so minus one
-        raise ValueError(f"Requested axis is out of range of array dimensions. Axis: {axis}, max axis index: {max_axis_index}")
-
-    # find the number of elements in the requested axis
-    num_elements = array.shape[axis]
-
-    # find the number of "full blocks" to average over
-    num_full_blocks = num_elements // average_over
-    # if num_elements is not exactly divisible by average_over, we will have some elements left over
-    # these remaining elements will be padded with nans to become another full block
-    remainder = num_elements % average_over
-    
-    # if there exists a remainder, pad the last block
-    if remainder != 0:
-        # initialise an array to hold the padding shape
-        padding_shape = [(0, 0)] * array.ndim
-        # pad after the last column in the requested axis
-        padding_shape[axis] = (0, average_over - remainder)
-        # pad with nan values (so to not contribute towards the mean computation)
-        array = np.pad(array, padding_shape, mode='constant', constant_values=np.nan)
-    
-    # initalise a list to hold the new shape
-    new_shape = list(array.shape)
-    # update the shape on the requested access (to the number of blocks we will average over)
-    new_shape[axis] = num_full_blocks + (1 if remainder else 0)
-    # insert a new dimension, with the size of each block
-    new_shape.insert(axis + 1, average_over)
-    # and reshape the array to sort the array into the relevant blocks.
-    reshaped_array = array.reshape(new_shape)
-    # average over the newly created axis, essentially averaging over the blocks.
-    averaged_array = np.nanmean(reshaped_array, axis=axis + 1)
-    # return the averaged array
-    return averaged_array
+from spectre_core.config import TimeFormats
+from ._array_operations import find_closest_index, average_array
+from ._spectrogram import Spectrogram
 
+__all__ = [
+    "frequency_chop",
+    "time_chop",
+    "frequency_average",
+    "time_average",
+    "join_spectrograms"
+]
 
 def frequency_chop(input_spectrogram: Spectrogram, 
                    start_frequency: float | int, 
@@ -98,7 +58,7 @@ def frequency_chop(input_spectrogram: Spectrogram,
 def time_chop(input_spectrogram: Spectrogram, 
               start_time: str, 
               end_time: str, 
-              time_format: str = DEFAULT_DATETIME_FORMAT) -> Optional[Spectrogram]:
+              time_format: str = TimeFormats.DATETIME) -> Optional[Spectrogram]:
     
     # parse the strings as datetimes
     start_datetime = datetime.strptime(start_time, time_format)
@@ -122,18 +82,17 @@ def time_chop(input_spectrogram: Spectrogram,
     # chop the spectrogram 
     transformed_dynamic_spectra = input_spectrogram.dynamic_spectra[:, start_index:end_index+1]
 
-    # chop the times array
-    transformed_times = input_spectrogram.times[start_index:end_index+1]
-    #translate the chopped times array to start at zero
-    transformed_times -= transformed_times[0]
-
     # compute the new start datetime following the time chop
     transformed_start_datetime = input_spectrogram.datetimes[start_index]
-    # parse the chunk start time (as string)
-    transformed_chunk_start_time = datetime.strftime(transformed_start_datetime, DEFAULT_DATETIME_FORMAT)
-    # and compute the microsecond correction
+    # compute the microsecond correction, and chunk start time
+    transformed_chunk_start_time = datetime.strftime(transformed_start_datetime, TimeFormats.DATETIME)
     transformed_microsecond_correction = transformed_start_datetime.microsecond
 
+    # chop the times array
+    transformed_times = input_spectrogram.times[start_index:end_index+1]
+    # assign the first spectrum to t=0 [s]
+    transformed_times -= transformed_times[0]
+
     return Spectrogram(transformed_dynamic_spectra, 
                        transformed_times, 
                        input_spectrogram.frequencies, 
@@ -144,33 +103,44 @@ def time_chop(input_spectrogram: Spectrogram,
 
 
 def time_average(input_spectrogram: Spectrogram, 
-                 average_over: int) -> Spectrogram:
-    
+                 resolution: Optional[float] = None,
+                 average_over: Optional[int] = None) -> Spectrogram:
+
     # spectre does not currently support averaging of non-datetime assigned spectrograms
     if input_spectrogram.chunk_start_time is None:
         raise ValueError(f"Input spectrogram is missing chunk start time. Averaging is not yet supported for non-datetime assigned spectrograms")
     
-    # if the user has requested no averaging, just return the same instance unchanged
+    # if nothing is specified, do nothing
+    if (resolution is None) and (average_over is None):
+        average_over = 1
+
+    if not (resolution is not None) ^ (average_over is not None):
+        raise ValueError(f"Exactly one of 'resolution' or 'average_over' "
+                         f"must be specified.")
+    
+    # if the resolution is specified, compute the appropriate number of spectrums to average over
+    # and recall the same function
+    if resolution is not None:
+        average_over = max(1, floor(resolution / input_spectrogram.time_resolution))
+        return time_average(input_spectrogram, average_over=average_over)
+    
+    # No averaging is required, if we have to average over every one spectrum
     if average_over == 1:
         return input_spectrogram
 
     # average the dynamic spectra array
-    transformed_dynamic_spectra = _average_array(input_spectrogram.dynamic_spectra, average_over, axis=1)
-    # average the times array s.t. the ith averaged spectrum is assigned the 
-    transformed_times = _average_array(input_spectrogram.times, average_over)
-
-    # We need to assign timestamps to the averaged spectrums in the spectrograms. The natural way to do this
-    # is to assign the i'th averaged spectrogram to the i'th averaged time stamp. From this,
-    # we then need to compute the chunk start time to assig to the first averaged spectrum,
-    # and update the microsecond correction.
-    
-    # define the initial spectrum as the spectrum at time index 0 in the spectrogram
-    # then, averaged_t0 is the seconds elapsed between the input intial spectrum and the averaged intial spectrum
-    averaged_t0 = float(transformed_times[0])
-    # compute the updated chunk start time and the updated microsecond correction based on averaged_t0
-    corrected_start_datetime = input_spectrogram.datetimes[0] + timedelta(seconds = averaged_t0)
-    # then, compute the transformed chunk start time and microsecond correction
-    transformed_chunk_start_time = corrected_start_datetime.strftime(DEFAULT_DATETIME_FORMAT)
+    transformed_dynamic_spectra = average_array(input_spectrogram.dynamic_spectra, 
+                                                 average_over, 
+                                                 axis=1)
+
+    # We need to assign timestamps to the averaged spectrums in the spectrograms. 
+    # The natural way to do this is to assign the i'th averaged spectrogram 
+    # to the i'th averaged time
+    transformed_times = average_array(input_spectrogram.times, average_over)
+    
+    # find the new chunk start time, which we will assign to the first spectrum after averaging
+    corrected_start_datetime = input_spectrogram.datetimes[0] + timedelta(seconds = float(transformed_times[0]))
+    transformed_chunk_start_time = corrected_start_datetime.strftime(TimeFormats.DATETIME)
     transformed_microsecond_correction = corrected_start_datetime.microsecond
 
     # finally, translate the averaged time seconds to begin at t=0 [s]
@@ -183,18 +153,37 @@ def time_average(input_spectrogram: Spectrogram,
                        microsecond_correction = transformed_microsecond_correction,
                        spectrum_type = input_spectrogram.spectrum_type)
 
+
+
 def frequency_average(input_spectrogram: Spectrogram, 
-                      average_over: int) -> Spectrogram:
+                      resolution: Optional[float] = None,
+                      average_over: Optional[int] = None) -> Spectrogram:
+    
+    # if nothing is specified, do nothing
+    if (resolution is None) and (average_over is None):
+        average_over = 1
+
+    if not (resolution is not None) ^ (average_over is not None):
+        raise ValueError(f"Exactly one of 'resolution' or 'average_over' "
+                         f"must be specified.")
+    
+    # if the resolution is specified, compute the appropriate number of spectrums to average over
+    # and recall the same function
+    if resolution is not None:
+        average_over = max(1, floor(resolution / input_spectrogram.frequency_resolution))
+        return frequency_average(input_spectrogram, average_over=average_over)
     
-    # if the user has requested no averaging, just return the same instance unchanged
+    # No averaging is required, if we have to average over every one spectrum
     if average_over == 1:
         return input_spectrogram
-
+    
     # We need to assign physical frequencies to the averaged spectrums in the spectrograms.
     # is to assign the i'th averaged spectral component to the i'th averaged frequency.
     # average the dynamic spectra array
-    transformed_dynamic_spectra = _average_array(input_spectrogram.dynamic_spectra, average_over, axis=0)
-    transformed_frequencies = _average_array(input_spectrogram.frequencies, average_over)
+    transformed_dynamic_spectra = average_array(input_spectrogram.dynamic_spectra, 
+                                                 average_over, 
+                                                 axis=0)
+    transformed_frequencies = average_array(input_spectrogram.frequencies, average_over)
 
     return Spectrogram(transformed_dynamic_spectra, 
                        input_spectrogram.times, 
@@ -213,6 +202,7 @@ def _time_elapsed(datetimes: np.ndarray) -> np.ndarray:
     # Convert the list of seconds to a NumPy array of type float32
     return np.array(elapsed_time, dtype=np.float32)
 
+
 # we assume that the spectrogram list is ORDERED chronologically
 # we assume there is no time overlap in any of the spectrograms in the list
 def join_spectrograms(spectrograms: list[Spectrogram]) -> Spectrogram:
@@ -254,14 +244,11 @@ def join_spectrograms(spectrograms: list[Spectrogram]) -> Spectrogram:
         start_index = end_index
 
     transformed_times = _time_elapsed(conc_datetimes)
-    
-    transformed_microsecond_correction = conc_datetimes[0].microsecond
 
     return Spectrogram(transformed_dynamic_spectra, 
                        transformed_times, 
                        reference_spectrogram.frequencies, 
                        reference_spectrogram.tag, 
                        chunk_start_time = reference_spectrogram.chunk_start_time,
-                       microsecond_correction = transformed_microsecond_correction,
-                       spectrum_type = reference_spectrogram.spectrum_type) 
-
+                       microsecond_correction = reference_spectrogram.microsecond_correction,
+                       spectrum_type = reference_spectrogram.spectrum_type) 

spectre_core/{post_processing/library → wgetting}/__init__.py

@@ -2,9 +2,8 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from spectre_core.dynamic_imports import import_target_modules
-
-import_target_modules(__file__, __name__, "event_handler")
-
-
+from ._callisto import download_callisto_data, CALLISTO_INSTRUMENT_CODES
 
+__all__ = [
+    "download_callisto_data", "CALLISTO_INSTRUMENT_CODES"
+]