spectre-core 0.0.18__tar.gz → 0.0.20__tar.gz

{spectre_core-0.0.18 → spectre_core-0.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: spectre-core
-Version: 0.0.18
+Version: 0.0.20
 Summary: The core Python package used by the spectre program. 
 Maintainer-email: Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -692,6 +692,7 @@ Requires-Dist: astropy==6.0.1
 Requires-Dist: matplotlib==3.5.0
 Requires-Dist: watchdog==4.0.0
 Requires-Dist: mypy==1.14.1
+Dynamic: license-file
 
 # spectre-core
 

{spectre_core-0.0.18 → spectre_core-0.0.20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spectre-core"
-version = "0.0.18"
+version = "0.0.20"
 maintainers = [
   { name="Jimmy Fitzpatrick", email="jcfitzpatrick12@gmail.com" },
 ]

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/batches/_base.py

@@ -4,8 +4,10 @@
 
 from datetime import datetime
 from typing import TypeVar
+from base64 import b64encode
 from functools import cached_property
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 
 from spectre_core._file_io import BaseFileHandler
 from spectre_core.config import get_batches_dir_path, TimeFormat
@@ -64,6 +66,40 @@ class BatchFile(BaseFileHandler[T]):
     ) -> str:
         """The batch name tag."""
         return self._tag
+  
+  
+@dataclass(frozen=True)
+class _BatchExtension:
+    """Supported extensions for a `BaseBatch`, inherited by all derived classes.
+    
+    :ivar PNG: Corresponds to the `.png` file extension.
+    """
+    PNG: str = "png"
+      
+    
+class _PngFile(BatchFile[str]):
+    """Stores an image visualising the data for the batch."""
+    def __init__(
+        self, 
+        batch_parent_dir_path: str, 
+        batch_name: str
+    ) -> None:
+        """Initialise a `_PngFile` instance.
+
+        :param batch_parent_dir_path: The parent directory for the batch.
+        :param batch_name: The batch name.
+        """
+        super().__init__(batch_parent_dir_path, batch_name, _BatchExtension.PNG)
+
+
+    def _read(self) -> str:
+        """Reads the PNG file and returns it base64-encoded.
+
+        :return: Base64-encoded string representation of the image.
+        """
+        with open(self.file_path, "rb") as f:
+            encoded = b64encode(f.read())
+            return encoded.decode("ascii")
    
  
 class BaseBatch(ABC):
@@ -98,6 +134,10 @@ class BaseBatch(ABC):
         # internal register of batch files
         self._batch_files: dict[str, BatchFile] = {}
     
+        # Add the files shared by all derived classes
+        self._png_file  = _PngFile(self.parent_dir_path, self.name)
+        self.add_file( self._png_file ) 
+    
     
     @property
     @abstractmethod
@@ -166,6 +206,14 @@ class BaseBatch(ABC):
         """
         return self._batch_files
     
+    
+    @property
+    def png_file(
+        self
+    ) -> _PngFile:
+        """The batch file corresponding to the `.png` extension."""
+        return self._png_file
+    
 
     def add_file(
         self, 

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/batches/_batches.py

@@ -209,23 +209,20 @@ class Batches(Generic[T]):
             return self._get_from_index(subscript)
 
 
-    def get_spectrogram_from_range(
+    def get_spectrogram(
         self,
-        start_time: str, 
-        end_time: str
+        start_datetime: datetime, 
+        end_datetime: datetime
     ) -> Spectrogram:
         """
         Retrieve a spectrogram spanning the specified time range. 
 
-        :param start_time: The start time of the range (inclusive).
-        :param end_time: The end time of the range (inclusive).
+        :param start_datetime: The start time of the range (inclusive).
+        :param end_datetime: The end time of the range (inclusive).
         :raises FileNotFoundError: If no spectrogram data is available within the specified time range.
         :return: A spectrogram created by stitching together data from all matching batches.
         """
-        # Convert input strings to datetime objects
-        start_datetime = datetime.strptime(start_time, TimeFormat.DATETIME)
-        end_datetime   = datetime.strptime(end_time,   TimeFormat.DATETIME)
-
+        
         spectrograms = []
         for batch in self:
             # skip batches without spectrogram data
@@ -238,10 +235,10 @@ class Batches(Generic[T]):
 
             # Check if the batch overlaps with the input time range
             if start_datetime <= upper_bound and lower_bound <= end_datetime:
-                spectrograms.append( time_chop(spectrogram, start_time, end_time) )
+                spectrograms.append( time_chop(spectrogram, start_datetime, end_datetime) )
 
         if spectrograms:
             return join_spectrograms(spectrograms)
         else:
             raise FileNotFoundError(f"No spectrogram data found for the time range "
-                                    f"{start_time} to {end_time}.")
+                                    f"{start_datetime} to {end_datetime}.")

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/batches/plugins/_iq_stream.py

@@ -317,7 +317,6 @@ class IQStreamBatch(BaseBatch):
         :param tag: The batch name tag.
         """
         super().__init__(start_time, tag) 
-        self._batch_files = {}
         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)

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/capture_configs/_capture_config.py

@@ -42,7 +42,7 @@ class CaptureConfig(JsonHandler):
         self._validate_tag(tag)
         self._tag = tag
         super().__init__(get_configs_dir_path(),
-                         f"capture_{tag}")
+                         tag)
         
     @property
     def tag(
@@ -60,11 +60,8 @@ class CaptureConfig(JsonHandler):
         
         Some substrings are reserved for third-party spectrogram data.
         """
-        if "_" in tag:
-            raise InvalidTagError(f"Tags cannot contain an underscore. Received {tag}")
-        
         if "callisto" in tag:
-            raise ValueError(f"The substring `callisto` 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

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/plotting/_base.py

@@ -5,6 +5,7 @@
 from abc import ABC, abstractmethod
 from typing import Optional, Literal
 from enum import Enum
+from datetime import datetime
 
 import numpy.typing as npt
 import numpy as np
@@ -13,6 +14,7 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
 from spectre_core.spectrograms import Spectrogram, TimeType
+from spectre_core.config import TimeFormat
 from ._format import PanelFormat
 from ._panel_names import PanelName
 
@@ -284,8 +286,11 @@ class BaseTimeSeriesPanel(BasePanel):
         if self.time_type == TimeType.RELATIVE:
             self.ax.set_xlabel('Time [s]')
         else:
-            self.ax.set_xlabel('Time [UTC]')
-            self.ax.xaxis.set_major_formatter(mdates.DateFormatter('%H:%M:%S'))
+            #TODO: Adapt for time ranges greater than one day
+            start_date = datetime.strftime(self.spectrogram.start_datetime.astype(datetime),
+                                           TimeFormat.DATE)
+            self.ax.set_xlabel(f'Time [UTC] (Start Date: {start_date})')
+            self.ax.xaxis.set_major_formatter(mdates.DateFormatter(TimeFormat.TIME))
 
 
 

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/plotting/_panel_stack.py

@@ -2,18 +2,22 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+import os
 import numpy as np
-import numpy.typing as npt
 from typing import Optional, Tuple, cast
 import matplotlib.pyplot as plt
 from matplotlib.figure import Figure
 from matplotlib.axes import Axes
+from matplotlib import use
+from datetime import datetime
 
 from spectre_core.spectrograms import TimeType
+from spectre_core.config import TimeFormat, get_batches_dir_path
 from ._base import BasePanel, XAxisType
 from ._format import PanelFormat
-from ._panels import PanelName, SpectrogramPanel, TimeCutsPanel, FrequencyCutsPanel
-
+from ._panels import (
+    PanelName, SpectrogramPanel, TimeCutsPanel, FrequencyCutsPanel
+)
 
 def _is_cuts_panel(
     panel: BasePanel
@@ -43,17 +47,22 @@ class PanelStack:
         self, 
         panel_format: PanelFormat = PanelFormat(),
         time_type: TimeType = TimeType.RELATIVE,
-        figsize: Tuple[int, int] = (10, 10)
+        figsize: Tuple[int, int] = (15, 8),
+        non_interactive: bool = False
     ) -> None:
         """Initialize an instance of `PanelStack`.
 
         :param panel_format: Formatting applied across all panels in the stack. Defaults to `PanelFormat()`.
         :param time_type: The type of time assigned to spectrograms, defaults to `TimeType.RELATIVE`.
-        :param figsize: The size of the `matplotlib` figure as (width, height). Defaults to (10, 10).
+        :param figsize: The size of the `matplotlib` figure as (width, height). Defaults to (15, 8).
         """
         self._panel_format = panel_format
         self._time_type = time_type
         self._figsize = figsize
+        
+        if non_interactive:
+            # Use a non-interactive matplotlib backend, which can only write files.
+            use('agg')
 
         self._panels             : list[BasePanel] = []
         self._superimposed_panels: list[BasePanel] = []
@@ -116,14 +125,15 @@ class PanelStack:
     def add_panel(
         self, 
         panel: BasePanel,
-        identifier: Optional[str] = None
+        identifier: Optional[str] = None,
+        panel_format: Optional[PanelFormat] = None
     ) -> None:
         """Add a panel to the stack.
 
         :param panel: An instance of a `BasePanel` subclass to be added to the stack.
         :param identifier: An optional string to link the panel with others for superimposing.
         """
-        panel.panel_format = self._panel_format
+        panel.panel_format = panel_format or self._panel_format 
         panel.time_type    = self._time_type
         if identifier: 
             panel.identifier = identifier
@@ -133,7 +143,8 @@ class PanelStack:
     def superimpose_panel(
         self, 
         panel: BasePanel,
-        identifier: Optional[str] = None
+        identifier: Optional[str] = None,
+        panel_format: Optional[PanelFormat] = None
     ) -> None:
         """Superimpose a panel onto an existing panel in the stack.
 
@@ -142,7 +153,8 @@ class PanelStack:
         """
         if identifier:
             panel.identifier = identifier
-        panel.panel_format = self._panel_format
+        panel.panel_format = panel_format or self._panel_format
+        panel.time_type    = self._time_type
         self._superimposed_panels.append(panel)
 
 
@@ -234,11 +246,13 @@ class PanelStack:
                     if _is_cuts_panel(super_panel):
                         self._overlay_cuts(super_panel)
 
-
-    def show(
+    def _make_figure(
         self
     ) -> None:
-        """Display the panel stack figure."""
+        """Make the panel stack figure."""
+        if self.num_panels < 1:
+            raise ValueError(f"There must be at least one panel in the stack.")
+        
         self._init_plot_style()
         self._create_figure_and_axes()
         self._assign_axes()
@@ -258,4 +272,34 @@ class PanelStack:
                 self._overlay_cuts(panel)
                 
         self._overlay_superimposed_panels()
+
+    def show(
+        self
+    ) -> None:
+        """Display the panel stack figure."""
+        self._make_figure()
         plt.show()
+        
+        
+    def save(
+        self,
+    ) -> str:
+        """Save the panel stack figure as a batch file under the tag of the first 
+        panel in the stack. The file format is `png`. 
+        
+        :return: The file path of the newly created batch file containing the figure.
+        """
+        self._make_figure()
+        first_panel = self._panels[0]
+        
+        start_dt = cast(datetime, first_panel.spectrogram.start_datetime.astype(datetime))
+        batch_name = f"{start_dt.strftime(TimeFormat.DATETIME)}_{first_panel.spectrogram.tag}"
+        batch_file_path = os.path.join(
+            get_batches_dir_path(start_dt.year, start_dt.month, start_dt.day),
+            f"{batch_name}.png"
+        )
+        plt.savefig(batch_file_path)
+        return batch_file_path
+        
+        
+

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/spectrograms/_transform.py

@@ -58,30 +58,30 @@ def frequency_chop(
 
 def time_chop(
     spectrogram: Spectrogram, 
-    start_time: str, 
-    end_time: str
+    start_datetime: datetime, 
+    end_datetime: datetime
 ) -> Spectrogram:
     """
     Extracts a portion of the spectrogram within the specified time range.
 
     :param spectrogram: The input spectrogram to process.
-    :param start_time: The starting time of the desired range.
-    :param end_time: The ending time of the desired range.
+    :param start_datetime: The starting time of the desired range.
+    :param end_datetime: The ending time of the desired range.
     :raises ValueError: If the specified time range is entirely outside the spectrogram's time range.
     :raises ValueError: If the start and end indices for the time range are identical.
     :return: A new spectrogram containing only the specified time range.
     """
-    start_datetime = np.datetime64( datetime.strptime(start_time, TimeFormat.DATETIME) )
-    end_datetime   = np.datetime64( datetime.strptime(end_time  , TimeFormat.DATETIME) )
+    start_datetime64 = np.datetime64(start_datetime)
+    end_datetime64   = np.datetime64(end_datetime)
 
-    is_entirely_below_time_range = (start_datetime < spectrogram.datetimes[0] and end_datetime < spectrogram.datetimes[0])
-    is_entirely_above_time_range = (start_datetime > spectrogram.datetimes[-1] and end_datetime > spectrogram.datetimes[-1])
+    is_entirely_below_time_range = (start_datetime64 < spectrogram.datetimes[0] and end_datetime64 < spectrogram.datetimes[0])
+    is_entirely_above_time_range = (start_datetime64 > spectrogram.datetimes[-1] and end_datetime64 > spectrogram.datetimes[-1])
     if is_entirely_below_time_range or is_entirely_above_time_range:
         raise ValueError(f"Requested time interval is entirely out of range of the input spectrogram.")
     
     # find the index of the nearest matching spectrums in the spectrogram.
-    start_index = find_closest_index(start_datetime, spectrogram.datetimes)
-    end_index   = find_closest_index(end_datetime, spectrogram.datetimes)
+    start_index = find_closest_index(start_datetime64, spectrogram.datetimes)
+    end_index   = find_closest_index(end_datetime64, spectrogram.datetimes)
     
     # enforce distinct start and end indices
     if start_index == end_index:

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core/wgetting/_callisto.py

@@ -9,7 +9,7 @@ import gzip
 from datetime import datetime
 
 from spectre_core.config import (
-    get_spectre_data_dir_path, get_batches_dir_path, TimeFormat, trim_spectre_data_dir_path
+    get_spectre_data_dir_path, get_batches_dir_path, TimeFormat
 )
 
 from enum import Enum
@@ -136,12 +136,12 @@ def _unzip_file_to_batches(
     Decompress a `.fit.gz` file and save it as a `.fits` batch file.
 
     :param gz_path: Path to the `.fit.gz` file.
-    :return: The file path of the newly created batch file, relative to `SPECTRE_DATA_DIR_PATH`.
+    :return: The file path of the newly created batch file, as absolute paths within the container's file system.
     """
     fits_path = _get_batch_path(gz_path)
     with gzip.open(gz_path, "rb") as f_in, open(fits_path, "wb") as f_out:
         shutil.copyfileobj(f_in, f_out)
-        return trim_spectre_data_dir_path(f_out.name)
+        return f_out.name
 
 
 def _unzip_to_batches(
@@ -152,7 +152,7 @@ def _unzip_to_batches(
     batch files.
 
     :param tmp_dir: Path to the temporary directory containing `.gz` files.
-    :return: A list of file names of all newly created batch files, relative to `SPECTRE_DATA_DIR_PATH`.
+    :return: A list of file names of all newly created batch files, as absolute paths within the container's file system.
     """
     batch_file_names = []
     for entry in os.scandir(tmp_dir):
@@ -203,7 +203,7 @@ def download_callisto_data(
     :param year: Year of the observation.
     :param month: Month of the observation.
     :param day: Day of the observation.
-    :return: A list of file names of all newly created batch files, relative to `SPECTRE_DATA_DIR_PATH`.
+    :return: A list of file names of all newly created batch files, as absolute paths within the container's file system.
     """
     tmp_dir = os.path.join(get_spectre_data_dir_path(), "tmp")
     # if there are any residual files in the temporary directory, remove them.

{spectre_core-0.0.18 → spectre_core-0.0.20}/src/spectre_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: spectre-core
-Version: 0.0.18
+Version: 0.0.20
 Summary: The core Python package used by the spectre program. 
 Maintainer-email: Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -692,6 +692,7 @@ Requires-Dist: astropy==6.0.1
 Requires-Dist: matplotlib==3.5.0
 Requires-Dist: watchdog==4.0.0
 Requires-Dist: mypy==1.14.1
+Dynamic: license-file
 
 # spectre-core