Merge branch 'master' into release-14.4

Author: alejoe91

.gitignore

@@ -80,4 +80,6 @@ doc/*.nwb
 *.plx
 *.smr
 B95.zip
-grouped_ephys
+grouped_ephys
+uv.lock
+.venv

neo/rawio/blackrockrawio.py

@@ -667,6 +667,68 @@ def _get_analogsignal_chunk(self, block_index, seg_index, i_start, i_stop, strea
         sig_chunk = memmap_data[i_start:i_stop, channel_indexes]
         return sig_chunk
 
+    def _get_blackrock_timestamps(self, block_index, seg_index, i_start, i_stop, stream_index):
+        """
+        Return timestamps in seconds for analog signal samples in the given range.
+
+        The behavior depends on the file format:
+
+        - **PTP format (FileSpec 3.0-ptp):** Each packet in the file contains
+          exactly one sample with its own PTP hardware timestamp at nanosecond
+          resolution. This method returns those actual timestamps converted to
+          seconds. Because each NSx file (e.g. ns2 at 1kHz, ns6 at 30kHz) stores
+          its own independent PTP packets, every sample has a real timestamp.
+          Note that PTP timestamps exhibit natural clock jitter at the
+          nanosecond scale, so consecutive sample intervals are not perfectly
+          uniform.
+
+        - **Standard formats (FileSpec 2.2, 2.3, 3.0 non-PTP):** Each data
+          block has a single scalar timestamp for its first sample. All
+          subsequent samples within the block are interpolated as
+          ``t_start + sample_index / sampling_rate``, assuming uniform spacing.
+
+        - **FileSpec 2.1:** No timestamps are stored in the file. All samples
+          are interpolated from ``t_start=0`` using the sampling rate.
+
+        Parameters
+        ----------
+        block_index : int
+            Block index.
+        seg_index : int
+            Segment index.
+        i_start : int | None
+            First sample index. None means 0.
+        i_stop : int | None
+            Stop sample index (exclusive). None means end of segment.
+        stream_index : int
+            Stream index.
+
+        Returns
+        -------
+        timestamps : np.ndarray (float64)
+            Timestamps in seconds for each sample in [i_start, i_stop).
+        """
+        stream_id = self.header["signal_streams"][stream_index]["id"]
+        nsx_nb = int(stream_id)
+
+        # Resolve None to concrete indices
+        size = self.nsx_datas[nsx_nb][seg_index].shape[0]
+        i_start = i_start if i_start is not None else 0
+        i_stop = i_stop if i_stop is not None else size
+
+        # Check if this segment has per-sample timestamps (PTP format)
+        raw_timestamps = self._nsx_data_header[nsx_nb][seg_index]["timestamp"]
+
+        if isinstance(raw_timestamps, np.ndarray) and raw_timestamps.size == size:
+            # PTP: real hardware timestamps
+            ts_res = float(self._nsx_basic_header[nsx_nb]["timestamp_resolution"])
+            return raw_timestamps[i_start:i_stop].astype("float64") / ts_res
+        else:
+            # Non-PTP: reconstruct from t_start + index / sampling_rate
+            t_start = self._sigs_t_starts[nsx_nb][seg_index]
+            sr = self._nsx_sampling_frequency[nsx_nb]
+            return t_start + np.arange(i_start, i_stop, dtype="float64") / sr
+
     def _spike_count(self, block_index, seg_index, unit_index):
         channel_id, unit_id = self.internal_unit_ids[unit_index]
 

neo/rawio/tdtrawio.py

@@ -283,11 +283,17 @@ def _parse_header(self):
                             raise ValueError("Dtype is changing!!")
 
                     # data buffer test if SEV file exists otherwise TEV
-                    # path = self.dirname / segment_name
                     if self.tdt_block_mode == "multi":
                         # for multi block datasets the names of sev files are fixed
-                        sev_stem = f"{tankname}_{segment_name}_{stream_name}_ch{chan_id}"
-                        sev_filename = (path / sev_stem).with_suffix(".sev")
+                        block_path = self.dirname / segment_name
+                        sev_regex = f"{tankname}_{segment_name}_{stream_name}_[cC]h{chan_id}.sev"
+                        sev_filename = list(block_path.glob(sev_regex))
+                        if len(sev_filename) == 1:
+                            sev_filename = sev_filename[0]
+                        elif len(sev_filename) == 0:
+                            sev_filename = None  # Indirect flag for TEV Format, see issue 1087
+                        else:
+                            raise ValueError(f"Multiple SEV files matched for channel {chan_id}: {sev_filename}")
                     else:
                         # for single block datasets the exact name of sev files is not known
                         sev_regex = f"*_[cC]h{chan_id}.sev"

neo/test/rawiotest/test_blackrockrawio.py

@@ -211,6 +211,137 @@ def test_blackrockrawio_ptp_timestamps(self):
         # Spikes enabled on channels 1-129 but channel 129 had 0 events.
         self.assertEqual(128, reader.spike_channels_count())
 
+    def test_get_blackrock_timestamps_reconstruction(self):
+        """Test _get_blackrock_timestamps for non-PTP formats (reconstructed from t_start + rate)."""
+        reader = BlackrockRawIO(filename=self.get_local_path("blackrock/FileSpec2.3001"))
+        reader.parse_header()
+
+        stream_index = 0
+        size = reader.get_signal_size(0, 0, stream_index)
+        sr = reader.get_signal_sampling_rate(stream_index)
+        t_start = reader.get_signal_t_start(0, 0, stream_index)
+
+        # Full segment timestamps
+        timestamps = reader._get_blackrock_timestamps(0, 0, None, None, stream_index)
+        self.assertEqual(timestamps.shape[0], size)
+        self.assertEqual(timestamps.dtype, np.float64)
+
+        # Verify reconstruction: t_start + index / sr
+        expected = t_start + np.arange(size, dtype="float64") / sr
+        np.testing.assert_allclose(timestamps, expected)
+
+    def test_get_blackrock_timestamps_ptp(self):
+        """Test _get_blackrock_timestamps for PTP format (real hardware timestamps)."""
+        dirname = self.get_local_path("blackrock/blackrock_3_0_ptp/20231027-125608-001")
+        reader = BlackrockRawIO(filename=dirname)
+        reader.parse_header()
+
+        nanoseconds_per_second = 1_000_000_000.0
+
+        # ns2 stream (stream_index=0, 1 kHz)
+        stream_index = 0
+        timestamps = reader._get_blackrock_timestamps(0, 0, None, None, stream_index)
+        self.assertEqual(timestamps.shape[0], reader.get_signal_size(0, 0, stream_index))
+        self.assertEqual(timestamps.dtype, np.float64)
+
+        # First 5 PTP clock values (nanoseconds since Unix epoch) read directly from the ns2 file and hardcoded here for testing
+        ptp_clock_ns_ns2 = np.array(
+            [1688252801327128558, 1688252801328128518, 1688252801329128718, 1688252801330128558, 1688252801331128518],
+            dtype="uint64",
+        )
+        expected_ns2 = ptp_clock_ns_ns2.astype("float64") / nanoseconds_per_second
+        np.testing.assert_array_equal(timestamps[:5], expected_ns2)
+
+        # ns6 stream (stream_index=1, 30 kHz) — different sampling rate, different timestamps
+        stream_index = 1
+        timestamps_ns6 = reader._get_blackrock_timestamps(0, 0, None, None, stream_index)
+        self.assertEqual(timestamps_ns6.shape[0], reader.get_signal_size(0, 0, stream_index))
+        self.assertEqual(timestamps_ns6.dtype, np.float64)
+
+        # First 5 PTP clock values (nanoseconds since Unix epoch) read directly from the ns6 file and hardcoded here for testing
+        ptp_clock_ns_ns6 = np.array(
+            [1688252801327328740, 1688252801327361940, 1688252801327395260, 1688252801327428620, 1688252801327461940],
+            dtype="uint64",
+        )
+        expected_ns6 = ptp_clock_ns_ns6.astype("float64") / nanoseconds_per_second
+        np.testing.assert_array_equal(timestamps_ns6[:5], expected_ns6)
+
+    def test_get_blackrock_timestamps_ptp_with_gaps(self):
+        """Test _get_blackrock_timestamps for PTP format with gaps and multiple segments."""
+        dirname = self.get_local_path("blackrock/blackrock_ptp_with_missing_samples/Hub1-NWBtestfile_neural_wspikes")
+        gap_tolerance_ms = 0.5
+        reader = BlackrockRawIO(filename=dirname, nsx_to_load=6, gap_tolerance_ms=gap_tolerance_ms)
+        reader.parse_header()
+
+        n_segments = reader.segment_count(0)
+        self.assertEqual(n_segments, 3)
+
+        nanoseconds_per_second = 1_000_000_000.0
+
+        # This file has a single stream: ns6 (30 kHz, 1 channel)
+        stream_index = 0
+        expected_sizes = [632, 58, 310]
+
+        # First 5 PTP clock values (nanoseconds since Unix epoch) per segment, read directly from file and hardcoded here for testing
+        first_5_ptp_clock_ns_per_segment = [
+            np.array(
+                [
+                    1752531864717743037,
+                    1752531864717776237,
+                    1752531864717809677,
+                    1752531864717843077,
+                    1752531864717876277,
+                ],
+                dtype="uint64",
+            ),
+            np.array(
+                [
+                    1752531864739742985,
+                    1752531864739776305,
+                    1752531864739809665,
+                    1752531864739842945,
+                    1752531864739876385,
+                ],
+                dtype="uint64",
+            ),
+            np.array(
+                [
+                    1752531864740742986,
+                    1752531864740776306,
+                    1752531864740809626,
+                    1752531864740842946,
+                    1752531864740876346,
+                ],
+                dtype="uint64",
+            ),
+        ]
+        # Last PTP clock value (nanoseconds since Unix epoch) of each segment, hardcoded here for testing
+        last_ptp_clock_ns_per_segment = np.array(
+            [1752531864738776304, 1752531864739709625, 1752531864751042999],
+            dtype="uint64",
+        )
+
+        for seg_index in range(n_segments):
+            timestamps = reader._get_blackrock_timestamps(0, seg_index, None, None, stream_index)
+            self.assertEqual(timestamps.shape[0], expected_sizes[seg_index])
+
+            # Verify first 5 timestamps match the clock values from the file
+            expected_first_5 = first_5_ptp_clock_ns_per_segment[seg_index].astype("float64") / nanoseconds_per_second
+            np.testing.assert_array_equal(timestamps[:5], expected_first_5)
+
+            # Verify last timestamp
+            expected_last = last_ptp_clock_ns_per_segment[seg_index].astype("float64") / nanoseconds_per_second
+            np.testing.assert_array_equal(timestamps[-1], expected_last)
+
+        # Verify the gaps between segments exceed the tolerance
+        for seg_index in range(n_segments - 1):
+            last_ts = last_ptp_clock_ns_per_segment[seg_index].astype("float64") / nanoseconds_per_second
+            first_ts_next = (
+                first_5_ptp_clock_ns_per_segment[seg_index + 1][0].astype("float64") / nanoseconds_per_second
+            )
+            gap_ms = (first_ts_next - last_ts) * 1000
+            self.assertGreater(gap_ms, gap_tolerance_ms)
+
     def test_gap_tolerance_ms_parameter(self):
         """
         Test gap_tolerance_ms parameter for gap handling with files that have actual gaps.