spectre-core 0.0.12__py3-none-any.whl → 0.0.13__py3-none-any.whl

spectre_core/post_processing/{library → plugins}/_swept_center_frequency.py

@@ -6,41 +6,45 @@ from logging import getLogger
 _LOGGER = getLogger(__name__)
 
 import os
-from typing import Optional
-from typing import Tuple
-from datetime import timedelta, datetime
+from typing import Optional, Tuple, cast
+from datetime import timedelta
 import numpy as np
+import numpy.typing as npt
 
 from scipy.signal import ShortTimeFFT
 
-from spectre_core.spectrograms import Spectrogram, time_average, frequency_average
-from spectre_core.config import TimeFormats
-from spectre_core.capture_configs import CaptureConfig, PNames, CaptureModes
-from spectre_core.batches import BaseBatch
-from spectre_core.batches import SweepMetadata
+from spectre_core.spectrograms import Spectrogram, SpectrumUnit, time_average, frequency_average
+from spectre_core.capture_configs import CaptureConfig, PName
+from spectre_core.batches import IQStreamBatch
 from spectre_core.exceptions import InvalidSweepMetadataError
+from ._event_handler_keys import EventHandlerKey
 from .._base import BaseEventHandler, make_sft_instance
 from .._register import register_event_handler
 
 
-def _stitch_steps(stepped_dynamic_spectra: np.ndarray,
-                  num_full_sweeps: int) -> np.ndarray:
-    """For each full sweep, create a swept spectrum by stitching together the spectrum at each of the steps."""
+def _stitch_steps(
+    stepped_dynamic_spectra: npt.NDArray[np.float32],
+    num_full_sweeps: int
+) -> npt.NDArray[np.float32]:
+    """For each full sweep, create a single spectrum by stitching together the spectrum at each step."""
     return stepped_dynamic_spectra.reshape((num_full_sweeps, -1)).T
 
     
-def _average_over_steps(stepped_dynamic_spectra: np.ndarray) -> None:
+def _average_over_steps(
+    stepped_dynamic_spectra: npt.NDArray[np.float32]
+) -> npt.NDArray[np.float32]:
     """Average the spectrums in each step totally in time."""
     return np.nanmean(stepped_dynamic_spectra[..., 1:], axis=-1)
 
 
-def _fill_times(times: np.ndarray,
-                num_samples: np.ndarray,
-                sample_rate: int,
-                num_full_sweeps: int,
-                num_steps_per_sweep: int) -> None:
-        """Assign physical times to each swept spectrum. We use (by convention) the time of the first sample in eahc sweep"""
-
+def _fill_times(
+    times: npt.NDArray[np.float32],
+    num_samples: npt.NDArray[np.int32],
+    sample_rate: int,
+    num_full_sweeps: int,
+    num_steps_per_sweep: int
+) -> None:
+        """Assign physical times to each swept spectrum. We use (by convention) the time of the first sample in each sweep"""
         sampling_interval = 1 / sample_rate
         cumulative_samples = 0
         for sweep_index in range(num_full_sweeps):
@@ -55,26 +59,29 @@ def _fill_times(times: np.ndarray,
             cumulative_samples += np.sum(num_samples[start_step:end_step])
 
 
-def _fill_frequencies(frequencies: np.ndarray,
-                      center_frequencies: np.ndarray,
-                      baseband_frequencies: np.ndarray,
-                      window_size: int) -> None:
-    """Assign physical frequencies to each of the swept spectral components."""
+def _fill_frequencies(
+    frequencies: npt.NDArray[np.float32],
+    center_frequencies: npt.NDArray[np.float32],
+    baseband_frequencies: npt.NDArray[np.float32],
+    window_size: int
+) -> None:
+    """Assign physical frequencies to each of the spectral components in the stitched spectrum."""
     for i, center_frequency in enumerate(np.unique(center_frequencies)):
         lower_bound = i * window_size
         upper_bound = (i + 1) * window_size
         frequencies[lower_bound:upper_bound] = (baseband_frequencies + center_frequency)
 
 
-def _fill_stepped_dynamic_spectra(stepped_dynamic_spectra: np.ndarray,
-                                  sft: ShortTimeFFT,
-                                  iq_data: np.ndarray,
-                                  num_samples: np.ndarray,
-                                  num_full_sweeps: int,
-                                  num_steps_per_sweep: int) -> None:
-    """Compute the dynamic spectra for the input IQ samples for each step.
-    
-    All IQ samples per step were collected at the same center frequency.
+def _fill_stepped_dynamic_spectra(
+    stepped_dynamic_spectra: npt.NDArray[np.float32],
+    sft: ShortTimeFFT,
+    iq_data: npt.NDArray[np.complex64],
+    num_samples: npt.NDArray[np.int32],
+    num_full_sweeps: int,
+    num_steps_per_sweep: int
+) -> None:
+    """For each full sweep, compute the dynamic spectra by performing a Short-time Fast Fourier Transform
+    on the IQ samples within each step.
     """
     # global_step_index will hold the step index over all sweeps (doesn't reset each sweep)
     # start_sample_index will hold the index of the first sample in the step
@@ -87,8 +94,8 @@ def _fill_stepped_dynamic_spectra(stepped_dynamic_spectra: np.ndarray,
             num_slices = sft.upper_border_begin(num_samples[global_step_index])[1]
             # perform a short time fast fourier transform on the step
             complex_spectra = sft.stft(iq_data[start_sample_index:end_sample_index], 
-                                            p0=0, 
-                                            p1=num_slices)
+                                       p0=0, 
+                                       p1=num_slices)
             # and pack the absolute values into the stepped spectrogram where the step slot is padded to the maximum size for ease of processing later)
             stepped_dynamic_spectra[sweep_index, step_index, :, :num_slices] = np.abs(complex_spectra)
             # reassign the start_sample_index for the next step
@@ -97,25 +104,31 @@ def _fill_stepped_dynamic_spectra(stepped_dynamic_spectra: np.ndarray,
             global_step_index += 1
         
 
-def _compute_num_max_slices_in_step(sft: ShortTimeFFT,
-                                    num_samples: np.ndarray) -> int:
-    """Compute the maximum number of slices over all steps, in all sweeps over the batch."""
+def _compute_num_max_slices_in_step(
+    sft: ShortTimeFFT,
+    num_samples: npt.NDArray[np.int32]
+) -> int:
+    """Compute the maximum number of slices over all steps (and all sweeps) in the batch."""
     return sft.upper_border_begin(np.max(num_samples))[1]
 
 
-def _compute_num_full_sweeps(center_frequencies: np.ndarray) -> int:
-    """Compute the total number of full sweeps over the batch.
+def _compute_num_full_sweeps(
+    center_frequencies: npt.NDArray[np.float32]
+) -> int:
+    """Compute the total number of full sweeps in the batch.
 
     Since the number of each samples in each step is variable, we only know a sweep is complete
     when there is a sweep after it. So we can define the total number of *full* sweeps as the number of 
     (freq_max, freq_min) pairs in center_frequencies. It is only at an instance of (freq_max, freq_min) pair 
     in center frequencies that the frequency decreases, so, we can compute the number of full sweeps by 
-    counting the numbers of negative values in np.diff(center_frequencies)
+    counting the numbers of negative values in np.diff(center_frequencies).
     """
     return len(np.where(np.diff(center_frequencies) < 0)[0])
 
 
-def _compute_num_steps_per_sweep(center_frequencies: np.ndarray) -> int:
+def _compute_num_steps_per_sweep(
+    center_frequencies: npt.NDArray[np.float32]
+) -> int:
     """Compute the (ensured constant) number of steps in each sweep."""
     # find the (step) indices corresponding to the minimum frequencies
     min_freq_indices = np.where(center_frequencies == np.min(center_frequencies))[0]
@@ -128,9 +141,11 @@ def _compute_num_steps_per_sweep(center_frequencies: np.ndarray) -> int:
     return int(unique_num_steps_per_sweep[0])
 
 
-def _validate_center_frequencies_ordering(center_frequencies: np.ndarray,
-                                          freq_step: float) -> None:
-    """Check that the center frequencies are well-ordered in the detached header"""
+def _validate_center_frequencies_ordering(
+    center_frequencies: npt.NDArray[np.float32],
+    freq_step: float
+) -> None:
+    """Check that the center frequencies are well-ordered in the detached header."""
     min_frequency = np.min(center_frequencies)
     # Extract the expected difference between each step within a sweep. 
     for i, diff in enumerate(np.diff(center_frequencies)):
@@ -139,48 +154,60 @@ def _validate_center_frequencies_ordering(center_frequencies: np.ndarray,
             raise InvalidSweepMetadataError(f"Unordered center frequencies detected")
 
 
-def _do_stfft(iq_data: np.ndarray,
-              sweep_metadata: SweepMetadata,
-              capture_config: CaptureConfig):
-    """Perform a Short Time FFT on the input swept IQ samples."""
+def _do_stfft(
+    iq_data: npt.NDArray[np.complex64],
+    center_frequencies: npt.NDArray[np.float32],
+    num_samples: npt.NDArray[np.int32],
+    capture_config: CaptureConfig
+) -> Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32], npt.NDArray[np.float32]]:
+    """Do a Short-time Fast Fourier Transform on an array of complex IQ samples.
+    
+    The computation requires extra metadata, which is extracted from the detached header in the batch 
+    and the capture config used to capture the data. 
+    
+    The current implementation relies heavily on the `ShortTimeFFT` implementation from 
+    `scipy.signal` (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.ShortTimeFFT.html)
+    which takes up a lot of the compute time.
+    """
 
     sft = make_sft_instance(capture_config)
 
-    frequency_step = capture_config.get_parameter_value(PNames.FREQUENCY_STEP)
-    _validate_center_frequencies_ordering(sweep_metadata.center_frequencies,
+    frequency_step = cast(float, capture_config.get_parameter_value(PName.FREQUENCY_STEP))
+    _validate_center_frequencies_ordering(center_frequencies,
                                           frequency_step)
 
-    window_size = capture_config.get_parameter_value(PNames.WINDOW_SIZE)
-
-    num_steps_per_sweep = _compute_num_steps_per_sweep(sweep_metadata.center_frequencies)
-    num_full_sweeps = _compute_num_full_sweeps(sweep_metadata.center_frequencies)
+    num_steps_per_sweep    = _compute_num_steps_per_sweep(center_frequencies)
+    num_full_sweeps        = _compute_num_full_sweeps(center_frequencies)
     num_max_slices_in_step = _compute_num_max_slices_in_step(sft,
-                                                             sweep_metadata.num_samples)
+                                                             num_samples)
     
+    window_size = cast(int, capture_config.get_parameter_value(PName.WINDOW_SIZE))
     stepped_dynamic_spectra_shape = (num_full_sweeps, 
                                      num_steps_per_sweep, 
                                      window_size, 
                                      num_max_slices_in_step)
-    stepped_dynamic_spectra = np.full(stepped_dynamic_spectra_shape, np.nan)
-
-    frequencies = np.empty(num_steps_per_sweep * window_size)
-    times = np.empty(num_full_sweeps)
+    
+    # pad with nan values up to the max number of slices to make computations simpler.
+    # nans are required, so that they are easily ignored, e.g. in averaging operations.
+    stepped_dynamic_spectra = np.full(stepped_dynamic_spectra_shape, np.nan, dtype=np.float32)
+    frequencies             = np.empty(num_steps_per_sweep * window_size, dtype=np.float32)
+    times                   = np.empty(num_full_sweeps, dtype=np.float32)
 
     _fill_stepped_dynamic_spectra(stepped_dynamic_spectra,
                                   sft,
                                   iq_data,
-                                  sweep_metadata.num_samples,
+                                  num_samples,
                                   num_full_sweeps,
                                   num_steps_per_sweep)
     
     _fill_frequencies(frequencies,
-                      sweep_metadata.center_frequencies,
+                      center_frequencies,
                       sft.f,
                       window_size)
     
-    sample_rate = capture_config.get_parameter_value(PNames.SAMPLE_RATE)
+    sample_rate = cast(int, capture_config.get_parameter_value(PName.SAMPLE_RATE))
     _fill_times(times,
-                sweep_metadata.num_samples,
+                num_samples,
                 sample_rate,
                 num_full_sweeps,
                 num_steps_per_sweep)
@@ -192,10 +219,13 @@ def _do_stfft(iq_data: np.ndarray,
     return times, frequencies, dynamic_spectra
 
 
-def _prepend_num_samples(carryover_num_samples: np.ndarray,
-                         num_samples: np.ndarray,
-                         final_step_spans_two_batches: bool) -> np.ndarray:
-    """Prepend the number of samples from the final sweep of the previous batch."""
+def _prepend_num_samples(
+    carryover_num_samples: npt.NDArray[np.int32],
+    num_samples: npt.NDArray[np.int32],
+    final_step_spans_two_batches: bool
+) -> npt.NDArray[np.int32]:
+    """Prepend the number of samples from the final sweep of the previous batch, to the first
+    sweep of the current batch."""
     if final_step_spans_two_batches:
         # ensure the number of samples from the final step in the previous batch are accounted for
         num_samples[0] += carryover_num_samples[-1]
@@ -204,10 +234,13 @@ def _prepend_num_samples(carryover_num_samples: np.ndarray,
     return np.concatenate((carryover_num_samples, num_samples))
 
 
-def _prepend_center_frequencies(carryover_center_frequencies: np.ndarray,
-                                center_frequencies: np.ndarray,
-                                final_step_spans_two_batches: bool)-> np.ndarray:
-    """Prepend the center frequencies from the final sweep of the previous batch."""
+def _prepend_center_frequencies(
+    carryover_center_frequencies: npt.NDArray[np.float32],
+    center_frequencies: npt.NDArray[np.float32],
+    final_step_spans_two_batches: bool
+)-> npt.NDArray[np.float32]:
+    """Prepend the center frequencies from the final sweep of the previous batch, to the first
+    sweep of the current batch."""
     # in the case that the sweep has bled across batches,
     # do not permit identical neighbours in the center frequency array
     if final_step_spans_two_batches:
@@ -216,134 +249,175 @@ def _prepend_center_frequencies(carryover_center_frequencies: np.ndarray,
     return np.concatenate((carryover_center_frequencies, center_frequencies))
 
 
-def _prepend_iq_data(carryover_iq_data: np.ndarray,
-                     iq_data: np.ndarray) -> np.ndarray:
-    """Prepend the IQ samples from the final sweep of the previous batch."""
+def _prepend_iq_data(
+    carryover_iq_data: npt.NDArray[np.complex64],
+    iq_data: npt.NDArray[np.complex64]
+) -> npt.NDArray[np.complex64]:
+    """Prepend the IQ samples from the final sweep of the previous batch, to the first sweep
+    of the current batch."""
     return np.concatenate((carryover_iq_data, iq_data))
 
 
-def _get_final_sweep(previous_batch: BaseBatch
-) -> Tuple[np.ndarray, SweepMetadata]:
-    """Get data from the final sweep of the previous batch."""
-    # unpack the data from the previous batch
-    previous_iq_data = previous_batch.read_file("bin")
-    _, previous_sweep_metadata = previous_batch.read_file("hdr")
+def _get_final_sweep(
+    previous_batch: IQStreamBatch
+) -> Tuple[npt.NDArray[np.complex64], npt.NDArray[np.float32], npt.NDArray[np.int32]]:
+    """Get IQ samples and metadata from the final sweep of the previous batch."""
+    
+    # unpack the data from the previous batch (using the cached values!)
+    previous_iq_data     = previous_batch.bin_file.read()
+    previous_iq_metadata = previous_batch.hdr_file.read()
+    
+    if previous_iq_metadata.center_frequencies is None or previous_iq_metadata.num_samples is None:
+        raise ValueError(f"Expected non-empty IQ metadata!")
+    
     # find the step index from the last sweep
     # [0] since the return of np.where is a 1 element Tuple, 
     # containing a list of step indices corresponding to the smallest center frequencies
     # [-1] since we want the final step index, where the center frequency is minimised
-    final_sweep_start_step_index = np.where(previous_sweep_metadata.center_frequencies == np.min(previous_sweep_metadata.center_frequencies))[0][-1]
+    final_sweep_start_step_index = np.where(previous_iq_metadata.center_frequencies == np.min(previous_iq_metadata.center_frequencies))[0][-1]
     # isolate the data from the final sweep
-    final_center_frequencies = previous_sweep_metadata.center_frequencies[final_sweep_start_step_index:]
-    final_num_samples = previous_sweep_metadata.num_samples[final_sweep_start_step_index:]
+    final_center_frequencies = previous_iq_metadata.center_frequencies[final_sweep_start_step_index:]
+    final_num_samples = previous_iq_metadata.num_samples[final_sweep_start_step_index:]
     final_sweep_iq_data = previous_iq_data[-np.sum(final_num_samples):]
 
     # sanity check on the number of samples in the final sweep
     if len(final_sweep_iq_data) != np.sum(final_num_samples):
         raise ValueError((f"Unexpected error! Mismatch in sample count for the final sweep data."
-                            f"Expected {np.sum(final_num_samples)} based on sweep metadata, but found "
-                            f" {len(final_sweep_iq_data)} IQ samples in the final sweep"))
+                          f"Expected {np.sum(final_num_samples)} based on sweep metadata, but found "
+                          f" {len(final_sweep_iq_data)} IQ samples in the final sweep"))
     
-    return final_sweep_iq_data, SweepMetadata(final_center_frequencies, final_num_samples)
-
+    return final_sweep_iq_data, final_center_frequencies, final_num_samples
 
-def _reconstruct_initial_sweep(previous_batch: BaseBatch,
-                               iq_data: np.ndarray,
-                               sweep_metadata: SweepMetadata) -> Tuple[np.ndarray, SweepMetadata, int]:
-    """Reconstruct the initial sweep of the current batch, using data from the previous batch."""
 
+def _reconstruct_initial_sweep(
+    previous_batch: IQStreamBatch,
+    batch: IQStreamBatch
+) -> Tuple[npt.NDArray[np.complex64], npt.NDArray[np.float32], npt.NDArray[np.int32], int]:
+    """Reconstruct the initial sweep of the current batch, using data from the previous batch.
+    
+    Specifically, we extract the data from the final sweep of the previous batch and prepend
+    it to the first sweep of the current batch. Additionally, we return how many IQ samples
+    we prepended, which will allow us to correct the spectrogram start time of the current batch.
+    """
+    
+    iq_data     = batch.bin_file.read()
+    iq_metadata = batch.hdr_file.read()
+    
+    if iq_metadata.center_frequencies is None or iq_metadata.num_samples is None:
+        raise ValueError(f"Expected non-empty IQ metadata!")
+    
     # carryover the final sweep of the previous batch, and prepend that data to the current batch data
-    carryover_iq_data, carryover_sweep_metadata = _get_final_sweep(previous_batch)
+    carryover_iq_data, carryover_center_frequencies, carryover_num_samples = _get_final_sweep(previous_batch)
 
     # prepend the iq data that was carried over from the previous batch
     iq_data = _prepend_iq_data(carryover_iq_data,
                                iq_data)
     
     # prepend the sweep metadata from the previous batch
-    final_step_spans_two_batches = carryover_sweep_metadata.center_frequencies[-1] == sweep_metadata.center_frequencies[0]
-    center_frequencies = _prepend_center_frequencies(carryover_sweep_metadata.center_frequencies,
-                                                     sweep_metadata.center_frequencies,
+    final_step_spans_two_batches = carryover_center_frequencies[-1] == iq_metadata.center_frequencies[0]
+    center_frequencies = _prepend_center_frequencies(carryover_center_frequencies,
+                                                     iq_metadata.center_frequencies,
                                                      final_step_spans_two_batches)
-    num_samples = _prepend_num_samples(carryover_sweep_metadata.num_samples,
-                                       sweep_metadata.num_samples,
+    num_samples = _prepend_num_samples(carryover_num_samples,
+                                       iq_metadata.num_samples,
                                        final_step_spans_two_batches)
     
     # keep track of how many samples we prepended (required to adjust timing later)
-    num_samples_prepended = np.sum(carryover_sweep_metadata.num_samples)
-    return iq_data, SweepMetadata(center_frequencies, num_samples), num_samples_prepended
-
-
-def _build_spectrogram(batch: BaseBatch,
-                       capture_config: CaptureConfig,
-                       previous_batch: Optional[BaseBatch] = None) -> Spectrogram:
-    """Create a spectrogram by performing a Short Time FFT on the (swept) IQ samples for this batch."""
-    iq_data = batch.read_file("bin")
-    millisecond_correction, sweep_metadata = batch.read_file("hdr")
+    num_samples_prepended = int(np.sum(carryover_num_samples))
+    return (iq_data, center_frequencies, num_samples, num_samples_prepended)
+
+
+def _build_spectrogram(
+    batch: IQStreamBatch,
+    capture_config: CaptureConfig,
+    previous_batch: Optional[IQStreamBatch] = None
+) -> Spectrogram:
+    """Generate a spectrogram using `IQStreamBatch` IQ samples."""
+    # read the batch files.
+    iq_data     = batch.bin_file.read()
+    iq_metadata = batch.hdr_file.read()
+    
+    # extract the center frequencies and num samples
+    center_frequencies, num_samples = iq_metadata.center_frequencies, iq_metadata.num_samples
+    
+    if center_frequencies is None or num_samples is None:
+        raise ValueError(f"An unexpected error has occured, expected frequency tag metadata "
+                         f"in the detached header.")
     
     # correct the batch start datetime with the millisecond correction stored in the detached header
-    spectrogram_start_datetime = batch.start_datetime + timedelta(milliseconds=millisecond_correction)
+    spectrogram_start_datetime = batch.start_datetime + timedelta(milliseconds=iq_metadata.millisecond_correction)
 
     # if a previous batch has been specified, this indicates that the initial sweep spans between two adjacent batched files. 
     if previous_batch:
         # If this is the case, first reconstruct the initial sweep of the current batch
         # by prepending the final sweep of the previous batch
-        iq_data, sweep_metadata, num_samples_prepended = _reconstruct_initial_sweep(previous_batch,
-                                                                                    iq_data,
-                                                                                    sweep_metadata)
+        iq_data, center_frequencies, num_samples, num_samples_prepended = _reconstruct_initial_sweep(previous_batch,
+                                                                                                     batch)
         
         # since we have prepended extra samples, we need to correct the spectrogram start time appropriately
-        elapsed_time = num_samples_prepended * (1 / capture_config.get_parameter_value(PNames.SAMPLE_RATE))
+        sample_rate = cast(int, capture_config.get_parameter_value(PName.SAMPLE_RATE))
+        elapsed_time = num_samples_prepended * (1 / sample_rate)
         spectrogram_start_datetime -= timedelta(seconds = float(elapsed_time))
     
 
 
     times, frequencies, dynamic_spectra = _do_stfft(iq_data, 
-                                                    sweep_metadata,
+                                                    center_frequencies,
+                                                    num_samples,
                                                     capture_config)
     
     return Spectrogram(dynamic_spectra,
                        times,
                        frequencies,
                        batch.tag,
-                       spectrogram_start_datetime,
-                       spectrum_type = "amplitude")
+                       SpectrumUnit.AMPLITUDE,
+                       spectrogram_start_datetime)
 
 
-@register_event_handler(CaptureModes.SWEPT_CENTER_FREQUENCY)
-class _EventHandler(BaseEventHandler):
-    def __init__(self, *args, **kwargs):
+@register_event_handler(EventHandlerKey.SWEPT_CENTER_FREQUENCY)
+class SweptEventHandler(BaseEventHandler):
+    def __init__(
+        self, 
+        *args, 
+        **kwargs
+    ) -> None:
         super().__init__(*args, **kwargs)
-
-        # the previous batch is stored in order to fetch the
-        # data from the "final sweep" which was ignored during
-        # processing.
-        self._previous_batch: BaseBatch = None 
+        self._previous_batch: Optional[IQStreamBatch] = None 
         
-
-    def process(self, 
-                absolute_file_path: str):
+        
+    def process(
+        self, 
+        absolute_file_path: str
+    ) -> None:
+        """
+        Compute a spectrogram using IQ samples from an `IQStreamBatch`, cache the results, and save them in the
+        FITS format. The IQ samples are assumed to be collected at a center frequency periodically swept in
+        fixed increments. Neighbouring IQ samples collected at the same frequency constitute a "step." Neighbouring 
+        steps collected at incrementally increasing center frequencies form a "sweep." A new sweep begins when the 
+        center frequency resets to its minimum value.
+
+        The computed spectrogram is averaged in time and frequency based on user-configured settings in the capture 
+        config. The batch is cached after computation for use in subsequent processing steps.
+
+        :param absolute_file_path: The absolute path to the `.bin` file containing the IQ sample batch.
+        """
         _LOGGER.info(f"Processing: {absolute_file_path}")
         file_name = os.path.basename(absolute_file_path)
         # discard the extension
         base_file_name, _ = os.path.splitext(file_name)
         batch_start_time, tag = base_file_name.split('_')
-        batch = self._Batch(batch_start_time, tag)
-
-        # ensure that the file which has been created has the expected tag
-        if tag != self._tag:
-            raise RuntimeError(f"Received an unexpected tag! Expected '{self._tag}', "
-                               f"but a file has been created with tag '{tag}'")
+        batch = IQStreamBatch(batch_start_time, tag)
 
         _LOGGER.info("Creating spectrogram")
         spectrogram = _build_spectrogram(batch,
-                                        self._capture_config,
-                                        previous_batch = self._previous_batch)
+                                         self._capture_config,
+                                         previous_batch = self._previous_batch)
 
         spectrogram = time_average(spectrogram,
-                                   resolution = self._capture_config.get_parameter_value(PNames.TIME_RESOLUTION))
+                                   resolution = self._capture_config.get_parameter_value(PName.TIME_RESOLUTION))
 
         spectrogram = frequency_average(spectrogram,
-                                        resolution = self._capture_config.get_parameter_value(PNames.FREQUENCY_RESOLUTION))
+                                        resolution = self._capture_config.get_parameter_value(PName.FREQUENCY_RESOLUTION))
 
         self._cache_spectrogram(spectrogram)
 
@@ -355,13 +429,11 @@ class _EventHandler(BaseEventHandler):
             
         # otherwise the previous batch is defined (and by this point has already been processed)
         else:
-            bin_file = self._previous_batch.get_file('bin')
-            _LOGGER.info(f"Deleting {bin_file.file_path}")
-            bin_file.delete()
+            _LOGGER.info(f"Deleting {self._previous_batch.bin_file.file_path}")
+            self._previous_batch.bin_file.delete()
 
-            hdr_file = self._previous_batch.get_file('hdr')
-            _LOGGER.info(f"Deleting {hdr_file.file_path}")
-            hdr_file.delete()
+            _LOGGER.info(f"Deleting {self._previous_batch.hdr_file.file_path}")
+            self._previous_batch.hdr_file.delete()
 
             # and reassign the current batch to be used as the previous batch at the next call of this method
             self._previous_batch = batch

spectre_core/receivers/__init__.py

@@ -2,16 +2,19 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# register decorators take effect on import
-from .library._test import _Receiver
-from .library._rsp1a import _Receiver
-from .library._rspduo import _Receiver
+"""A vendor-neutral interface for collecting data from SDRs."""
+
+from .plugins._receiver_names import ReceiverName
+from .plugins._test import Test
+from .plugins._rsp1a import RSP1A
+from .plugins._rspduo import RSPduo
 
 from ._base import BaseReceiver
 from ._factory import get_receiver
-from ._register import list_all_receiver_names
-from ._spec_names import SpecNames
+from ._register import get_registered_receivers
+from ._spec_names import SpecName
 
 __all__ = [
-    "BaseReceiver", "get_receiver", "list_all_receiver_names", "SpecNames"
+    "Test", "RSP1A", "RSPduo", "BaseReceiver", "get_receiver", 
+    "get_registered_receivers", "SpecName", "ReceiverName"
 ]