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

spectre_core/plotting/_base.py

@@ -20,14 +20,15 @@ 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`.
-    
+
     :ivar TIME: The xaxis has units of time.
     :ivar FREQUENCY: The xaxis has units of frequency.
     """
-    TIME      = "time"
+
+    TIME = "time"
     FREQUENCY = "frequency"
 
 
@@ -36,92 +37,72 @@ 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, 
+        self,
         name: PanelName,
-        spectrogram: Spectrogram
+        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.
+        # 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._time_type   : Optional[TimeType]    = None
-        self._ax          : Optional[Axes]        = None
-        self._fig         : Optional[Figure]      = None
-        self._identifier  : Optional[str]         = None
-
+        self._identifier: Optional[str] = None
 
     @abstractmethod
-    def draw(
-        self
-    ) -> None:
+    def draw(self) -> None:
         """Modify the `ax` attribute to draw the panel contents."""
 
-
     @abstractmethod
-    def annotate_xaxis(
-        self
-    ) -> None:
-        """Modify the `ax` attribute to annotate the x-axis of the panel."""
-
+    def annotate_xaxis(self) -> None:
+        """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."""
-
+    def annotate_yaxis(self) -> None:
+        """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."""
-
+    def xaxis_type(self) -> XAxisType:
+        """Specify the xaxis type for the panel."""
 
     @property
-    def spectrogram(
-        self
-    ) -> Spectrogram:
+    def spectrogram(self) -> Spectrogram:
         """The spectrogram being visualised on this panel."""
         return self._spectrogram
-    
 
     @property
-    def tag(
-        self
-    ) -> str:
+    def tag(self) -> str:
         """The tag of the spectrogram being visualised."""
         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.
@@ -129,59 +110,36 @@ class BasePanel(ABC):
         :param value: The `TimeType` to assign to the spectrogram.
         """
         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
 
+    def _get_ax(self) -> Axes:
+        """Return the `Axes` object bound to this panel.
 
-    @property
-    def ax(
-        self
-    ) -> Axes:
-        """The `Axes` object bound to this panel.
+        This method is protected to restrict direct access to `matplotlib` functionality,
+        promoting encapsulation, promoting encapsulation.
 
-        :raises AttributeError: If the `Axes` object has not been set.
+        :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.
@@ -190,26 +148,19 @@ class BasePanel(ABC):
         """
         self._ax = value
 
+    def _get_fig(self) -> Figure:
+        """Return the `Figure` object bound to this panel.
 
-    @property
-    def fig(
-        self
-    ) -> Figure:
-        """
-        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.
 
@@ -218,104 +169,88 @@ class BasePanel(ABC):
         :param value: The Matplotlib `Figure` to assign to the panel.
         """
         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 
+        This identifier can be used to distinguish panels or aid in superimposing
         panels in a stack.
         """
         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.
         """
         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)
+    def hide_xaxis_labels(self) -> None:
+        """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 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())
 
-    def hide_yaxis_labels(
-        self
-    ) -> None:
-        """Hide the y-axis labels for this panel."""
-        self.ax.tick_params(axis='y', labelbottom=False)
-    
 
 class BaseTimeSeriesPanel(BasePanel):
     """
     Abstract subclass of `BasePanel` designed for visualising time series data.
 
     Subclasses must implement any remaining abstract methods from `BasePanel`.
-    """   
+    """
+
     @property
-    def xaxis_type(
-        self
-    ) -> Literal[XAxisType.TIME]:
+    def xaxis_type(self) -> Literal[XAxisType.TIME]:
         return XAxisType.TIME
-    
-    
+
     @property
-    def times(
-        self
-    ) -> npt.NDArray[np.float32 | np.datetime64]:
+    def times(self) -> npt.NDArray[np.float32 | np.datetime64]:
         """The times assigned to each spectrum according to the `TimeType`."""
-        return self.spectrogram.times if self.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]')
+        return (
+            self.spectrogram.times
+            if self.get_time_type() == TimeType.RELATIVE
+            else self.spectrogram.datetimes
+        )
+
+    def annotate_xaxis(self) -> None:
+        """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]')
+            # TODO: Adapt for time ranges greater than one day
+            start_date = datetime.strftime(
+                self.spectrogram.start_datetime.astype(datetime), TimeFormat.DATE
+            )
+            ax.set_xlabel(f"Time [UTC] (Start Date: {start_date})")
+            ax.xaxis.set_major_formatter(mdates.DateFormatter(TimeFormat.TIME))

spectre_core/plotting/_format.py

@@ -4,9 +4,10 @@
 
 from dataclasses import dataclass
 
+
 @dataclass
 class PanelFormat:
-    """Specifies formatting options for a panel, including font sizes, line styles, 
+    """Specifies formatting options for a panel, including font sizes, line styles,
     colour maps, and general visual settings.
 
     These formatting values can be applied consistently across all panels within a `PanelStack`,
@@ -21,11 +22,12 @@ class PanelFormat:
     :ivar style: Matplotlib style applied to the panel, defaults to "dark_background".
     :ivar spectrogram_cmap: Colormap applied to spectrogram plots, defaults to "gnuplot2".
     """
-    small_size      : int = 18
-    medium_size     : int = 21
-    large_size      : int = 24
-    line_width      : int = 3
-    line_color      : str = "lime"
-    line_cmap       : str = "winter"
-    style           : str = "dark_background"
+
+    small_size: int = 18
+    medium_size: int = 21
+    large_size: int = 24
+    line_width: int = 3
+    line_color: str = "lime"
+    line_cmap: str = "winter"
+    style: str = "dark_background"
     spectrogram_cmap: str = "gnuplot2"

spectre_core/plotting/_panel_names.py

@@ -4,15 +4,17 @@
 
 from enum import Enum
 
+
 class PanelName(Enum):
     """Literal corresponding to a fully implemented `BasePanel` subclass.
-    
+
     :ivar SPECTROGRAM: Panel for visualising the full spectrogram.
     :ivar FREQUENCY_CUTS: Panel for visualising individual spectrums in a spectrogram.
     :ivar TIME_CUTS: Panel for visualising spectrogram data as time series of spectral components.
     :ivar INTEGRAL_OVER_FREQUENCY: Panel for visualising the spectrogram integrated over frequency.
     """
-    SPECTROGRAM             = "spectrogram"
-    FREQUENCY_CUTS          = "frequency_cuts"
-    TIME_CUTS               = "time_cuts"
-    INTEGRAL_OVER_FREQUENCY = "integral_over_frequency"
+
+    SPECTROGRAM = "spectrogram"
+    FREQUENCY_CUTS = "frequency_cuts"
+    TIME_CUTS = "time_cuts"
+    INTEGRAL_OVER_FREQUENCY = "integral_over_frequency"