Expose information about clock segments

Author: jamieforth

src/pyxdf/pyxdf.py

@@ -64,6 +64,9 @@ def __init__(self, xml, stream_id):
         # list of segments corresponding to detected time-stamp breaks
         # (each a tuple of start_idx, end_idx)
         self.segments = []
+        # list of segments corresponding to detected clock resets (each
+        # a tuple of start_idx, end_idx)
+        self.clock_segments = []
         # pre-calc some parsing parameters for efficiency
         if self.fmt != "string":
             self.dtype = np.dtype(fmts[self.fmt])
@@ -396,9 +399,15 @@ def load_xdf(
                 "Using the 'stream_id' value {} from the beginning of the StreamHeader "
                 "chunk instead.".format(stream["info"]["stream_id"], k)
             )
+        if synchronize_clocks:
+            if tmp.segments != tmp.clock_segments:
+                logger.warning(
+                    f"Stream {tmp.stream_id}: Segments and clock-segments differ"
+                )
         stream["info"]["stream_id"] = k
         stream["info"]["effective_srate"] = tmp.effective_srate
         stream["info"]["segments"] = tmp.segments
+        stream["info"]["clock_segments"] = tmp.clock_segments
         stream["time_series"] = tmp.time_series
         stream["time_stamps"] = tmp.time_stamps
         stream["clock_times"] = tmp.clock_times
@@ -677,6 +686,9 @@ def _clock_sync(
             # Apply the correction to all time-stamps
             if len(ranges) == 1:
                 stream.time_stamps += coef[0][0] + (coef[0][1] * stream.time_stamps)
+                stream.clock_segments.append(
+                    (0, len(stream.time_stamps) - 1)  # inclusive
+                )
             else:
                 # Assumes time-stamps are monotonically increasing.
                 ts_start = 0
@@ -702,6 +714,7 @@ def _clock_sync(
                     else:
                         # Include all time-stamps from the last break until the end.
                         ts_stop = len(stream.time_stamps)
+                    stream.clock_segments.append((ts_start, ts_stop - 1))
                     ts_slice = slice(ts_start, ts_stop)
                     ts_start = ts_stop
                     stream.time_stamps[ts_slice] += (

test/mock_data_stream.py

@@ -62,6 +62,7 @@ def __init__(
         self.clock_times = clock_times
         self.clock_values = clock_values
         self.segments = []
+        self.clock_segments = []
 
 
 def test_mock_stream_default_timeseries_num():

test/test_clock_sync.py

@@ -31,6 +31,7 @@ def test_sync_empty_stream(n_clock_offsets, handle_clock_resets):
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, [])
 
 
 @pytest.mark.parametrize("n_time_stamps", list(range(0, 5)))
@@ -55,6 +56,7 @@ def test_sync_empty_offsets(n_time_stamps, handle_clock_resets):
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, [])
 
 
 @pytest.mark.parametrize("n_clock_offsets", list(range(2, 5)))
@@ -87,6 +89,7 @@ def test_sync_no_resets(n_clock_offsets, clock_value, handle_clock_resets):
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, [(0, len(time_stamps) - 1)])
 
 
 @pytest.mark.parametrize("n_clock_offsets", list(range(2, 4)))
@@ -119,6 +122,7 @@ def test_sync_no_resets_bounds(n_clock_offsets, clock_value, handle_clock_resets
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, [(0, len(time_stamps) - 1)])
 
 
 @pytest.mark.parametrize("n_clock_offsets", list(range(2, 4)))
@@ -165,6 +169,7 @@ def test_sync_no_resets_bounds_jitter(
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, [(0, len(time_stamps) - 1)])
 
 
 # Clock resets.
@@ -191,6 +196,13 @@ def test_sync_clock_jumps_forward_break_at_reset():
         expected,
         atol=1e-13,
     )
+    np.testing.assert_equal(
+        streams[1].clock_segments,
+        [
+            (0, 4),
+            (5, 9),
+        ],
+    )
 
 
 def test_sync_clock_jumps_forward_break_between_reset():
@@ -214,6 +226,13 @@ def test_sync_clock_jumps_forward_break_between_reset():
         expected,
         atol=1e-13,
     )
+    np.testing.assert_equal(
+        streams[1].clock_segments,
+        [
+            (0, 7),
+            (8, 15),
+        ],
+    )
 
 
 def test_sync_clock_jumps_backward_break_at_reset():
@@ -237,6 +256,13 @@ def test_sync_clock_jumps_backward_break_at_reset():
         expected,
         atol=1e-13,
     )
+    np.testing.assert_equal(
+        streams[1].clock_segments,
+        [
+            (0, 4),
+            (5, 9),
+        ],
+    )
 
 
 def test_sync_clock_jumps_backward_break_between_reset():
@@ -260,6 +286,13 @@ def test_sync_clock_jumps_backward_break_between_reset():
         expected,
         atol=1e-13,
     )
+    np.testing.assert_equal(
+        streams[1].clock_segments,
+        [
+            (0, 7),
+            (8, 15),
+        ],
+    )
 
 
 @pytest.mark.parametrize(
@@ -296,9 +329,16 @@ def test_sync_clock_jumps_forward_tdiffs(clock_offsets, tdiff, clock_tdiff):
     time_stamps = np.hstack(
         [np.arange(start, stop, tdiff) for start, stop in clock_reset_times]
     )
-    expected = np.hstack(
-        [np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range]
-    )
+    expected = [
+        np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range
+    ]
+    expected_clock_segments = []
+    seg_start_idx = 0
+    for segment in expected:
+        seg_end_idx = seg_start_idx + len(segment) - 1
+        expected_clock_segments.append((seg_start_idx, seg_end_idx))
+        seg_start_idx = seg_end_idx + 1
+    expected = np.hstack(expected)
     streams = {
         1: MockStreamData(
             time_stamps=time_stamps,
@@ -318,6 +358,7 @@ def test_sync_clock_jumps_forward_tdiffs(clock_offsets, tdiff, clock_tdiff):
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, expected_clock_segments)
 
 
 @pytest.mark.parametrize(
@@ -354,9 +395,16 @@ def test_sync_clock_jumps_backward_tdiffs(clock_offsets, tdiff, clock_tdiff):
     time_stamps = np.hstack(
         [np.arange(start, stop, tdiff) for start, stop in clock_reset_times]
     )
-    expected = np.hstack(
-        [np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range]
-    )
+    expected = [
+        np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range
+    ]
+    expected_clock_segments = []
+    seg_start_idx = 0
+    for segment in expected:
+        seg_end_idx = seg_start_idx + len(segment) - 1
+        expected_clock_segments.append((seg_start_idx, seg_end_idx))
+        seg_start_idx = seg_end_idx + 1
+    expected = np.hstack(expected)
     streams = {
         1: MockStreamData(
             time_stamps=time_stamps,
@@ -375,6 +423,7 @@ def test_sync_clock_jumps_backward_tdiffs(clock_offsets, tdiff, clock_tdiff):
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, expected_clock_segments)
 
 
 @pytest.mark.parametrize(
@@ -411,9 +460,16 @@ def test_sync_clock_jumps_forward_backward_tdiffs(clock_offsets, tdiff, clock_td
     time_stamps = np.hstack(
         [np.arange(start, stop, tdiff) for start, stop in clock_reset_times]
     )
-    expected = np.hstack(
-        [np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range]
-    )
+    expected = [
+        np.arange(0, clock_tdiff * offsets, tdiff) for offsets in offsets_per_range
+    ]
+    expected_clock_segments = []
+    seg_start_idx = 0
+    for segment in expected:
+        seg_end_idx = seg_start_idx + len(segment) - 1
+        expected_clock_segments.append((seg_start_idx, seg_end_idx))
+        seg_start_idx = seg_end_idx + 1
+    expected = np.hstack(expected)
     streams = {
         1: MockStreamData(
             time_stamps=time_stamps,
@@ -433,3 +489,4 @@ def test_sync_clock_jumps_forward_backward_tdiffs(clock_offsets, tdiff, clock_td
     np.testing.assert_equal(streams[1].time_series[:, 0], time_stamps)
     np.testing.assert_equal(streams[1].clock_times, clock_times)
     np.testing.assert_equal(streams[1].clock_values, clock_values)
+    np.testing.assert_equal(streams[1].clock_segments, expected_clock_segments)

test/test_data.py

@@ -37,6 +37,7 @@ def test_minimal_file():
     assert streams[0]["info"]["channel_format"][0] == "int16"
     assert streams[0]["info"]["stream_id"] == 0
     assert streams[0]["info"]["segments"] == [(0, 8)]
+    assert streams[0]["info"]["clock_segments"] == [(0, 8)]
 
     s = np.array(
         [
@@ -101,17 +102,19 @@ def test_minimal_file():
         path, jitter_break_threshold_seconds=0.001, jitter_break_threshold_samples=1
     )
     assert streams[0]["info"]["segments"] == [(0, 0), (1, 3), (4, 8)]
+    assert streams[0]["info"]["clock_segments"] == [(0, 8)]
 
 
 @pytest.mark.parametrize("dejitter_timestamps", [False, True])
-def test_empty_streams_file(dejitter_timestamps):
+@pytest.mark.parametrize("synchronize_clocks", [False, True])
+def test_empty_streams_file(synchronize_clocks, dejitter_timestamps):
     path = Path("example-files/data_with_empty_streams.xdf")
     if not path.exists():
         pytest.skip(f"File not available: {path}.")
 
     streams, header = load_xdf(
         path,
-        synchronize_clocks=False,
+        synchronize_clocks=synchronize_clocks,
         dejitter_timestamps=dejitter_timestamps,
     )
 
@@ -127,6 +130,9 @@ def test_empty_streams_file(dejitter_timestamps):
     assert streams[1]["info"]["nominal_srate"][0] == "1.000000000000000"
     assert streams[1]["info"]["stream_id"] == 1
     assert streams[1]["info"]["segments"] == [(0, 9)]
+    assert streams[1]["info"]["clock_segments"] == (
+        [(0, 9)] if synchronize_clocks else []
+    )
 
     s = np.array([[0], [1], [2], [3], [4], [5], [6], [7], [8], [9]], dtype=np.int32)
     t = np.array(
@@ -155,6 +161,7 @@ def test_empty_streams_file(dejitter_timestamps):
     assert streams[0]["info"]["nominal_srate"][0] == "1.000000000000000"
     assert streams[0]["info"]["stream_id"] == 2
     assert streams[0]["info"]["segments"] == []
+    assert streams[0]["info"]["clock_segments"] == []
 
     s = np.zeros((0, 1), dtype=np.int32)
     t = np.array([], dtype=np.float64)
@@ -186,6 +193,9 @@ def test_empty_streams_file(dejitter_timestamps):
     assert streams[3]["info"]["channel_format"][0] == "string"
     assert streams[3]["info"]["stream_id"] == 4
     assert streams[3]["info"]["segments"] == [(0, 0)]
+    assert streams[3]["info"]["clock_segments"] == (
+        [(0, 0)] if synchronize_clocks else []
+    )
 
     s = [['{"state": 2}']]
     t = np.array([401340.59709634])