spectre-core 0.0.22__py3-none-any.whl → 0.0.24__py3-none-any.whl

spectre_core/batches/plugins/_iq_stream.py

@@ -24,25 +24,23 @@ from .._register import register_batch
 @dataclass(frozen=True)
 class _BatchExtension:
     """Supported extensions for a `IQStreamBatch`.
-    
+
     :ivar FITS: Corresponds to the `.fits` file extension.
     :ivar BIN: Corresponds to the `.bin` file extension.
     :ivar HDR: Corresponds to the `.hdr` file extension.
     """
+
     FITS: str = "fits"
-    BIN : str = "bin"
-    HDR : str = "hdr"
-    
-    
+    BIN: str = "bin"
+    HDR: str = "hdr"
+
+
 class _BinFile(BatchFile[npt.NDArray[np.complex64]]):
-    """Stores complex IQ samples in the binary format, as produced by the `gr-spectre` 
+    """Stores complex IQ samples in the binary format, as produced by the `gr-spectre`
     OOT module block `batched_file_sink`.
     """
-    def __init__(
-        self, 
-        batch_parent_dir_path: str, 
-        batch_name: str
-    ) -> None:
+
+    def __init__(self, batch_parent_dir_path: str, batch_name: str) -> None:
         """Initialise a `_BinFile` instance.
 
         :param batch_parent_dir_path: The parent directory for the batch.
@@ -50,48 +48,46 @@ class _BinFile(BatchFile[npt.NDArray[np.complex64]]):
         """
         super().__init__(batch_parent_dir_path, batch_name, _BatchExtension.BIN)
 
-
-    def _read(
-        self
-    ) -> npt.NDArray[np.complex64]:
+    def _read(self) -> npt.NDArray[np.complex64]:
         """Reads the binary file and returns the stored complex IQ samples.
 
         :return: The raw 32-bit floats in the binary file, interpreted as 64-bit complex IQ samples.
         """
         with open(self.file_path, "rb") as fh:
             return np.fromfile(fh, dtype=np.complex64)
-    
+
 
 @dataclass
 class IQMetadata:
     """Represents metadata for IQ samples produced by the `gr-spectre` OOT module block `batched_file_sink`.
 
     :ivar millisecond_correction: The millisecond component of the batch start time.
-    :ivar center_frequencies: Center frequencies for each IQ sample, if the stream was frequency tagged. 
+    :ivar center_frequencies: Center frequencies for each IQ sample, if the stream was frequency tagged.
     None otherwise.
-    :ivar num_samples: Number of samples collected at each center frequency, if the stream was frequency 
+    :ivar num_samples: Number of samples collected at each center frequency, if the stream was frequency
     tagged. None otherwise.
     """
+
     millisecond_correction: int
     center_frequencies: Optional[npt.NDArray[np.float32]] = None
     num_samples: Optional[npt.NDArray[np.int32]] = None
-    
+
     def is_frequency_tagged(self) -> bool:
         """Check if the IQ metadata contains frequency tagging information.
 
         :return: True if frequency tagging information is present; False otherwise.
         """
         return (self.center_frequencies is not None) and (self.num_samples is not None)
-    
+
 
 class _HdrFile(BatchFile[IQMetadata]):
-    """Stores IQ sample metadata produced by the `gr-spectre` OOT module block `batched_file_sink`, used 
+    """Stores IQ sample metadata produced by the `gr-spectre` OOT module block `batched_file_sink`, used
     to help parse the corresponding `.bin` file.
 
     File Structure:
         - If frequency tagged:
             (`<millisecond_correction>`, `<freq_0>`, `<num_samples_0>`, `<freq_1>`, `<num_samples_1>`, ...)
-            All values are stored as 32-bit floats. 
+            All values are stored as 32-bit floats.
             - The first value is the millisecond component for the batch start time.
             - Subsequent tuples (`<freq_n>`, `<num_samples_n>`) indicate that `<num_samples_n>` samples were collected at `<freq_n>`.
         - If not frequency tagged:
@@ -100,11 +96,8 @@ class _HdrFile(BatchFile[IQMetadata]):
 
     This format enables mapping IQ samples in the binary file to their corresponding center frequencies, if applicable.
     """
-    def __init__(
-        self, 
-        parent_dir_path: str, 
-        base_file_name: str
-    ) -> None:
+
+    def __init__(self, parent_dir_path: str, base_file_name: str) -> None:
         """Initialise a `_HdrFile` instance.
 
         :param parent_dir_path: The parent directory for the batch.
@@ -112,44 +105,30 @@ class _HdrFile(BatchFile[IQMetadata]):
         """
         super().__init__(parent_dir_path, base_file_name, _BatchExtension.HDR)
 
-
-    def _read(
-        self
-    ) -> IQMetadata:
+    def _read(self) -> IQMetadata:
         """Parses the binary contents of the `.hdr` file to extract IQ sample metadata.
 
-        :return: An instance of `IQMetadata` containing the parsed metadata, including the millisecond correction 
+        :return: An instance of `IQMetadata` containing the parsed metadata, including the millisecond correction
         and, if applicable, frequency tagging details.
         """
-        hdr_contents           = self._extract_raw_contents()
+        hdr_contents = self._extract_raw_contents()
         millisecond_correction = self._get_millisecond_correction(hdr_contents)
         if hdr_contents.size == 1:
             return IQMetadata(millisecond_correction)
         else:
-            center_frequencies     = self._get_center_frequencies(hdr_contents)
-            num_samples            = self._get_num_samples(hdr_contents)
-            self._validate_frequencies_and_samples(center_frequencies, 
-                                                num_samples)
-            return IQMetadata(millisecond_correction, 
-                              center_frequencies, 
-                              num_samples)
-
+            center_frequencies = self._get_center_frequencies(hdr_contents)
+            num_samples = self._get_num_samples(hdr_contents)
+            self._validate_frequencies_and_samples(center_frequencies, num_samples)
+            return IQMetadata(millisecond_correction, center_frequencies, num_samples)
 
-
-    def _extract_raw_contents(
-        self
-    ) -> npt.NDArray[np.float32]:
+    def _extract_raw_contents(self) -> npt.NDArray[np.float32]:
         """Reads the raw contents of the `.hdr` file."""
         with open(self.file_path, "rb") as fh:
-            # the `batched_file_sink` block in the `gr-spectre` GNU Radio OOT module stores 
+            # the `batched_file_sink` block in the `gr-spectre` GNU Radio OOT module stores
             # the integral millisecond component as a 32-bit float.
             return np.fromfile(fh, dtype=np.float32)
 
-
-    def _get_millisecond_correction(
-        self, 
-        hdr_contents: npt.NDArray[np.float32]
-    ) -> int:
+    def _get_millisecond_correction(self, hdr_contents: npt.NDArray[np.float32]) -> int:
         """Extracts and validates the millisecond component of the batch start time.
 
         The value is stored as a 32-bit float but interpreted as an integer.
@@ -157,14 +136,14 @@ class _HdrFile(BatchFile[IQMetadata]):
         millisecond_correction = float(hdr_contents[0])
 
         if not millisecond_correction.is_integer():
-            raise TypeError(f"Expected integer value for millisecond correction, but got {millisecond_correction}")
-        
+            raise TypeError(
+                f"Expected integer value for millisecond correction, but got {millisecond_correction}"
+            )
+
         return int(millisecond_correction)
-        
 
     def _get_center_frequencies(
-        self, 
-        hdr_contents: npt.NDArray[np.float32]
+        self, hdr_contents: npt.NDArray[np.float32]
     ) -> npt.NDArray[np.float32]:
         """Extracts the center frequencies from the `.hdr` file contents.
 
@@ -172,182 +151,139 @@ class _HdrFile(BatchFile[IQMetadata]):
         """
         return hdr_contents[1::2]
 
-
     def _get_num_samples(
-        self, 
-        hdr_contents: npt.NDArray[np.float32]
+        self, hdr_contents: npt.NDArray[np.float32]
     ) -> npt.NDArray[np.int32]:
         """Extracts the number of samples per frequency from the `.hdr` file contents.
 
-        The values are stored as 32-bit floats but are interpreted as integers. 
-        Sample counts are located at every second entry, starting from the second index. 
+        The values are stored as 32-bit floats but are interpreted as integers.
+        Sample counts are located at every second entry, starting from the second index.
         """
         num_samples_as_float = hdr_contents[2::2]
         if not all(num_samples_as_float == num_samples_as_float.astype(int)):
-            raise InvalidSweepMetadataError("Number of samples per frequency is expected to describe an integer")
+            raise InvalidSweepMetadataError(
+                "Number of samples per frequency is expected to describe an integer"
+            )
         return num_samples_as_float.astype(np.int32)
 
-
     def _validate_frequencies_and_samples(
-        self, 
-        center_frequencies: npt.NDArray[np.float32], 
-        num_samples: npt.NDArray[np.int32]
+        self,
+        center_frequencies: npt.NDArray[np.float32],
+        num_samples: npt.NDArray[np.int32],
     ) -> None:
         """Ensures that each center frequency has a corresponding sample count."""
         if len(center_frequencies) != len(num_samples):
-            raise InvalidSweepMetadataError("Center frequencies and number of samples arrays are not the same length")
+            raise InvalidSweepMetadataError(
+                "Center frequencies and number of samples arrays are not the same length"
+            )
 
 
 class _FitsFile(BatchFile[Spectrogram]):
     """Stores spectrogram data in the FITS file format, as generated by `spectre` from a stream of IQ samples."""
-    def __init__(
-        self, 
-        parent_dir_path: str, 
-        base_file_name: str
-    ) -> None:
+
+    def __init__(self, parent_dir_path: str, base_file_name: str) -> None:
         """Initialise a `_FitsFile` instance.
 
         :param parent_dir_path: The parent directory for the batch.
         :param base_file_name: The batch name.
         """
         super().__init__(parent_dir_path, base_file_name, _BatchExtension.FITS)
-           
 
-    def _read(
-        self
-    ) -> Spectrogram:
+    def _read(self) -> Spectrogram:
         """Read the FITS file and create a spectrogram.
 
         :return: A `Spectrogram` instance containing the parsed FITS file data.
         """
-        with fits.open(self.file_path, mode='readonly') as hdulist:
-            primary_hdu                = self._get_primary_hdu(hdulist)
-            dynamic_spectra            = self._get_dynamic_spectra(primary_hdu)
-            bunit                      = self._get_bunit(primary_hdu)
-            spectrogram_start_datetime = self._get_spectrogram_start_datetime(primary_hdu)
-            bintable_hdu               = self._get_bintable_hdu(hdulist)
-            times                      = self._get_times(bintable_hdu)
-            frequencies                = self._get_frequencies(bintable_hdu)
-            
+        with fits.open(self.file_path, mode="readonly") as hdulist:
+            primary_hdu = self._get_primary_hdu(hdulist)
+            dynamic_spectra = self._get_dynamic_spectra(primary_hdu)
+            bunit = self._get_bunit(primary_hdu)
+            spectrogram_start_datetime = self._get_spectrogram_start_datetime(
+                primary_hdu
+            )
+            bintable_hdu = self._get_bintable_hdu(hdulist)
+            times = self._get_times(bintable_hdu)
+            frequencies = self._get_frequencies(bintable_hdu)
+
         # bunit is interpreted as a SpectrumUnit.
         spectrum_unit = SpectrumUnit(bunit)
-        return Spectrogram(dynamic_spectra, 
-                           times, 
-                           frequencies, 
-                           self.tag,
-                           spectrum_unit,
-                           spectrogram_start_datetime)
-
-
-    def _get_primary_hdu(
-        self, 
-        hdulist: HDUList
-    ) -> PrimaryHDU:
-        return hdulist['PRIMARY']
-
-
-    def _get_bintable_hdu(
-        self, 
-        hdulist: HDUList
-    ) -> BinTableHDU:
+        return Spectrogram(
+            dynamic_spectra,
+            times,
+            frequencies,
+            self.tag,
+            spectrum_unit,
+            spectrogram_start_datetime,
+        )
+
+    def _get_primary_hdu(self, hdulist: HDUList) -> PrimaryHDU:
+        return hdulist["PRIMARY"]
+
+    def _get_bintable_hdu(self, hdulist: HDUList) -> BinTableHDU:
         return hdulist[1]
-  
-  
-    def _get_bunit(
-        self, 
-        primary_hdu: PrimaryHDU
-    ) -> str:
+
+    def _get_bunit(self, primary_hdu: PrimaryHDU) -> str:
         """Get the units corresponding to the elements of the dynamic spectra."""
-        return primary_hdu.header['BUNIT']
-      
-    
-    def _get_dynamic_spectra(
-        self, 
-        primary_hdu: PrimaryHDU
-    ) -> npt.NDArray[np.float32]:
-        return primary_hdu.data
+        return primary_hdu.header["BUNIT"]
 
+    def _get_dynamic_spectra(self, primary_hdu: PrimaryHDU) -> npt.NDArray[np.float32]:
+        return primary_hdu.data
 
-    def _get_spectrogram_start_datetime(
-        self, 
-        primary_hdu: PrimaryHDU
-    ) -> datetime:
+    def _get_spectrogram_start_datetime(self, primary_hdu: PrimaryHDU) -> datetime:
         """Get the start time of the spectrogram, up to the full precision available."""
-        date_obs = primary_hdu.header['DATE-OBS']
-        time_obs = primary_hdu.header['TIME-OBS']
+        date_obs = primary_hdu.header["DATE-OBS"]
+        time_obs = primary_hdu.header["TIME-OBS"]
         return datetime.strptime(f"{date_obs}T{time_obs}", TimeFormat.PRECISE_DATETIME)
 
-
-    def _get_times(
-        self, 
-        bintable_hdu: BinTableHDU
-    ) -> npt.NDArray[np.float32]:
+    def _get_times(self, bintable_hdu: BinTableHDU) -> npt.NDArray[np.float32]:
         """Extracts the elapsed times for each spectrum in seconds, with the first spectrum set to t=0
         by convention.
         """
-        return bintable_hdu.data['TIME'][0] # already in seconds
-
+        return bintable_hdu.data["TIME"][0]  # already in seconds
 
-    def _get_frequencies(
-        self,
-        bintable_hdu: BinTableHDU
-    ) -> npt.NDArray[np.float32]:
+    def _get_frequencies(self, bintable_hdu: BinTableHDU) -> npt.NDArray[np.float32]:
         """Extracts the frequencies for each spectral component."""
-        frequencies_MHz = bintable_hdu.data['FREQUENCY'][0]
-        return frequencies_MHz * 1e6 # convert to Hz
-    
- 
+        frequencies_MHz = bintable_hdu.data["FREQUENCY"][0]
+        return frequencies_MHz * 1e6  # convert to Hz
+
+
 @register_batch(BatchKey.IQ_STREAM)
 class IQStreamBatch(BaseBatch):
     """A batch of data derived from a stream of IQ samples from some receiver.
-    
+
     Supports the following extensions:
     - `.fits` (via the `spectrogram_file` attribute)
     - `.bin` (via the `bin_file` attribute)
     - `.hdr` (via the `hdr_file` attribute)
     """
-    def __init__(
-        self,
-        start_time: str,
-        tag: str
-    ) -> None:
-        """Initialise a `IQStreamBatch` instance.   
+
+    def __init__(self, start_time: str, tag: str) -> None:
+        """Initialise a `IQStreamBatch` instance.
 
         :param start_time: The start time of the batch.
         :param tag: The batch name tag.
         """
-        super().__init__(start_time, tag) 
+        super().__init__(start_time, tag)
         self._fits_file = _FitsFile(self.parent_dir_path, self.name)
-        self._bin_file  = _BinFile (self.parent_dir_path, self.name)
-        self._hdr_file  = _HdrFile (self.parent_dir_path, self.name)
-        
+        self._bin_file = _BinFile(self.parent_dir_path, self.name)
+        self._hdr_file = _HdrFile(self.parent_dir_path, self.name)
+
         # add files formally to the batch
-        self.add_file( self.spectrogram_file )
-        self.add_file( self.bin_file )
-        self.add_file( self.hdr_file )
-    
+        self.add_file(self.spectrogram_file)
+        self.add_file(self.bin_file)
+        self.add_file(self.hdr_file)
 
     @property
-    def spectrogram_file(
-        self
-    ) -> _FitsFile:
+    def spectrogram_file(self) -> _FitsFile:
         """The batch file corresponding to the `.fits` extension."""
         return self._fits_file
-    
-    
+
     @property
-    def bin_file(
-        self
-    ) -> _BinFile:
+    def bin_file(self) -> _BinFile:
         """The batch file corresponding to the `.bin` extension."""
         return self._bin_file
-    
-    
+
     @property
-    def hdr_file(
-        self
-    ) -> _HdrFile:
+    def hdr_file(self) -> _HdrFile:
         """The batch file corresponding to the `.hdr` extension."""
         return self._hdr_file
-    
-    

spectre_core/capture_configs/__init__.py

@@ -6,28 +6,57 @@
 
 from ._pnames import PName
 from ._capture_modes import CaptureMode
-from ._pvalidators  import (
-    validate_fixed_center_frequency, validate_non_overlapping_steps, validate_num_samples_per_step,
-    validate_num_steps_per_sweep, validate_nyquist_criterion, validate_step_interval, validate_sweep_interval,
-    validate_swept_center_frequency, validate_window, validate_sample_rate_with_master_clock_rate
+from ._pvalidators import (
+    validate_fixed_center_frequency,
+    validate_non_overlapping_steps,
+    validate_num_samples_per_step,
+    validate_num_steps_per_sweep,
+    validate_nyquist_criterion,
+    validate_step_interval,
+    validate_sweep_interval,
+    validate_swept_center_frequency,
+    validate_window,
+    validate_sample_rate_with_master_clock_rate,
 )
 from ._capture_config import CaptureConfig
 from ._ptemplates import PTemplate, get_base_ptemplate
-from ._parameters   import (
-    Parameter, Parameters, parse_string_parameters, make_parameters
-)
+from ._parameters import Parameter, Parameters, parse_string_parameters, make_parameters
 from ._capture_templates import (
-    CaptureTemplate, get_base_capture_template, make_base_capture_template
-)
-from ._pconstraints import (
-    BasePConstraint, EnforceSign, Bound, OneOf, PowerOfTwo
+    CaptureTemplate,
+    get_base_capture_template,
+    make_base_capture_template,
 )
+from ._pconstraints import BasePConstraint, EnforceSign, Bound, OneOf, PowerOfTwo
 
 __all__ = [
-    "PTemplate", "PValidator", "CaptureConfig", "Parameter", "Parameters", "parse_string_parameters",
-    "make_parameters", "CaptureTemplate", "CaptureMode", "get_base_capture_template", "make_base_capture_template"
-    "PConstraint", "PConstraint", "Bound", "OneOf", "EnforceSign", "PowerOfTwo", "make_base_capture_template", "PName",
-    "get_base_ptemplate", "BasePConstraint", "validate_fixed_center_frequency", "validate_non_overlapping_steps",
-    "validate_num_samples_per_step", "validate_num_steps_per_sweep", "validate_nyquist_criterion", "validate_step_interval",
-    "validate_sweep_interval", "validate_swept_center_frequency", "validate_window", "validate_sample_rate_with_master_clock_rate"
+    "PTemplate",
+    "PValidator",
+    "CaptureConfig",
+    "Parameter",
+    "Parameters",
+    "parse_string_parameters",
+    "make_parameters",
+    "CaptureTemplate",
+    "CaptureMode",
+    "get_base_capture_template",
+    "make_base_capture_template" "PConstraint",
+    "PConstraint",
+    "Bound",
+    "OneOf",
+    "EnforceSign",
+    "PowerOfTwo",
+    "make_base_capture_template",
+    "PName",
+    "get_base_ptemplate",
+    "BasePConstraint",
+    "validate_fixed_center_frequency",
+    "validate_non_overlapping_steps",
+    "validate_num_samples_per_step",
+    "validate_num_steps_per_sweep",
+    "validate_nyquist_criterion",
+    "validate_step_interval",
+    "validate_sweep_interval",
+    "validate_swept_center_frequency",
+    "validate_window",
+    "validate_sample_rate_with_master_clock_rate",
 ]

spectre_core/capture_configs/_capture_config.py

@@ -10,91 +10,69 @@ from spectre_core._file_io import JsonHandler
 from spectre_core.config import get_configs_dir_path
 from spectre_core.exceptions import InvalidTagError
 from ._ptemplates import PName
-from ._parameters import (
-    Parameter, 
-    Parameters,
-    make_parameters
-)
+from ._parameters import Parameter, Parameters, make_parameters
+
 
 @dataclass(frozen=True)
 class _CaptureConfigKey:
     """Defined JSON keys for capture configs.
-    
+
     :ivar RECEIVER_NAME: The name of the receiver used for capture.
     :ivar RECEIVER_MODE: The operating mode for the receiver to be used for capture.
     :ivar PARAMETERS: The user configured parameters given to the receiver at the time of capture.
     """
+
     RECEIVER_NAME = "receiver_name"
     RECEIVER_MODE = "receiver_mode"
-    PARAMETERS    = "parameters"
+    PARAMETERS = "parameters"
 
 
 class CaptureConfig(JsonHandler):
     """Simple IO interface for a capture configs under a particular tag."""
-    def __init__(
-        self,
-        tag: str
-    ) -> None:
+
+    def __init__(self, tag: str) -> None:
         """Initialise an instance of `CaptureConfig`.
 
         :param tag: The tag identifier for the capture config.
         """
         self._validate_tag(tag)
         self._tag = tag
-        super().__init__(get_configs_dir_path(),
-                         tag)
-        
+        super().__init__(get_configs_dir_path(), tag)
+
     @property
-    def tag(
-        self
-    ) -> str:
+    def tag(self) -> str:
         """The tag identifier for the capture config."""
         return self._tag
 
-
-    def _validate_tag(
-        self, 
-        tag: str
-    ) -> None:
+    def _validate_tag(self, tag: str) -> None:
         """Validate the tag of the capture config.
-        
+
         Some substrings are reserved for third-party spectrogram data.
         """
         if "callisto" in tag:
-            raise ValueError(f"The substring `callisto` is reserved, and is not allowed in a capture config tag.")
-    
+            raise ValueError(
+                f"The substring `callisto` is reserved, and is not allowed in a capture config tag."
+            )
 
     @property
-    def receiver_name(
-        self
-    ) -> str:
+    def receiver_name(self) -> str:
         """The name of the receiver to be used for capture."""
         d = self.read(cache=True)
         return d[_CaptureConfigKey.RECEIVER_NAME]
-    
 
     @property
-    def receiver_mode(
-        self
-    ) -> str:
+    def receiver_mode(self) -> str:
         """The operating mode for the receiver to be used for capture."""
         d = self.read(cache=True)
         return d[_CaptureConfigKey.RECEIVER_MODE]
-    
 
     @cached_property
-    def parameters(
-        self
-    ) -> Parameters:
+    def parameters(self) -> Parameters:
         """The user-configured parameters provided to the receiver at the time of capture."""
         d = self.read(cache=True)
-        return make_parameters( d[_CaptureConfigKey.PARAMETERS] )
-
+        return make_parameters(d[_CaptureConfigKey.PARAMETERS])
 
-    def get_parameter(
-        self, 
-        name: PName
-    ) -> Parameter:
+    def get_parameter(self, name: PName) -> Parameter:
         """Get a parameter stored by the capture config.
 
         :param name: The name of the parameter.
@@ -102,14 +80,10 @@ class CaptureConfig(JsonHandler):
                 configuration file.
         """
         return self.parameters.get_parameter(name)
-    
 
-    def get_parameter_value(
-        self,
-        name: PName
-    ) -> Optional[Any]:
+    def get_parameter_value(self, name: PName) -> Optional[Any]:
         """Get the value of a parameter stored by the capture config.
-        
+
         For static typing, should be `cast` after return according to the corresponding `PTemplate`.
 
         :param name: The name of the parameter.
@@ -118,13 +92,12 @@ class CaptureConfig(JsonHandler):
         """
         return self.parameters.get_parameter_value(name)
 
-
     def save_parameters(
         self,
         receiver_name: str,
         receiver_mode: str,
         parameters: Parameters,
-        force: bool = False
+        force: bool = False,
     ):
         """Write the input parameters to a capture config.
 
@@ -136,6 +109,6 @@ class CaptureConfig(JsonHandler):
         d = {
             _CaptureConfigKey.RECEIVER_MODE: receiver_mode,
             _CaptureConfigKey.RECEIVER_NAME: receiver_name,
-            _CaptureConfigKey.PARAMETERS   : parameters.to_dict()
+            _CaptureConfigKey.PARAMETERS: parameters.to_dict(),
         }
-        self.save(d, force=force)
+        self.save(d, force=force)