Add native datetime axis support with formatting and limits configuration

Author: PierreRaybaut

CHANGELOG.md

@@ -35,6 +35,14 @@
 * New `SyncPlotDialog` class:
   * This class provides a dialog for displaying synchronized plots.
   * This is a complementary class to `SyncPlotWindow`, providing a modal dialog interface for synchronized plotting.
+* Native datetime axis support:
+  * Added `DateTimeScaleDraw` class in `plotpy.styles.scaledraw` for formatting axis labels as date/time strings
+  * Added `BasePlot.set_axis_datetime()` method to easily configure an axis for datetime display
+  * Added `BasePlot.set_axis_limits_from_datetime()` method to set axis limits using datetime objects directly
+  * Supports customizable datetime format strings using Python's `strftime` format codes
+  * Configurable label rotation and spacing for optimal display
+  * Example: `plot.set_axis_datetime("bottom", format="%H:%M:%S")` for time-only display
+  * Example: `plot.set_axis_limits_from_datetime("bottom", dt1, dt2)` to zoom to a specific time range
 
 🧹 API cleanup: removed deprecated update methods (use `update_item` instead)
 

plotpy/plot/base.py

@@ -52,10 +52,12 @@
     PolygonMapItem,
     PolygonShape,
 )
+from plotpy.plot.scaledraw import DateTimeScaleDraw
 from plotpy.styles.axes import AxesParam, AxeStyleParam, AxisParam, ImageAxesParam
 from plotpy.styles.base import GridParam, ItemParameters
 
 if TYPE_CHECKING:
+    from datetime import datetime
     from typing import IO
 
     from qwt.scale_widget import QwtScaleWidget
@@ -1114,6 +1116,80 @@ def set_scales(self, xscale: str, yscale: str) -> None:
         self.set_axis_scale(ay, yscale)
         self.replot()
 
+    def set_axis_datetime(
+        self,
+        axis_id: int | str,
+        format: str = "%Y-%m-%d %H:%M:%S",
+        rotate: float = -45,
+        spacing: int = 20,
+    ) -> None:
+        """Configure an axis to display datetime labels
+
+        This method sets up an axis to display Unix timestamps as formatted
+        date/time strings.
+
+        Args:
+            axis_id: Axis ID (constants.Y_LEFT, constants.X_BOTTOM, ...)
+                or string: 'bottom', 'left', 'top' or 'right'
+            format: Format string for datetime display (default: "%Y-%m-%d %H:%M:%S").
+                Uses Python datetime.strftime() format codes.
+            rotate: Rotation angle for labels in degrees (default: -45)
+            spacing: Spacing between labels (default: 20)
+
+        Examples:
+            >>> # Enable datetime on x-axis with default format
+            >>> plot.set_axis_datetime("bottom")
+
+            >>> # Enable datetime with time only
+            >>> plot.set_axis_datetime("bottom", format="%H:%M:%S")
+
+            >>> # Enable datetime with date only, no rotation
+            >>> plot.set_axis_datetime("bottom", format="%Y-%m-%d", rotate=0)
+        """
+        axis_id = self.get_axis_id(axis_id)
+        scale_draw = DateTimeScaleDraw(format=format, rotate=rotate, spacing=spacing)
+        self.setAxisScaleDraw(axis_id, scale_draw)
+        self.replot()
+
+    def set_axis_limits_from_datetime(
+        self,
+        axis_id: int | str,
+        dt_min: "datetime",
+        dt_max: "datetime",
+        stepsize: int = 0,
+    ) -> None:
+        """Set axis limits using datetime objects
+
+        This is a convenience method to set axis limits for datetime axes without
+        manually converting datetime objects to Unix timestamps.
+
+        Args:
+            axis_id: Axis ID (constants.Y_LEFT, constants.X_BOTTOM, ...)
+                or string: 'bottom', 'left', 'top' or 'right'
+            dt_min: Minimum datetime value
+            dt_max: Maximum datetime value
+            stepsize: The step size (optional, default=0)
+
+        Examples:
+            >>> from datetime import datetime
+            >>> # Set x-axis limits to a specific date range
+            >>> dt1 = datetime(2025, 10, 7, 10, 0, 0)
+            >>> dt2 = datetime(2025, 10, 7, 18, 0, 0)
+            >>> plot.set_axis_limits_from_datetime("bottom", dt1, dt2)
+        """
+        from datetime import datetime
+
+        if not isinstance(dt_min, datetime) or not isinstance(dt_max, datetime):
+            raise TypeError("dt_min and dt_max must be datetime objects")
+
+        # Convert datetime objects to Unix timestamps
+        epoch = datetime(1970, 1, 1)
+        timestamp_min = (dt_min - epoch).total_seconds()
+        timestamp_max = (dt_max - epoch).total_seconds()
+
+        # Set the axis limits using the timestamps
+        self.set_axis_limits(axis_id, timestamp_min, timestamp_max, stepsize)
+
     def get_autoscale_margin_percent(self) -> float:
         """Get autoscale margin percentage
 

plotpy/plot/scaledraw.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see plotpy/LICENSE for details)
+
+"""Scale draw classes for custom axis formatting"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from qtpy import QtCore as QC
+from qwt import QwtScaleDraw, QwtText
+
+
+class DateTimeScaleDraw(QwtScaleDraw):
+    """Scale draw for datetime axis
+
+    This class formats axis labels as date/time strings from Unix timestamps.
+
+    Args:
+        format: Format string for datetime display (default: "%Y-%m-%d %H:%M:%S").
+                Uses Python datetime.strftime() format codes.
+        rotate: Rotation angle for labels in degrees (default: -45)
+        spacing: Spacing between labels (default: 20)
+
+    Examples:
+        >>> # Create a datetime scale with default format
+        >>> scale = DateTimeScaleDraw()
+
+        >>> # Create a datetime scale with custom format (time only)
+        >>> scale = DateTimeScaleDraw(format="%H:%M:%S")
+
+        >>> # Create a datetime scale with date only
+        >>> scale = DateTimeScaleDraw(format="%Y-%m-%d", rotate=0)
+    """
+
+    def __init__(
+        self,
+        format: str = "%Y-%m-%d %H:%M:%S",
+        rotate: float = -45,
+        spacing: int = 20,
+    ):
+        super().__init__()
+        self._format = format
+        self.setLabelRotation(rotate)
+        self.setLabelAlignment(QC.Qt.AlignHCenter | QC.Qt.AlignVCenter)
+        self.setSpacing(spacing)
+
+    def label(self, value: float) -> QwtText:
+        """Convert a timestamp value to a formatted date/time label
+
+        Args:
+            value: Unix timestamp (seconds since epoch)
+
+        Returns:
+            QwtText: Formatted label
+        """
+        try:
+            dt = datetime.fromtimestamp(value)
+            return QwtText(dt.strftime(self._format))
+        except (ValueError, OSError):
+            # Handle invalid timestamps
+            return QwtText("")
+
+    def get_format(self) -> str:
+        """Get the current datetime format string
+
+        Returns:
+            str: Format string
+        """
+        return self._format
+
+    def set_format(self, format: str) -> None:
+        """Set the datetime format string
+
+        Args:
+            format: Format string for datetime display
+        """
+        self._format = format

plotpy/tests/features/test_plot_time.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see plotpy/LICENSE for details)
+
+"""Curve plotting with time axis test"""
+
+# guitest: show
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+import numpy as np
+from guidata.qthelpers import qt_app_context
+
+from plotpy.builder import make
+from plotpy.tests import vistools as ptv
+
+
+def __create_time_data() -> tuple[np.ndarray, np.ndarray]:
+    """Create time data"""
+    # Create a temperature monitoring signal with second-resolution timestamps
+    base_time = datetime(2025, 10, 7, 10, 0, 0)
+    timestamps = [base_time + timedelta(seconds=i * 10) for i in range(100)]
+
+    # Convert timestamps to numpy array of floats (seconds since epoch)
+    x = np.array([(ts - datetime(1970, 1, 1)).total_seconds() for ts in timestamps])
+
+    # Simulate temperature data with daily variation and noise
+    hours_elapsed = np.arange(100) * 10 / 3600  # Convert to hours
+    y = 20 + 5 * np.sin(2 * np.pi * hours_elapsed / 24) + np.random.randn(100) * 0.5
+
+    return x, y
+
+
+def test_plot_time_axis():
+    """Test plot time axis"""
+    with qt_app_context(exec_loop=True):
+        x, y = __create_time_data()
+        items = [make.curve(x, y, color="b")]
+        win = ptv.show_items(
+            items, plot_type="curve", wintitle=test_plot_time_axis.__doc__
+        )
+        plot = win.manager.get_plot()
+        # Configure x-axis for datetime display
+        plot.set_axis_datetime("bottom", format="%H:%M:%S")
+        # Set axis limits using datetime objects (zoom to first half of data)
+        base_time = datetime(2025, 10, 7, 10, 0, 0)
+        plot.set_axis_limits_from_datetime(
+            "bottom",
+            base_time,
+            base_time + timedelta(minutes=10),
+        )
+
+
+if __name__ == "__main__":
+    test_plot_time_axis()

plotpy/tests/unit/test_datetime_axis.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the terms of the BSD 3-Clause
+# (see plotpy/LICENSE for details)
+
+"""Testing datetime axis feature"""
+
+# guitest: show
+
+from datetime import datetime
+
+import numpy as np
+from guidata.qthelpers import qt_app_context
+
+from plotpy.builder import make
+from plotpy.plot.scaledraw import DateTimeScaleDraw
+from plotpy.tests import vistools as ptv
+
+
+def test_datetime_axis():
+    """Testing datetime axis with various formats"""
+    with qt_app_context(exec_loop=False):
+        # Create time data
+        x = np.linspace(0, 86400, 100)  # One day in seconds from epoch
+        y = np.sin(x / 3600 * 2 * np.pi) + np.random.randn(100) * 0.1
+
+        items = [make.curve(x, y, color="b")]
+        win = ptv.show_items(items, plot_type="curve", wintitle="Test datetime axis")
+        plot = win.manager.get_plot()
+
+        # Test 1: Set datetime axis with default format
+        plot.set_axis_datetime("bottom")
+        scale_draw = plot.axisScaleDraw(plot.xBottom)
+        assert isinstance(scale_draw, DateTimeScaleDraw)
+        assert scale_draw.get_format() == "%Y-%m-%d %H:%M:%S"
+
+        # Test 2: Set datetime axis with custom format (time only)
+        plot.set_axis_datetime("bottom", format="%H:%M:%S")
+        scale_draw = plot.axisScaleDraw(plot.xBottom)
+        assert scale_draw.get_format() == "%H:%M:%S"
+
+        # Test 3: Set datetime axis with date only
+        plot.set_axis_datetime("bottom", format="%Y-%m-%d", rotate=0, spacing=10)
+        scale_draw = plot.axisScaleDraw(plot.xBottom)
+        assert scale_draw.get_format() == "%Y-%m-%d"
+
+        # Test 4: Verify label formatting
+        timestamp = 86400.0  # 1970-01-02 00:00:00 UTC
+        label = scale_draw.label(timestamp)
+        expected = datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d")
+        assert label.text() == expected
+
+        # Test 5: Set axis limits using datetime objects
+        dt1 = datetime(1970, 1, 1, 6, 0, 0)
+        dt2 = datetime(1970, 1, 1, 18, 0, 0)
+        plot.set_axis_limits_from_datetime("bottom", dt1, dt2)
+
+        # Verify the limits were set correctly
+        # Note: autoscale margin might affect the exact values
+        vmin, vmax = plot.get_axis_limits("bottom")
+        expected_min = (dt1 - datetime(1970, 1, 1)).total_seconds()
+        expected_max = (dt2 - datetime(1970, 1, 1)).total_seconds()
+        # Just verify that limits are in the right order and contain expected range
+        assert vmin <= expected_min
+        assert vmax >= expected_max
+        assert vmax > vmin
+
+        print("All datetime axis tests passed!")
+
+
+if __name__ == "__main__":
+    test_datetime_axis()