spectre-core 0.0.23__tar.gz → 0.0.24__tar.gz

{spectre_core-0.0.23 → spectre_core-0.0.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectre-core
-Version: 0.0.23
+Version: 0.0.24
 Summary: The core Python package used by the spectre program. 
 Maintainer-email: Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{spectre_core-0.0.23 → spectre_core-0.0.24}/pyproject.toml

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

spectre_core-0.0.23/tests/test_config.py → spectre_core-0.0.24/src/spectre_core/__init__.py

@@ -1,3 +1,5 @@
 # SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
+
+__version__ = "0.0.24"

{spectre_core-0.0.23 → spectre_core-0.0.24}/src/spectre_core/config/__init__.py

@@ -5,6 +5,8 @@
 
 """General `spectre` package configurations."""
 
+import os
+
 from ._paths import (
     get_spectre_data_dir_path,
     get_batches_dir_path,
@@ -14,6 +16,10 @@ from ._paths import (
 )
 from ._time_formats import TimeFormat
 
+os.makedirs(get_batches_dir_path(), exist_ok=True)
+os.makedirs(get_logs_dir_path(), exist_ok=True)
+os.makedirs(get_configs_dir_path(), exist_ok=True)
+
 __all__ = [
     "get_spectre_data_dir_path",
     "get_batches_dir_path",

{spectre_core-0.0.23 → spectre_core-0.0.24}/src/spectre_core/config/_paths.py

@@ -16,24 +16,17 @@ and creates three directories inside it:
 import os
 from typing import Optional
 
-_SPECTRE_DATA_DIR_PATH = os.environ.get("SPECTRE_DATA_DIR_PATH", "NOTSET")
-if _SPECTRE_DATA_DIR_PATH == "NOTSET":
-    raise ValueError("The environment variable `SPECTRE_DATA_DIR_PATH` must be set.")
-
-_BATCHES_DIR_PATH = os.path.join(_SPECTRE_DATA_DIR_PATH, "batches")
-_LOGS_DIR_PATH = os.path.join(_SPECTRE_DATA_DIR_PATH, "logs")
-_CONFIGS_DIR_PATH = os.path.join(_SPECTRE_DATA_DIR_PATH, "configs")
-
-os.makedirs(_BATCHES_DIR_PATH, exist_ok=True)
-os.makedirs(_LOGS_DIR_PATH, exist_ok=True)
-os.makedirs(_CONFIGS_DIR_PATH, exist_ok=True)
-
 
 def get_spectre_data_dir_path() -> str:
     """The default ancestral path for all `spectre` file system data.
 
     :return: The value stored by the `SPECTRE_DATA_DIR_PATH` environment variable.
     """
+    _SPECTRE_DATA_DIR_PATH = os.environ.get("SPECTRE_DATA_DIR_PATH", "NOTSET")
+    if _SPECTRE_DATA_DIR_PATH == "NOTSET":
+        raise ValueError(
+            "The environment variable `SPECTRE_DATA_DIR_PATH` must be set."
+        )
     return _SPECTRE_DATA_DIR_PATH
 
 
@@ -80,7 +73,8 @@ def get_batches_dir_path(
     :param day: The numeric day. Defaults to None.
     :return: The directory path for batched data files, optionally with a date-based subdirectory.
     """
-    return _get_date_based_dir_path(_BATCHES_DIR_PATH, year, month, day)
+    batches_dir_path = os.path.join(get_spectre_data_dir_path(), "batches")
+    return _get_date_based_dir_path(batches_dir_path, year, month, day)
 
 
 def get_logs_dir_path(
@@ -94,7 +88,8 @@ def get_logs_dir_path(
     :param day: The numeric day. Defaults to None.
     :return: The directory path for log files, optionally with a date-based subdirectory.
     """
-    return _get_date_based_dir_path(_LOGS_DIR_PATH, year, month, day)
+    logs_dir_path = os.path.join(get_spectre_data_dir_path(), "logs")
+    return _get_date_based_dir_path(logs_dir_path, year, month, day)
 
 
 def get_configs_dir_path() -> str:
@@ -102,7 +97,7 @@ def get_configs_dir_path() -> str:
 
     :return: The directory path for configuration files.
     """
-    return _CONFIGS_DIR_PATH
+    return os.path.join(get_spectre_data_dir_path(), "configs")
 
 
 def trim_spectre_data_dir_path(full_path: str) -> str:
@@ -116,7 +111,7 @@ def trim_spectre_data_dir_path(full_path: str) -> str:
     :param full_path: The full file path to be trimmed.
     :return: The relative path with `SPECTRE_DATA_DIR_PATH` removed.
     """
-    return os.path.relpath(full_path, _SPECTRE_DATA_DIR_PATH)
+    return os.path.relpath(full_path, get_spectre_data_dir_path())
 
 
 def add_spectre_data_dir_path(rel_path: str) -> str:
@@ -129,4 +124,4 @@ def add_spectre_data_dir_path(rel_path: str) -> str:
     :param rel_path: The relative file path to be appended.
     :return: The full file path prefixed with `SPECTRE_DATA_DIR_PATH`.
     """
-    return os.path.join(_SPECTRE_DATA_DIR_PATH, rel_path)
+    return os.path.join(get_spectre_data_dir_path(), rel_path)

{spectre_core-0.0.23 → spectre_core-0.0.24}/src/spectre_core/plotting/__init__.py

@@ -5,6 +5,8 @@
 """An intuitive API for plotting spectrogram data."""
 
 from ._format import PanelFormat
+from ._panel_names import PanelName
+from ._base import BasePanel, BaseTimeSeriesPanel, XAxisType
 from ._panels import (
     SpectrogramPanel,
     FrequencyCutsPanel,
@@ -14,6 +16,10 @@ from ._panels import (
 from ._panel_stack import PanelStack
 
 __all__ = [
+    "BaseTimeSeriesPanel",
+    "PanelName",
+    "XAxisType",
+    "BasePanel",
     "PanelFormat",
     "PanelStack",
     "SpectrogramPanel",

{spectre_core-0.0.23 → spectre_core-0.0.24}/src/spectre_core/plotting/_base.py

@@ -20,7 +20,7 @@ from ._panel_names import PanelName
 
 
 class XAxisType(Enum):
-    """The x-axis type for a panel.
+    """The xaxis type for a panel.
 
     Axes are shared in a stack between panels with common `XAxisType`.
 
@@ -37,23 +37,30 @@ class BasePanel(ABC):
 
     `BasePanel` instances are designed to be part of a `PanelStack`, where multiple
     panels contribute to a composite plot. Subclasses must implement methods to define
-    how the panel is drawn and annotated, and specify its x-axis type.
+    how the panel is drawn and annotated, and specify its xaxis type.
     """
 
-    def __init__(self, name: PanelName, spectrogram: Spectrogram) -> None:
+    def __init__(
+        self,
+        name: PanelName,
+        spectrogram: Spectrogram,
+        time_type: TimeType = TimeType.RELATIVE,
+    ) -> None:
         """Initialize an instance of `BasePanel`.
 
         :param name: The name of the panel.
         :param spectrogram: The spectrogram being visualised.
+        :param time_type: Indicates whether the times of each spectrum are relative to the first
+        spectrum in the spectrogram, or datetimes.
         """
         self._name = name
         self._spectrogram = spectrogram
+        self._time_type = time_type
 
-        # internal attributes set by `PanelStack` during stacking.
-        self._panel_format: Optional[PanelFormat] = None
-        self._time_type: Optional[TimeType] = None
+        # These attributes should be set by instances of `PanelStack`.
         self._ax: Optional[Axes] = None
         self._fig: Optional[Figure] = None
+        self._panel_format: Optional[PanelFormat] = None
         self._identifier: Optional[str] = None
 
     @abstractmethod
@@ -62,16 +69,16 @@ class BasePanel(ABC):
 
     @abstractmethod
     def annotate_xaxis(self) -> None:
-        """Modify the `ax` attribute to annotate the x-axis of the panel."""
+        """Modify the `ax` attribute to annotate the xaxis of the panel."""
 
     @abstractmethod
     def annotate_yaxis(self) -> None:
-        """Modify the `ax` attribute to annotate the y-axis of the panel."""
+        """Modify the `ax` attribute to annotate the yaxis of the panel."""
 
     @property
     @abstractmethod
     def xaxis_type(self) -> XAxisType:
-        """Specify the x-axis type for the panel."""
+        """Specify the xaxis type for the panel."""
 
     @property
     def spectrogram(self) -> Spectrogram:
@@ -84,17 +91,18 @@ class BasePanel(ABC):
         return self._spectrogram.tag
 
     @property
-    def time_type(self) -> TimeType:
+    def name(self) -> PanelName:
+        """The name of the panel."""
+        return self._name
+
+    def get_time_type(self) -> TimeType:
         """The time type of the spectrogram.
 
         :raises ValueError: If the `time_type` has not been set.
         """
-        if self._time_type is None:
-            raise ValueError(f"`time_type` for the panel '{self.name}' must be set.")
         return self._time_type
 
-    @time_type.setter
-    def time_type(self, value: TimeType) -> None:
+    def set_time_type(self, value: TimeType) -> None:
         """Set the `TimeType` for the spectrogram.
 
         This controls how time is represented and annotated on the panel.
@@ -103,41 +111,35 @@ class BasePanel(ABC):
         """
         self._time_type = value
 
-    @property
-    def name(self) -> PanelName:
-        """The name of the panel."""
-        return self._name
-
-    @property
-    def panel_format(self) -> PanelFormat:
+    def get_panel_format(self) -> PanelFormat:
         """Retrieve the panel format, which controls the style of the panel.
 
         :raises ValueError: If the `panel_format` has not been set.
         """
         if self._panel_format is None:
-            raise ValueError(f"`panel_format` for the panel '{self.name}' must be set.")
+            raise ValueError(f"`panel_format` must be set for the panel `{self.name}`")
         return self._panel_format
 
-    @panel_format.setter
-    def panel_format(self, value: PanelFormat) -> None:
+    def set_panel_format(self, value: PanelFormat) -> None:
         """Set the panel format to control the style of the panel.
 
         :param value: The `PanelFormat` to assign to the panel.
         """
         self._panel_format = value
 
-    @property
-    def ax(self) -> Axes:
-        """The `Axes` object bound to this panel.
+    def _get_ax(self) -> Axes:
+        """Return the `Axes` object bound to this panel.
 
-        :raises AttributeError: If the `Axes` object has not been set.
+        This method is protected to restrict direct access to `matplotlib` functionality,
+        promoting encapsulation, promoting encapsulation.
+
+        :raises ValueError: If the `Axes` object has not been set.
         """
         if self._ax is None:
-            raise AttributeError(f"`ax` must be set for the panel `{self.name}`")
+            raise ValueError(f"`ax` must be set for the panel `{self.name}`")
         return self._ax
 
-    @ax.setter
-    def ax(self, value: Axes) -> None:
+    def set_ax(self, value: Axes) -> None:
         """Assign a Matplotlib `Axes` object to this panel.
 
         This `Axes` will be used for drawing and annotations.
@@ -146,19 +148,19 @@ class BasePanel(ABC):
         """
         self._ax = value
 
-    @property
-    def fig(self) -> Figure:
-        """
-        The `Figure` object bound to this panel.
+    def _get_fig(self) -> Figure:
+        """Return the `Figure` object bound to this panel.
+
+        This method is protected to restrict direct access to `matplotlib` functionality,
+        promoting encapsulation, promoting encapsulation.
 
-        :raises AttributeError: If the `Figure` object has not been set.
+        :raises ValueError: If the `Figure` object has not been set.
         """
         if self._fig is None:
-            raise AttributeError(f"`fig` must be set for the panel `{self.name}`")
+            raise ValueError(f"`fig` must be set for the panel `{self.name}`")
         return self._fig
 
-    @fig.setter
-    def fig(self, value: Figure) -> None:
+    def set_fig(self, value: Figure) -> None:
         """
         Assign a Matplotlib `Figure` object to this panel.
 
@@ -168,8 +170,7 @@ class BasePanel(ABC):
         """
         self._fig = value
 
-    @property
-    def identifier(self) -> Optional[str]:
+    def get_identifier(self) -> Optional[str]:
         """Optional identifier for the panel.
 
         This identifier can be used to distinguish panels or aid in superimposing
@@ -177,8 +178,7 @@ class BasePanel(ABC):
         """
         return self._identifier
 
-    @identifier.setter
-    def identifier(self, value: str) -> None:
+    def set_identifier(self, value: str) -> None:
         """Set the optional identifier for the panel.
 
         This can be used to distinguish panels or aid in superimposing panels.
@@ -186,12 +186,40 @@ class BasePanel(ABC):
         self._identifier = value
 
     def hide_xaxis_labels(self) -> None:
-        """Hide the x-axis labels for this panel."""
-        self.ax.tick_params(axis="x", labelbottom=False)
+        """Hide the labels for xaxis ticks in the panel."""
+        self._get_ax().tick_params(axis="x", labelbottom=False)
 
     def hide_yaxis_labels(self) -> None:
-        """Hide the y-axis labels for this panel."""
-        self.ax.tick_params(axis="y", labelbottom=False)
+        """Hide the labels for yaxis ticks in the panel."""
+        self._get_ax().tick_params(axis="y", labelleft=False)
+
+    def sharex(self, axes: Axes):
+        """Share the xaxis with another axes."""
+        self._get_ax().sharex(axes)
+
+    def get_xaxis_labels(self) -> list[str]:
+        """Get the text string of all xaxis tick labels."""
+        tick_labels = self._get_ax().get_xaxis().get_ticklabels(which="both")
+        return [tick_label.get_text() for tick_label in tick_labels]
+
+    def get_yaxis_labels(self) -> list[str]:
+        """Get the text string of all yaxis tick labels."""
+        tick_labels = self._get_ax().get_yaxis().get_ticklabels(which="both")
+        return [tick_label.get_text() for tick_label in tick_labels]
+
+    def get_xlabel(self) -> str:
+        """Get the xlabel text string."""
+        return self._get_ax().get_xlabel()
+
+    def get_ylabel(self) -> str:
+        """Get the ylabel text string."""
+        return self._get_ax().get_ylabel()
+
+    def share_axes(self, panel: "BasePanel") -> None:
+        # TODO: More elegantly share axes, rather than access protected method from
+        # another instance. Probably, this should just be entirely managed by the `PanelStack`
+        self.set_ax(panel._get_ax())
+        self.set_fig(panel._get_fig())
 
 
 class BaseTimeSeriesPanel(BasePanel):
@@ -210,38 +238,19 @@ class BaseTimeSeriesPanel(BasePanel):
         """The times assigned to each spectrum according to the `TimeType`."""
         return (
             self.spectrogram.times
-            if self.time_type == TimeType.RELATIVE
+            if self.get_time_type() == TimeType.RELATIVE
             else self.spectrogram.datetimes
         )
 
     def annotate_xaxis(self) -> None:
-        """Annotate the x-axis according to the specified `TimeType`."""
-        if self.time_type == TimeType.RELATIVE:
-            self.ax.set_xlabel("Time [s]")
+        """Annotate the xaxis according to the specified `TimeType`."""
+        ax = self._get_ax()
+        if self.get_time_type() == TimeType.RELATIVE:
+            ax.set_xlabel("Time [s]")
         else:
             # 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))
-
-
-class BaseSpectrumPanel(BasePanel):
-    """An abstract subclass of `BasePanel` tailored for visualising spectrum data.
-
-    Subclasses must implement any remaining abstract methods as described by `BasePanel`.
-    """
-
-    @property
-    def xaxis_type(self) -> Literal[XAxisType.FREQUENCY]:
-        return XAxisType.FREQUENCY
-
-    @property
-    def frequencies(self) -> npt.NDArray[np.float32]:
-        """The physical frequencies assigned to each spectral component."""
-        return self._spectrogram.frequencies
-
-    def annotate_xaxis(self) -> None:
-        """Annotate the x-axis assuming frequency in units of Hz."""
-        self.ax.set_xlabel("Frequency [Hz]")
+            ax.set_xlabel(f"Time [UTC] (Start Date: {start_date})")
+            ax.xaxis.set_major_formatter(mdates.DateFormatter(TimeFormat.TIME))

{spectre_core-0.0.23 → spectre_core-0.0.24}/src/spectre_core/plotting/_panel_stack.py

@@ -66,18 +66,48 @@ class PanelStack:
         self._fig: Optional[Figure] = None
         self._axs: Optional[np.ndarray] = None
 
-    @property
-    def time_type(self) -> TimeType:
-        """The type of time we assign to the spectrograms"""
-        return self._time_type
+    def _sort_by_xaxis_type(self, panels: list[BasePanel]) -> list[BasePanel]:
+        return list(sorted(panels, key=lambda panel: panel.xaxis_type.value))
 
     @property
     def panels(self) -> list[BasePanel]:
         """Get the panels in the stack, sorted by their `XAxisType`."""
-        return list(sorted(self._panels, key=lambda panel: panel.xaxis_type.value))
+        return self._sort_by_xaxis_type(self._panels)
+
+    @property
+    def superimposed_panels(self) -> list[BasePanel]:
+        """Get the superimposed panels in the stack, sorted by their `XAxisType"""
+        return self._sort_by_xaxis_type(self._superimposed_panels)
+
+    @property
+    def num_panels(self) -> int:
+        """Get the number of panels in the stack."""
+        return len(self._panels)
+
+    @property
+    def num_superimposed_panels(self) -> int:
+        """Get the number of superimposed panels in the stack."""
+        return len(self._superimposed_panels)
 
     @property
-    def fig(self) -> Figure:
+    def time_type(self) -> TimeType:
+        """The imposed time type on all time series panels in the stack.
+
+        :raises ValueError: If the `time_type` has not been set.
+        """
+        return self._time_type
+
+    @time_type.setter
+    def time_type(self, value: TimeType) -> None:
+        """Set the `TimeType` for all time series panels in the stack.
+
+        This controls how time is represented and annotated on the panel.
+
+        :param value: The `TimeType` to impose on all time series panels in the stack.
+        """
+        self._time_type = value
+
+    def _get_fig(self) -> Figure:
         """Get the shared `matplotlib` figure for the panel stack.
 
         :raises ValueError: If the axes have not been initialized.
@@ -88,8 +118,7 @@ class PanelStack:
             )
         return self._fig
 
-    @property
-    def axs(self) -> np.ndarray:
+    def _get_axes(self) -> np.ndarray:
         """Get the `matplotlib` axes in the stack.
 
         :return: An array of `matplotlib.axes.Axes`, one for each panel in the stack.
@@ -101,10 +130,13 @@ class PanelStack:
             )
         return np.atleast_1d(self._axs)
 
-    @property
-    def num_panels(self) -> int:
-        """Get the number of panels in the stack."""
-        return len(self._panels)
+    def _validate_time_type(self, panel: BasePanel) -> None:
+        """Check that the time type of the input panel, is consistent with the time type of the stack."""
+        if panel.get_time_type() != self._time_type:
+            raise ValueError(
+                f"Cannot add a panel with inconsistent time type. "
+                f"Expected {self._time_type.value}, but got {panel.get_time_type().value}"
+            )
 
     def add_panel(
         self,
@@ -114,13 +146,16 @@ class PanelStack:
     ) -> None:
         """Add a panel to the stack.
 
+        Overrides the time type of the panel, to the time type of 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 = panel_format or self._panel_format
-        panel.time_type = self._time_type
+        panel.set_panel_format(panel_format or self._panel_format)
+        panel.set_time_type(self._time_type)
         if identifier:
-            panel.identifier = identifier
+            panel.set_identifier(identifier)
+
         self._panels.append(panel)
 
     def superimpose_panel(
@@ -131,13 +166,16 @@ class PanelStack:
     ) -> None:
         """Superimpose a panel onto an existing panel in the stack.
 
+        Overrides the time type of the panel, to the time type of the stack.
+
         :param panel: The panel to superimpose.
         :param identifier: An optional identifier to link panels during superimposing, defaults to None
         """
         if identifier:
-            panel.identifier = identifier
-        panel.panel_format = panel_format or self._panel_format
-        panel.time_type = self._time_type
+            panel.set_identifier(identifier)
+        panel.set_panel_format(panel_format or self._panel_format)
+        panel.set_time_type(self._time_type)
+
         self._superimposed_panels.append(panel)
 
     def _init_plot_style(self) -> None:
@@ -173,16 +211,17 @@ class PanelStack:
     def _assign_axes(self) -> None:
         """Assign each axes in the figure to some panel in the stack.
 
-        Axes are shared between panels with common `xaxis_type`.
+        Axes are shared between panels with common `XAxisType`.
         """
         shared_axes: dict[XAxisType, Axes] = {}
         for i, panel in enumerate(self.panels):
-            panel.ax = self.axs[i]
-            panel.fig = self._fig
+            ax = self._get_axes()[i]
+            panel.set_ax(ax)
+            panel.set_fig(self._fig)
             if panel.xaxis_type in shared_axes:
-                panel.ax.sharex(shared_axes[panel.xaxis_type])
+                panel.sharex(shared_axes[panel.xaxis_type])
             else:
-                shared_axes[panel.xaxis_type] = panel.ax
+                shared_axes[panel.xaxis_type] = ax
 
     def _overlay_cuts(self, cuts_panel: BasePanel) -> None:
         """Overlay cuts onto corresponding spectrogram panels.
@@ -210,9 +249,9 @@ class PanelStack:
         for super_panel in self._superimposed_panels:
             for panel in self._panels:
                 if panel.name == super_panel.name and (
-                    panel.identifier == super_panel.identifier
+                    panel.get_identifier() == super_panel.get_identifier()
                 ):
-                    super_panel.ax, super_panel.fig = panel.ax, self._fig
+                    super_panel.share_axes(panel)
                     super_panel.draw()
                     if _is_cuts_panel(super_panel):
                         self._overlay_cuts(super_panel)
@@ -245,7 +284,7 @@ class PanelStack:
     def show(self) -> None:
         """Display the panel stack figure."""
         self._make_figure()
-        plt.show()
+        self._get_fig().show()
 
     def save(
         self,
@@ -268,5 +307,7 @@ class PanelStack:
             get_batches_dir_path(start_dt.year, start_dt.month, start_dt.day),
             f"{batch_name}.png",
         )
-        plt.savefig(batch_file_path)
+        # If the parent directory does not exist, create it.
+        os.makedirs(os.path.dirname(batch_file_path), exist_ok=True)
+        self._get_fig().savefig(batch_file_path)
         return batch_file_path