BaseRecord: add time conversion methods.

These methods can be used to convert between three different
representations of time:

- frame number (i.e., an index into the p_signal or d_signal array)

- elapsed time in microseconds, represented by a datetime.timedelta
  object

- absolute date and time, represented by a datetime.datetime object

Each of these methods will accept any of these three representations
as an argument, and convert into the specified representation.

For example, using record 100 (which has a frame frequency of 360 Hz):

    >>> r = wfdb.rdrecord('sample-data/100')
    >>> r.get_elapsed_time(180)
    datetime.timedelta(microseconds=500000)
    >>> r.get_frame_number(datetime.timedelta(seconds=0.5))
    180.0

Author: Benjamin Moody

docs/io.rst

@@ -12,10 +12,12 @@ WFDB Records
     :members: rdrecord, rdheader, rdsamp, wrsamp
 
 .. autoclass:: wfdb.io.Record
-    :members: wrsamp, adc, dac
+    :members: get_frame_number, get_elapsed_time, get_absolute_time,
+              wrsamp, adc, dac
 
 .. autoclass:: wfdb.io.MultiRecord
-    :members: multi_to_single
+    :members: get_frame_number, get_elapsed_time, get_absolute_time,
+              multi_to_single
 
 
 WFDB Anotations

docs/wfdb.rst

@@ -12,10 +12,12 @@ WFDB Records
     :members: rdrecord, rdheader, rdsamp, wrsamp
 
 .. autoclass:: wfdb.Record
-    :members: wrsamp, adc, dac
+    :members: get_frame_number, get_elapsed_time, get_absolute_time,
+              wrsamp, adc, dac
 
 .. autoclass:: wfdb.MultiRecord
-    :members: multi_to_single
+    :members: get_frame_number, get_elapsed_time, get_absolute_time,
+              multi_to_single
 
 
 WFDB Anotations

wfdb/io/record.py

@@ -249,6 +249,105 @@ def base_datetime(self, value):
         else:
             raise TypeError(f"invalid base_datetime value: {value!r}")
 
+    def get_frame_number(self, time_value):
+        """
+        Convert a time value to a frame number.
+
+        A time value may be specified as:
+        - An integer or floating-point number, representing the number of
+          WFDB frames elapsed from the start of the record.
+        - A `datetime.timedelta` object, representing elapsed time from the
+          start of the record.
+        - A `datetime.datetime` object, representing an absolute date and
+          time (if the record starting time is known.)
+
+        Note that this function may return a value that is less than zero
+        or greater than the actual length of the record.
+
+        Parameters
+        ----------
+        time_value : number or timedelta or datetime
+            A time value.
+
+        Returns
+        -------
+        frame_number : float
+            Frame number (possibly a fractional frame number).
+
+        """
+        if hasattr(time_value, "__float__"):
+            return float(time_value)
+
+        if isinstance(time_value, datetime.datetime):
+            if not self.base_datetime:
+                raise ValueError(
+                    "base_datetime is unknown; cannot convert absolute "
+                    "date/time to a frame number"
+                )
+            time_value -= self.base_datetime
+
+        if isinstance(time_value, datetime.timedelta):
+            return time_value.total_seconds() * self.fs
+
+        raise TypeError(f"invalid time value: {time_value!r}")
+
+    def get_elapsed_time(self, time_value):
+        """
+        Convert a time value to an elapsed time in seconds.
+
+        A time value may be specified as:
+        - An integer or floating-point number, representing the number of
+          WFDB frames elapsed from the start of the record.
+        - A `datetime.timedelta` object, representing elapsed time from the
+          start of the record.
+        - A `datetime.datetime` object, representing an absolute date and
+          time (if the record starting time is known.)
+
+        Parameters
+        ----------
+        time_value : number or timedelta or datetime
+            A time value.
+
+        Returns
+        -------
+        elapsed_time : timedelta
+            Elapsed time from the start of the record.
+
+        """
+        time_value = self.get_frame_number(time_value)
+        return datetime.timedelta(seconds=time_value / self.fs)
+
+    def get_absolute_time(self, time_value):
+        """
+        Convert a time value to an absolute date and time.
+
+        A time value may be specified as:
+        - An integer or floating-point number, representing the number of
+          WFDB frames elapsed from the start of the record.
+        - A `datetime.timedelta` object, representing elapsed time from the
+          start of the record.
+        - A `datetime.datetime` object, representing an absolute date and
+          time (if the record starting time is known.)
+
+        Parameters
+        ----------
+        time_value : number or timedelta or datetime
+            A time value.
+
+        Returns
+        -------
+        absolute_time : datetime
+            Absolute date and time.
+
+        """
+        time_value = self.get_elapsed_time(time_value)
+        if not self.base_datetime:
+            raise ValueError(
+                "base_datetime is unknown; cannot convert frame number "
+                "to an absolute date/time"
+            )
+        return time_value + self.base_datetime
+
     def check_field(self, field, required_channels="all"):
         """
         Check whether a single field is valid in its basic form. Does