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

spectre_core/receivers/{gr → plugins/gr}/_rspduo.py

@@ -19,35 +19,30 @@
 from functools import partial
 from dataclasses import dataclass
 
-from gnuradio import gr
-from gnuradio import spectre
-from gnuradio import sdrplay3
-
-from spectre_core.capture_configs import Parameters, PNames
+from spectre_core.capture_configs import Parameters, PName
 from spectre_core.config import get_batches_dir_path
-from ._base import capture
-
-
-class _tuner_1_fixed_center_frequency(gr.top_block):
-    def __init__(self, 
-                 tag: str,
-                 parameters: Parameters):
-        gr.top_block.__init__(self, catch_exceptions=True)
-        gr.top_block.__init__(self, "tuner_1_fixed", catch_exceptions=True)
+from ._base import capture, spectre_top_block
+
+
+class _tuner_1_fixed_center_frequency(spectre_top_block):
+    def flowgraph(
+        self, 
+        tag: str,
+        parameters: Parameters
+    ) -> None:
+        # OOT Module inline imports 
+        from gnuradio import spectre
+        from gnuradio import sdrplay3
         
-        ##################################################
-        # Unpack capture config
-        ##################################################
-        sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-        batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
-        center_freq = parameters.get_parameter_value(PNames.CENTER_FREQUENCY)
-        bandwidth   = parameters.get_parameter_value(PNames.BANDWIDTH)
-        if_gain     = parameters.get_parameter_value(PNames.IF_GAIN)
-        rf_gain     = parameters.get_parameter_value(PNames.RF_GAIN)
-
-        ##################################################
+        # Unpack the capture config parameters
+        sample_rate = parameters.get_parameter_value(PName.SAMPLE_RATE)
+        batch_size  = parameters.get_parameter_value(PName.BATCH_SIZE)
+        center_freq = parameters.get_parameter_value(PName.CENTER_FREQUENCY)
+        bandwidth   = parameters.get_parameter_value(PName.BANDWIDTH)
+        if_gain     = parameters.get_parameter_value(PName.IF_GAIN)
+        rf_gain     = parameters.get_parameter_value(PName.RF_GAIN)
+
         # Blocks
-        ##################################################
         self.spectre_batched_file_sink_0 = spectre.batched_file_sink(get_batches_dir_path(), 
                                                                      tag, 
                                                                      batch_size, 
@@ -80,33 +75,29 @@ class _tuner_1_fixed_center_frequency(gr.top_block):
         self.sdrplay3_rspduo_0.set_sample_sequence_gaps_check(False)
         self.sdrplay3_rspduo_0.set_show_gain_changes(False)
 
-
-        ##################################################
         # Connections
-        ##################################################
         self.connect((self.sdrplay3_rspduo_0, 0), (self.spectre_batched_file_sink_0, 0))
     
         
-class _tuner_2_fixed_center_frequency(gr.top_block):
-    def __init__(self, 
-                 tag: str,
-                 parameters: Parameters):
-        gr.top_block.__init__(self, catch_exceptions=True)
-        gr.top_block.__init__(self, "tuner_1_fixed", catch_exceptions=True)
+class _tuner_2_fixed_center_frequency(spectre_top_block):
+    def flowgraph(
+        self, 
+        tag: str,
+        parameters: Parameters
+    ) -> None:
+        # OOT Module inline imports 
+        from gnuradio import spectre
+        from gnuradio import sdrplay3
         
-        ##################################################
-        # Unpack capture config
-        ##################################################
-        sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-        batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
-        center_freq = parameters.get_parameter_value(PNames.CENTER_FREQUENCY)
-        bandwidth   = parameters.get_parameter_value(PNames.BANDWIDTH)
-        if_gain     = parameters.get_parameter_value(PNames.IF_GAIN)
-        rf_gain     = parameters.get_parameter_value(PNames.RF_GAIN)
-
-        ##################################################
+        # Unpack the capture config parameters
+        sample_rate = parameters.get_parameter_value(PName.SAMPLE_RATE)
+        batch_size  = parameters.get_parameter_value(PName.BATCH_SIZE)
+        center_freq = parameters.get_parameter_value(PName.CENTER_FREQUENCY)
+        bandwidth   = parameters.get_parameter_value(PName.BANDWIDTH)
+        if_gain     = parameters.get_parameter_value(PName.IF_GAIN)
+        rf_gain     = parameters.get_parameter_value(PName.RF_GAIN)
+
         # Blocks
-        ##################################################
         self.spectre_batched_file_sink_0 = spectre.batched_file_sink(get_batches_dir_path(), 
                                                                      tag, 
                                                                      batch_size, 
@@ -141,34 +132,32 @@ class _tuner_2_fixed_center_frequency(gr.top_block):
         self.sdrplay3_rspduo_0.set_show_gain_changes(False)
 
 
-        ##################################################
         # Connections
-        ##################################################
         self.connect((self.sdrplay3_rspduo_0, 0), (self.spectre_batched_file_sink_0, 0))    
 
 
-class _tuner_1_swept_center_frequency(gr.top_block):
-    def __init__(self, 
-                 tag: str,
-                 parameters: Parameters):
-        gr.top_block.__init__(self, catch_exceptions=True)
-
-        ##################################################
-        # Unpack capture config
-        ##################################################
-        sample_rate      = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-        bandwidth        = parameters.get_parameter_value(PNames.BANDWIDTH)
-        min_frequency    = parameters.get_parameter_value(PNames.MIN_FREQUENCY)
-        max_frequency    = parameters.get_parameter_value(PNames.MAX_FREQUENCY)
-        frequency_step   = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
-        samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
-        if_gain          = parameters.get_parameter_value(PNames.IF_GAIN)
-        rf_gain          = parameters.get_parameter_value(PNames.RF_GAIN)
-        batch_size       = parameters.get_parameter_value(PNames.BATCH_SIZE)
-
-        ##################################################
+class _tuner_1_swept_center_frequency(spectre_top_block):
+    def flowgraph(
+        self, 
+        tag: str,
+        parameters: Parameters
+    ) -> None:
+        # OOT Module inline imports 
+        from gnuradio import spectre
+        from gnuradio import sdrplay3
+
+        # Unpack the capture config parameters
+        sample_rate      = parameters.get_parameter_value(PName.SAMPLE_RATE)
+        bandwidth        = parameters.get_parameter_value(PName.BANDWIDTH)
+        min_frequency    = parameters.get_parameter_value(PName.MIN_FREQUENCY)
+        max_frequency    = parameters.get_parameter_value(PName.MAX_FREQUENCY)
+        frequency_step   = parameters.get_parameter_value(PName.FREQUENCY_STEP)
+        samples_per_step = parameters.get_parameter_value(PName.SAMPLES_PER_STEP)
+        if_gain          = parameters.get_parameter_value(PName.IF_GAIN)
+        rf_gain          = parameters.get_parameter_value(PName.RF_GAIN)
+        batch_size       = parameters.get_parameter_value(PName.BATCH_SIZE)
+
         # Blocks
-        ##################################################
         self.spectre_sweep_driver_0 = spectre.sweep_driver(min_frequency, 
                                                            max_frequency, 
                                                            frequency_step, 
@@ -212,16 +201,14 @@ class _tuner_1_swept_center_frequency(gr.top_block):
         self.sdrplay3_rspduo_0.set_show_gain_changes(False)
 
 
-        ##################################################
         # Connections
-        ##################################################
         self.msg_connect((self.spectre_sweep_driver_0, 'freq'), (self.sdrplay3_rspduo_0, 'freq'))
         self.connect((self.sdrplay3_rspduo_0, 0), (self.spectre_batched_file_sink_0, 0))
         self.connect((self.sdrplay3_rspduo_0, 0), (self.spectre_sweep_driver_0, 0))
         
         
 @dataclass(frozen=True)
-class CaptureMethods:
+class CaptureMethod:
     tuner_1_fixed_center_frequency  = partial(capture, top_block_cls=_tuner_1_fixed_center_frequency)
     tuner_2_fixed_center_frequency  = partial(capture, top_block_cls=_tuner_2_fixed_center_frequency)
-    tuner_1_swept_center_frequency  = partial(capture, top_block_cls=_tuner_1_swept_center_frequency)
+    tuner_1_swept_center_frequency  = partial(capture, top_block_cls=_tuner_1_swept_center_frequency, max_noutput_items=1024)

spectre_core/receivers/{gr → plugins/gr}/_test.py

@@ -17,35 +17,34 @@
 #
 
 from functools import partial
+from typing import Callable
 from dataclasses import dataclass
 
 from gnuradio import gr
 from gnuradio import blocks
-from gnuradio import spectre
 from gnuradio import analog
 
-from spectre_core.capture_configs import Parameters, PNames
+from spectre_core.capture_configs import Parameters, PName
 from spectre_core.config import get_batches_dir_path
-from ._base import capture
+from ._base import capture, spectre_top_block
 
 
-class _cosine_signal_1(gr.top_block):
-    def __init__(self, 
-                 tag: str,
-                 parameters: Parameters):
-        gr.top_block.__init__(self, catch_exceptions=True)
+class _cosine_signal_1(spectre_top_block):
+    def flowgraph(
+        self, 
+        tag: str,
+        parameters: Parameters
+    ) -> None:
+        # Inline imports 
+        from gnuradio import spectre
 
-        ##################################################
-        # Unpack capture config
-        ##################################################
-        samp_rate   = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-        batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
-        frequency   = parameters.get_parameter_value(PNames.FREQUENCY)
-        amplitude   = parameters.get_parameter_value(PNames.AMPLITUDE)
+        # Unpack the capture config parameters
+        samp_rate   = parameters.get_parameter_value(PName.SAMPLE_RATE)
+        batch_size  = parameters.get_parameter_value(PName.BATCH_SIZE)
+        frequency   = parameters.get_parameter_value(PName.FREQUENCY)
+        amplitude   = parameters.get_parameter_value(PName.AMPLITUDE)
 
-        ##################################################
         # Blocks
-        ##################################################
         self.spectre_batched_file_sink_0 = spectre.batched_file_sink(get_batches_dir_path(), 
                                                                      tag, 
                                                                      batch_size, 
@@ -76,21 +75,24 @@ class _cosine_signal_1(gr.top_block):
         self.connect((self.blocks_throttle_0_1, 0), (self.blocks_float_to_complex_1, 1))
 
 
-class _tagged_staircase(gr.top_block):
-    def __init__(self, 
-                 tag: str,
-                 parameters: Parameters):
-        gr.top_block.__init__(self, catch_exceptions=True)
+class _tagged_staircase(spectre_top_block):
+    def flowgraph(
+        self, 
+        tag: str,
+        parameters: Parameters
+    ) -> None:
+        # Inline imports 
+        from gnuradio import spectre
 
         ##################################################
         # Unpack capture config
         ##################################################
-        step_increment       = parameters.get_parameter_value(PNames.STEP_INCREMENT)
-        samp_rate            = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-        min_samples_per_step = parameters.get_parameter_value(PNames.MIN_SAMPLES_PER_STEP)
-        max_samples_per_step = parameters.get_parameter_value(PNames.MAX_SAMPLES_PER_STEP)
-        frequency_step       = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
-        batch_size           = parameters.get_parameter_value(PNames.BATCH_SIZE)
+        step_increment       = parameters.get_parameter_value(PName.STEP_INCREMENT)
+        samp_rate            = parameters.get_parameter_value(PName.SAMPLE_RATE)
+        min_samples_per_step = parameters.get_parameter_value(PName.MIN_SAMPLES_PER_STEP)
+        max_samples_per_step = parameters.get_parameter_value(PName.MAX_SAMPLES_PER_STEP)
+        frequency_step       = parameters.get_parameter_value(PName.FREQUENCY_STEP)
+        batch_size           = parameters.get_parameter_value(PName.BATCH_SIZE)
 
         ##################################################
         # Blocks
@@ -118,6 +120,6 @@ class _tagged_staircase(gr.top_block):
 
 
 @dataclass(frozen=True)
-class CaptureMethods:
-    cosine_signal_1  = partial(capture, top_block_cls=_cosine_signal_1)
-    tagged_staircase = partial(capture, top_block_cls=_tagged_staircase)
+class CaptureMethod:
+    cosine_signal_1 : Callable[[str, Parameters], None] = partial(capture, top_block_cls=_cosine_signal_1)
+    tagged_staircase: Callable[[str, Parameters], None] = partial(capture, top_block_cls=_tagged_staircase)

spectre_core/spectrograms/__init__.py

@@ -2,11 +2,13 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+"""Create and transform spectrogram data."""
+
 from ._analytical import (
     get_analytical_spectrogram, validate_analytically, TestResults
 )
 from ._spectrogram import (
-    Spectrogram, FrequencyCut, TimeCut, SpectrumTypes, TimeTypes
+    Spectrogram, FrequencyCut, TimeCut, SpectrumUnit, TimeType
 )
 from ._transform import (
     frequency_chop, time_chop, frequency_average, time_average, 
@@ -15,7 +17,7 @@ from ._transform import (
 
 __all__ = [
     "get_analytical_spectrogram", "validate_analytically", "TestResults",
-    "Spectrogram", "FrequencyCut", "TimeCut", "SpectrumTypes", "frequency_chop",
+    "Spectrogram", "FrequencyCut", "TimeCut", "SpectrumUnit", "frequency_chop",
     "time_chop", "frequency_average","time_average", "join_spectrograms",
-    "TimeTypes"
+    "TimeType"
 ]

spectre_core/spectrograms/_analytical.py

@@ -1,96 +1,129 @@
+
 # SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Callable
-from dataclasses import dataclass
+from typing import Callable, cast
+from dataclasses import dataclass, field
 
 import numpy as np
 
-from spectre_core.capture_configs import CaptureConfig, PNames
+from spectre_core.capture_configs import CaptureConfig, PName
 from spectre_core.exceptions import ModeNotFoundError
-from ._spectrogram import Spectrogram
+from ._spectrogram import Spectrogram, SpectrumUnit
 from ._array_operations import is_close
 
 @dataclass
 class TestResults:
-    # Whether the times array matches analytically 
-    times_validated: bool = False  
-    # Whether the frequencies array matches analytically
-    frequencies_validated: bool = False  
-    # Maps each time to whether the corresponding spectrum matched analytically
-    spectrum_validated: dict[float, bool] = None
+    """
+    Summarise the validation results when comparing two spectrograms.
 
+    :ivar times_validated: Whether the time arrays match.
+    :ivar frequencies_validated: Whether the frequency arrays match.
+    :ivar spectrum_validated: Maps the relative time of each spectrum to its match results.
+    """
+    times_validated: bool = False
+    frequencies_validated: bool = False
+    spectrum_validated: dict[float, bool] = field(default_factory=dict)
 
     @property
-    def num_validated_spectrums(self) -> int:
-        """Counts the number of validated spectrums."""
+    def num_validated_spectrums(
+        self
+    ) -> int:
+        """Returns the count of spectrums that successfully passed validation."""
         return sum(is_validated for is_validated in self.spectrum_validated.values())
 
 
     @property
-    def num_invalid_spectrums(self) -> int:
-        """Counts the number of spectrums that are not validated."""
+    def num_invalid_spectrums(
+        self
+    ) -> int:
+        """Returns the count of spectrums that failed validation."""
         return len(self.spectrum_validated) - self.num_validated_spectrums
     
-
-    def to_dict(self) -> dict[str, bool | dict[float, bool]]:
+    
+    def to_dict(
+        self
+    ) -> dict[str, bool | dict[float, bool]]:
+        """Converts the instance into a serialisable dictionary."""
         return {
-            "times_validated": self.times_validated,
+            "times_validated"      : self.times_validated,
             "frequencies_validated": self.frequencies_validated,
-            "spectrum_validated": self.spectrum_validated
+            "spectrum_validated"   : self.spectrum_validated
         }
 
 
 class _AnalyticalFactory:
-    def __init__(self):
-        self._builders: dict[str, Callable] = {
-            "cosine-signal-1": self.cosine_signal_1,
-            "tagged-staircase": self.tagged_staircase
+    """Factory for creating analytical spectrograms."""
+    def __init__(
+        self
+    ) -> None:
+        """Initialises an instance of the `_AnalyticalFactory` class."""
+        self._builders: dict[str, Callable[[int, CaptureConfig], Spectrogram]] = {
+            "cosine_signal_1" : self._cosine_signal_1,
+            "tagged_staircase": self._tagged_staircase
         }
-        self._test_modes = list(self.builders.keys())
 
 
     @property
-    def builders(self) -> dict[str, Callable]:
+    def builders(
+        self
+    ) -> dict[str, Callable[[int, CaptureConfig], Spectrogram]]:
+        """
+        Provides a mapping from each `Test` receiver mode to its corresponding builder method.
+
+        Each builder method generates the expected spectrograms for a session run in the associated mode.
+        """
         return self._builders
     
 
     @property
-    def test_modes(self) -> list[str]:
-        return self._test_modes
+    def test_modes(
+        self
+    ) -> list[str]:
+        """Returns the available modes for the `Test` receiver."""
+        return list(self.builders.keys())
     
 
-    def get_spectrogram(self, 
-                        num_spectrums: int, 
-                        capture_config: CaptureConfig) -> Spectrogram:
-        """Get an analytical spectrogram based on a test receiver capture config.
-        
-        The anaytically derived spectrogram should be able to be fully determined
-        by parameters in the corresponding capture config and the number of spectrums
-        in the output spectrogram.
+    def get_spectrogram(
+        self, 
+        num_spectrums: int, 
+        capture_config: CaptureConfig
+    ) -> Spectrogram:
+        """
+        Generates an analytical spectrogram based on the capture config for a `Test` receiver.
+
+        :param num_spectrums: The number of spectrums to include in the output spectrogram.
+        :param capture_config: The capture config used for `Test` receiver data capture.
+        :raises ValueError: Raised if the capture config is not associated with a `Test` receiver.
+        :raises ModeNotFoundError: Raised if the specified `Test` mode in the capture config lacks
+        a corresponding builder method.
+        :return: The expected spectrogram for running a session with the `Test` receiver in the specified mode.
         """
-
         if capture_config.receiver_name != "test":
             raise ValueError(f"Input capture config must correspond to the test receiver")
         
         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 {capture_config.receiver_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)
     
 
-    def cosine_signal_1(self, 
-                        num_spectrums: int,
-                        capture_config: CaptureConfig) -> Spectrogram:
-        # Extract necessary parameters from the capture configuration.
-        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)
+    def _cosine_signal_1(
+        self, 
+        num_spectrums: int,
+        capture_config: CaptureConfig
+    ) -> Spectrogram:
+        """Creates the expected spectrogram for the `Test` receiver operating in the mode `cosine-signal-1`."""
+        # Extract necessary parameters from the capture config.
+        window_size      = cast(int,   capture_config.get_parameter_value(PName.WINDOW_SIZE))
+        sample_rate      = cast(int,   capture_config.get_parameter_value(PName.SAMPLE_RATE))
+        frequency        = cast(int,   capture_config.get_parameter_value(PName.FREQUENCY))
+        window_hop       = cast(int,   capture_config.get_parameter_value(PName.WINDOW_HOP))
+        amplitude        = cast(float, capture_config.get_parameter_value(PName.AMPLITUDE))
+        center_frequency = cast(float, capture_config.get_parameter_value(PName.CENTER_FREQUENCY))
+        
         # Calculate derived parameters a (sampling rate ratio) and p (sampled periods).
         a = int(sample_rate / frequency)
         p = int(window_size / a)
@@ -119,18 +152,21 @@ class _AnalyticalFactory:
                            times,
                            frequencies,
                            'analytically-derived-spectrogram',
-                           spectrum_type="amplitude")
-
-
-    def tagged_staircase(self, 
-                        num_spectrums: int,
-                        capture_config: CaptureConfig) -> Spectrogram:
-        # Extract necessary parameters from the capture configuration.
-        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)
+                           SpectrumUnit.AMPLITUDE)
+
+
+    def _tagged_staircase(
+        self, 
+        num_spectrums: int,
+        capture_config: CaptureConfig
+    ) -> Spectrogram:
+        """Creates the expected spectrogram for the `Test` receiver operating in the mode `tagged-staircase`."""
+        # Extract necessary parameters from the capture config.
+        window_size          = cast(int, capture_config.get_parameter_value(PName.WINDOW_SIZE))
+        min_samples_per_step = cast(int, capture_config.get_parameter_value(PName.MIN_SAMPLES_PER_STEP))
+        max_samples_per_step = cast(int, capture_config.get_parameter_value(PName.MAX_SAMPLES_PER_STEP))
+        step_increment       = cast(int, capture_config.get_parameter_value(PName.STEP_INCREMENT))
+        samp_rate            = cast(int, capture_config.get_parameter_value(PName.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)
@@ -156,7 +192,7 @@ class _AnalyticalFactory:
 
         # Compute the frequency array
         baseband_frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval))
-        frequencies = np.empty((window_size * num_steps))
+        frequencies = np.empty((window_size * num_steps), dtype=np.float32)
         for i in range(num_steps):
             lower_bound = i * window_size
             upper_bound = (i + 1) * window_size
@@ -167,25 +203,44 @@ class _AnalyticalFactory:
                            times,
                            frequencies,
                            'analytically-derived-spectrogram',
-                           spectrum_type="amplitude")
+                           SpectrumUnit.AMPLITUDE)
     
 
-def get_analytical_spectrogram(num_spectrums: int,
-                               capture_config: CaptureConfig) -> Spectrogram:
+def get_analytical_spectrogram(
+    num_spectrums: int,
+    capture_config: CaptureConfig
+) -> Spectrogram:
+    """Each mode of the `Test` receiver generates a known synthetic signal. Based on this, we can 
+    derive an analytical solution that predicts the expected spectrogram for a session in that mode. 
     
+    This function constructs the analytical spectrogram using the capture config for a `Test` 
+    receiver operating in a specific mode.
+
+    :param num_spectrums: The number of spectrums in the output spectrogram.
+    :param capture_config: The capture config used for data capture.
+    :return: The expected, analytically derived spectrogram for the specified mode of the `Test` receiver.
+    """
     factory = _AnalyticalFactory()
     return factory.get_spectrogram(num_spectrums,
                                    capture_config)
 
 
-def validate_analytically(spectrogram: Spectrogram,
-                          capture_config: CaptureConfig,
-                          absolute_tolerance: float) -> TestResults:
+def validate_analytically(
+    spectrogram: Spectrogram,
+    capture_config: CaptureConfig,
+    absolute_tolerance: float
+) -> TestResults:
+    """Validate a spectrogram generated during sessions with a `Test` receiver operating
+    in a particular mode.
 
+    :param spectrogram: The spectrogram to be validated.
+    :param capture_config: The capture config used for data capture.
+    :param absolute_tolerance: Tolerance level for numerical comparisons.
+    :return: A `TestResults` object summarising the validation outcome.
+    """
     analytical_spectrogram = get_analytical_spectrogram(spectrogram.num_times,
                                                         capture_config)
 
-
     test_results = TestResults()
 
     test_results.times_validated = bool(is_close(analytical_spectrogram.times,