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

spectre_core/chunks/library/_swept_center_frequency.py

@@ -0,0 +1,103 @@
+# 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 Tuple
+from dataclasses import dataclass
+
+import numpy as np
+
+from spectre_core.exceptions import InvalidSweepMetadataError
+from spectre_core.capture_configs import CaptureModes
+from ._fixed_center_frequency import BinChunk, FitsChunk
+from .._register import register_chunk
+from .._base import BaseChunk, ChunkFile
+
+
+@dataclass
+class SweepMetadata:
+    """Wrapper for metadata required to assign center frequencies to each IQ sample in the chunk.
+    
+    center_frequencies is an ordered list containing all the center frequencies that the IQ samples
+    were collected at. Typically, these will be ordered in "steps", where each step corresponds to
+    IQ samples collected at a constant center frequency:
+
+    (freq_0, freq_1, ..., freq_M, freq_0, freq_1, ..., freq_M, ...), freq_0 < freq_1 < ... < freq_M
+
+    The n'th element of the num_samples list, tells us how many samples were collected at the n'th
+    element of center_frequencies:
+chunks.library.fixed_center_frequency.chunk import (
+    BinChunk, FitsChunk
+)
+    Number of samples: (num_samples_at_freq_0, num_samples_at_freq_1, ...)
+
+    Both these lists together allow us to map for each IQ sample, the center frequency it was collected at.
+    """
+    center_frequencies: np.ndarray
+    num_samples: np.ndarray
+
+
+@register_chunk(CaptureModes.SWEPT_CENTER_FREQUENCY)
+class _Chunk(BaseChunk):
+    def __init__(self, chunk_start_time, tag):
+        super().__init__(chunk_start_time, tag)
+
+        self.add_file(BinChunk(self.chunk_parent_path, self.chunk_name))
+        self.add_file(FitsChunk(self.chunk_parent_path, self.chunk_name))
+        self.add_file(HdrChunk(self.chunk_parent_path, self.chunk_name))
+
+    
+class HdrChunk(ChunkFile):
+    def __init__(self, chunk_parent_path: str, chunk_name: str):
+        super().__init__(chunk_parent_path, chunk_name, "hdr")
+
+    def read(self) -> Tuple[int, SweepMetadata]:
+        hdr_contents = self._read_file_contents()
+        millisecond_correction = self._get_millisecond_correction(hdr_contents)
+        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 millisecond_correction, SweepMetadata(center_frequencies, num_samples)
+        
+
+    def _read_file_contents(self) -> np.ndarray:
+        with open(self.file_path, "rb") as fh:
+            return np.fromfile(fh, dtype=np.float32)
+
+
+    def _get_millisecond_correction(self, hdr_contents: np.ndarray) -> int:
+        ''' Millisecond correction is an integral quantity, but stored in the detached header as a 32-bit float.'''
+        millisecond_correction_as_float = float(hdr_contents[0])
+
+        if not millisecond_correction_as_float.is_integer():
+            raise TypeError(f"Expected integer value for millisecond correction, but got {millisecond_correction_as_float}")
+        
+        return int(millisecond_correction_as_float)
+
+
+    def _get_center_frequencies(self, hdr_contents: np.ndarray) -> np.ndarray:
+        ''' 
+        Detached header contents are stored in (center_freq_i, num_samples_at_center_freq_i) pairs
+        Return only a list of center frequencies, by skipping over file contents in twos.
+        '''
+        return hdr_contents[1::2]
+
+
+    def _get_num_samples(self, hdr_contents: np.ndarray) -> np.ndarray:
+        ''' 
+        Detached header contents are stored in (center_freq_i, num_samples_at_center_freq_i) pairs
+        Return only the number of samples at each center frequency, by skipping over file contents in twos.
+        Number of samples is an integral quantity, but stored in the detached header as a 32-bit float.
+        Types are checked before return.
+        '''
+        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")
+        return num_samples_as_float.astype(int)
+
+
+    def _validate_frequencies_and_samples(self, center_frequencies: np.ndarray, num_samples: np.ndarray) -> None:
+        """Validates that the center frequencies and the number of samples arrays have the same length."""
+        if len(center_frequencies) != len(num_samples):
+            raise InvalidSweepMetadataError("Center frequencies and number of samples arrays are not the same length")

spectre_core/config/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from ._paths import (
+    get_spectre_data_dir_path, get_chunks_dir_path, get_configs_dir_path, get_logs_dir_path
+)
+from ._time_formats import (
+    TimeFormats
+)
+
+__all__ = [
+    "get_spectre_data_dir_path",
+    "get_chunks_dir_path",
+    "get_configs_dir_path",
+    "get_logs_dir_path",
+    "DEFAULT_DATE_FORMAT",
+    "DEFAULT_TIME_FORMAT",
+    "DEFAULT_DATETIME_FORMAT"
+]

spectre_core/config/_paths.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+SPECTRE data paths.
+"""
+
+import os
+
+_SPECTRE_DATA_DIR_PATH = os.environ.get("SPECTRE_DATA_DIR_PATH")
+if _SPECTRE_DATA_DIR_PATH is None:
+    raise ValueError("The environment variable SPECTRE_DATA_DIR_PATH has not been set")
+
+_CHUNKS_DIR_PATH = os.environ.get("SPECTRE_CHUNKS_DIR_PATH", 
+                                  os.path.join(_SPECTRE_DATA_DIR_PATH, 'chunks'))
+os.makedirs(_CHUNKS_DIR_PATH, 
+            exist_ok=True)
+
+_LOGS_DIR_PATH = os.environ.get("SPECTRE_LOGS_DIR_PATH",
+                               os.path.join(_SPECTRE_DATA_DIR_PATH, 'logs'))
+os.makedirs(_LOGS_DIR_PATH, 
+            exist_ok=True)
+
+_CONFIGS_DIR_PATH = os.environ.get("SPECTRE_CONFIGS_DIR_PATH",
+                                  os.path.join(_SPECTRE_DATA_DIR_PATH, "configs"))
+os.makedirs(_CONFIGS_DIR_PATH, 
+            exist_ok=True)
+
+
+def get_spectre_data_dir_path(
+) -> str:
+    return _SPECTRE_DATA_DIR_PATH
+
+
+def _get_date_based_dir_path(base_dir: str, year: int = None, 
+                             month: int = None, day: int = None
+) -> str:
+    if day and not (year and month):
+        raise ValueError("A day requires both a month and a year")
+    if month and not year:
+        raise ValueError("A month requires a year")
+    
+    date_dir_components = []
+    if year:
+        date_dir_components.append(f"{year:04}")
+    if month:
+        date_dir_components.append(f"{month:02}")
+    if day:
+        date_dir_components.append(f"{day:02}")
+    
+    return os.path.join(base_dir, *date_dir_components)
+
+
+def get_chunks_dir_path(year: int = None, 
+                        month: int = None, 
+                        day: int = None
+) -> str:
+    return _get_date_based_dir_path(_CHUNKS_DIR_PATH, 
+                                    year, 
+                                    month, 
+                                    day)
+
+
+def get_logs_dir_path(year: int = None, 
+                      month: int = None, 
+                      day: int = None
+) -> str:
+    return _get_date_based_dir_path(_LOGS_DIR_PATH, 
+                                    year, 
+                                    month, 
+                                    day)
+
+
+def get_configs_dir_path(
+) -> str:
+    return _CONFIGS_DIR_PATH

spectre_core/config/_time_formats.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Package-wide default datetime formats.
+"""
+
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class TimeFormats:
+    TIME     = "%H:%M:%S"
+    DATE     = "%Y-%m-%d"
+    DATETIME = f"{DATE}T{TIME}"

spectre_core/exceptions.py

@@ -2,16 +2,15 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+"""
+SPECTRE custom exceptions.
+"""
+
 class ChunkNotFoundError(FileNotFoundError): ...
 class ChunkFileNotFoundError(FileNotFoundError): ...
 class SpectrogramNotFoundError(FileNotFoundError): ...
-
 class ModeNotFoundError(KeyError): ...
 class EventHandlerNotFoundError(KeyError): ...
 class ReceiverNotFoundError(KeyError): ...
-class TemplateNotFoundError(KeyError): ...
-class SpecificationNotFoundError(KeyError): ...
-class PanelNotFoundError(KeyError): ...
-
 class InvalidTagError(ValueError): ...
 class InvalidSweepMetadataError(ValueError): ...

spectre_core/logging/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from ._decorators import log_call
+from ._configure import configure_root_logger
+from ._log_handlers import LogHandler, LogHandlers
+
+__all__ = [
+    "log_call", "configure_root_logger", "LogHandler", "LogHandlers"
+]

spectre_core/logging/_configure.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import os
+import logging
+from datetime import datetime
+
+from spectre_core.config import TimeFormats
+from ._log_handlers import LogHandler
+
+def configure_root_logger(process_type: str, 
+                          level: int = logging.INFO
+) -> LogHandler:
+    system_datetime = datetime.now()
+    datetime_stamp = system_datetime.strftime(TimeFormats.DATETIME)
+    pid = os.getpid()
+    log_handler = LogHandler(datetime_stamp, pid, process_type)
+    log_handler.make_parent_path()
+
+    # configure the root logger
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    # Remove any existing handlers to avoid duplicate logs
+    for handler in logger.handlers:
+        logger.removeHandler(handler)
+    # Set up file handler with specific filename
+    file_handler = logging.FileHandler(log_handler.file_path)
+    file_handler.setLevel(level)
+    formatter = logging.Formatter("[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)")
+    file_handler.setFormatter(formatter)
+    # and add it to the root logger
+    logger.addHandler(file_handler)
+
+    return log_handler

spectre_core/logging/_decorators.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import logging
+from typing import Callable
+from functools import wraps
+
+def log_call(func: Callable) -> Callable:
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        logger = logging.getLogger(func.__module__)
+        try:
+            logger.info(f"Calling the function: {func.__name__}")
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"Error in function: {func.__name__}", exc_info=True)
+            raise
+    return wrapper

spectre_core/{logging.py → logging/_log_handlers.py}

@@ -8,26 +8,21 @@ _LOGGER = getLogger(__name__)
 
 import os
 import logging
-from typing import Callable, Optional
+from dataclasses import dataclass
+from typing import Optional
 import warnings
 from collections import OrderedDict
 from datetime import datetime
-from functools import wraps
 
-from spectre_core.file_handlers.text import TextHandler
-from spectre_core.cfg import (
-    LOGS_DIR_PATH, 
-    DEFAULT_DATETIME_FORMAT, 
-    get_logs_dir_path
-)
+from spectre_core._file_io import TextHandler
+from spectre_core.config import get_logs_dir_path, TimeFormats
 
 PROCESS_TYPES = [
     "user", 
     "worker"
 ]
 
-
-def validate_process_type(process_type: str
+def _validate_process_type(process_type: str
 ) -> None:
     if process_type not in PROCESS_TYPES:
         raise ValueError(f"Invalid process type: {process_type}. Expected one of {PROCESS_TYPES}")
@@ -40,12 +35,11 @@ class LogHandler(TextHandler):
                  process_type: str):
         self._datetime_stamp = datetime_stamp
         self._pid = pid
-        validate_process_type(process_type)
+        _validate_process_type(process_type)
         self._process_type = process_type
 
-        dt = datetime.strptime(datetime_stamp, DEFAULT_DATETIME_FORMAT)
-        date_dir = os.path.join(dt.strftime("%Y"), dt.strftime("%m"), dt.strftime("%d"))
-        parent_path = os.path.join(LOGS_DIR_PATH, date_dir)
+        dt = datetime.strptime(datetime_stamp, TimeFormats.DATETIME)
+        parent_path = get_logs_dir_path(dt.year, dt.month, dt.day)
         base_file_name = f"{datetime_stamp}_{pid}_{process_type}"
 
         super().__init__(parent_path, base_file_name, extension = "log")
@@ -164,8 +158,8 @@ class LogHandlers:
         yield from self.log_handler_list
 
 
-    def get_log_handler_from_file_name(self, 
-                                       file_name: str) -> LogHandler:
+    def get_from_file_name(self, 
+                           file_name: str) -> LogHandler:
         # auto strip the extension if present
         file_name, _ = os.path.splitext(file_name)
         try:
@@ -174,48 +168,9 @@ class LogHandlers:
             raise FileNotFoundError(f"Log handler for file name '{file_name}' not found in log map")
 
 
-    def get_log_handler_from_pid(self, 
-                                 pid: str) -> LogHandler:
+    def get_from_pid(self, 
+                     pid: str) -> LogHandler:
         for log_handler in self.log_handler_list:
             if log_handler.pid == pid:
                 return log_handler
-        raise FileNotFoundError(f"Log handler for PID '{pid}' not found in log map")
-
-
-def configure_root_logger(process_type: str, 
-                          level: int = logging.INFO
-) -> LogHandler:
-    system_datetime = datetime.now()
-    datetime_stamp = system_datetime.strftime(DEFAULT_DATETIME_FORMAT)
-    pid = os.getpid()
-    log_handler = LogHandler(datetime_stamp, pid, process_type)
-    log_handler.make_parent_path()
-
-    # configure the root logger
-    logger = logging.getLogger()
-    logger.setLevel(level)
-    # Remove any existing handlers to avoid duplicate logs
-    for handler in logger.handlers:
-        logger.removeHandler(handler)
-    # Set up file handler with specific filename
-    file_handler = logging.FileHandler(log_handler.file_path)
-    file_handler.setLevel(level)
-    formatter = logging.Formatter("[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)")
-    file_handler.setFormatter(formatter)
-    # and add it to the root logger
-    logger.addHandler(file_handler)
-
-    return log_handler
-
-
-def log_call(func: Callable) -> Callable:
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        logger = logging.getLogger(func.__module__)  # Automatically get module-level logger
-        try:
-            logger.info(f"Calling the function: {func.__name__}")
-            return func(*args, **kwargs)
-        except Exception as e:
-            logger.error(f"Error in function: {func.__name__}", exc_info=True)
-            raise
-    return wrapper
+        raise FileNotFoundError(f"Log handler for PID '{pid}' not found in log map")

spectre_core/plotting/__init__.py

@@ -2,4 +2,10 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-import spectre_core.plotting.library
+from ._format import PanelFormat
+from ._panels import Panels
+from ._panel_stack import PanelStack
+
+__all__ = [
+    "PanelFormat", "Panels", "PanelStack"
+]

spectre_core/plotting/{base.py → _base.py}

@@ -5,34 +5,40 @@
 from abc import ABC, abstractmethod
 from typing import Optional
 import numpy as np
+from dataclasses import dataclass
 
 from matplotlib import cm
 import matplotlib.dates as mdates
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
-from spectre_core.spectrograms.spectrogram import Spectrogram
+from spectre_core.spectrograms import Spectrogram, TimeTypes
+from ._format import PanelFormat
+
+
+@dataclass(frozen=True)
+class XAxisTypes:
+    TIME     : str = "time"
+    FREQUENCY: str = "frequency"
 
-TIME_X_AXIS = "time"
-FREQUENCY_X_AXIS = "frequency"
 
 class BasePanel(ABC):
     def __init__(self, 
                  name: str,
-                 spectrogram: Spectrogram, 
-                 time_type: str = "seconds"):
+                 spectrogram: Spectrogram):
         self._name = name
         self._spectrogram = spectrogram
 
-        self._validate_time_type(time_type)
-        self._time_type = time_type
-
         self._x_axis_type: Optional[str] = None
         self._set_x_axis_type()
 
-        self._ax: Optional[Axes] = None # defined while stacking
-        self._fig: Optional[Figure] = None # defined while stacking
-        self._identifier: Optional[str] = None # defined if specified by the user
+        # defined while stacking
+        self._panel_format: Optional[PanelFormat] = None
+        self._time_type: Optional[str] = None
+        self._ax: Optional[Axes] = None
+        self._fig: Optional[Figure] = None
+         # defined if specified by the user
+        self._identifier: Optional[str] = None
 
 
     @abstractmethod
@@ -71,6 +77,12 @@ class BasePanel(ABC):
         return self._time_type
     
 
+    @time_type.setter
+    def time_type(self, value: str) -> None:
+        self._validate_time_type(value)
+        self._time_type = value
+    
+
     @property
     def name(self) -> str:
         if self._name is None:
@@ -83,6 +95,18 @@ class BasePanel(ABC):
         self._name = value
     
     
+    @property
+    def panel_format(self) -> PanelFormat:
+        if self._panel_format is None:
+            raise AttributeError(f"Panel format has not yet been specified for this panel")
+        return self._panel_format
+
+
+    @panel_format.setter
+    def panel_format(self, value: PanelFormat):
+        self._panel_format = value
+
+
     @property
     def ax(self) -> Axes:
         if self._ax is None:
@@ -126,7 +150,7 @@ class BasePanel(ABC):
 
     def _validate_time_type(self, 
                             time_type: str):
-        valid_time_types = ["seconds", "datetimes"]
+        valid_time_types = [TimeTypes.SECONDS, TimeTypes.DATETIMES]
         if time_type not in valid_time_types:
             raise ValueError(f"Invalid time type. "
                              f"Expected one of {valid_time_types} "
@@ -156,11 +180,11 @@ class BaseTimeSeriesPanel(BasePanel):
 
     @property
     def times(self):
-        return self.spectrogram.times if self.time_type == "seconds" else self.spectrogram.datetimes
+        return self.spectrogram.times if self.time_type == TimeTypes.SECONDS else self.spectrogram.datetimes
     
 
     def annotate_x_axis(self):
-        if self.time_type == "seconds":
+        if self.time_type == TimeTypes.SECONDS:
             self.ax.set_xlabel('Time [s]')
         else:
             self.ax.set_xlabel('Time [UTC]')
@@ -168,7 +192,7 @@ class BaseTimeSeriesPanel(BasePanel):
         
         
     def _set_x_axis_type(self):
-        self._x_axis_type = TIME_X_AXIS
+        self._x_axis_type = XAxisTypes.TIME
 
 
 
@@ -187,8 +211,4 @@ class BaseSpectrumPanel(BasePanel):
 
 
     def _set_x_axis_type(self):
-        self._x_axis_type = FREQUENCY_X_AXIS
-
-
-class CutsPanel(BasePanel):
-    """Convenience parent class for cuts"""
+        self._x_axis_type = XAxisTypes.FREQUENCY

spectre_core/plotting/_format.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from dataclasses import dataclass
+
+@dataclass
+class PanelFormat:
+    small_size      : int = 18
+    medium_size     : int = 21
+    large_size      : int = 24
+    line_width      : int = 3
+    style           : str = "dark_background"
+    spectrogram_cmap: str = "gnuplot2"
+    cuts_cmap       : str = "winter"
+    integral_color  : str = "lime"
+
+DEFAULT_FORMAT = PanelFormat()