From 1828c6aee1f8a8531178ecdc1f2a839916302c3f Mon Sep 17 00:00:00 2001 From: Galen Lynch Date: Wed, 21 Oct 2026 09:03:33 -0700 Subject: [PATCH] feat: prefetch the next block while scrolling SpikeInterface traces Scrolling a remote or preprocessed recording stalls each time the window enters a block not yet computed. A read that continues the previous one now starts computing the next block in the direction of travel on a background thread. Reads that jump, such as waveform snippets, prefetch nothing and cancel pending prefetches, so random access does no extra work, and a requested block is computed in the calling thread rather than queued behind prefetches. A failed prefetch is dropped, so it does not make its block unreadable. close() stops the thread pool. benchmarks/benchmark_spikeinterface_reader.py, 384 channels at 30 kHz with 0.2 s latency plus 0.5 s per second of data per call: pattern prefetch total mean read reads > 0.1 s get_traces scroll off 13.78s 0.038s 6 6 scroll on 11.44s 0.014s 1 7 snippets off 47.38s 0.474s 100 102 snippets on 46.89s 0.469s 100 102 Scrolling is 100 steps of 10% of a 0.25 s window with 0.1 s pauses; the one slow read left is the first. Snippets are 100 reads of 82 samples. --- benchmarks/benchmark_spikeinterface_reader.py | 108 ++++++++++++++++++ phylib/io/tests/test_traces.py | 94 ++++++++++++++- phylib/io/traces.py | 84 ++++++++++++-- 3 files changed, 275 insertions(+), 11 deletions(-) create mode 100644 benchmarks/benchmark_spikeinterface_reader.py diff --git a/benchmarks/benchmark_spikeinterface_reader.py b/benchmarks/benchmark_spikeinterface_reader.py new file mode 100644 index 0000000..2ee18ee --- /dev/null +++ b/benchmarks/benchmark_spikeinterface_reader.py @@ -0,0 +1,108 @@ +"""Opt-in benchmark for ``SpikeInterfaceEphysReader`` prefetching. + +Run from the repository root, with spikeinterface installed, with:: + + python benchmarks/benchmark_spikeinterface_reader.py + +A stand-in recording sleeps for a fixed latency plus a cost per second of data, as a remote +preprocessed recording would. Two access patterns are timed with and without prefetching: +scrolling, which steps a trace window by 10% and pauses as a GUI would to draw it, and +waveform snippets at random times. The benchmark has no timing assertions. +""" + +import argparse +from pathlib import Path +import sys +from time import perf_counter, sleep + +import numpy as np + +# Make the documented direct invocation use the repository checkout. +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from phylib.io.traces import SpikeInterfaceEphysReader # noqa: E402 + + +class _SlowRecording: + def __init__(self, n_channels, sample_rate, latency, cost_per_second): + self.n_channels = n_channels + self.sample_rate = sample_rate + self.latency = latency + self.cost_per_second = cost_per_second + self.calls = 0 + self.seconds = 0. + + def get_traces(self, start_frame=None, end_frame=None, segment_index=0): + duration = (end_frame - start_frame) / self.sample_rate + self.calls += 1 + self.seconds += duration + sleep(self.latency + self.cost_per_second * duration) + return np.zeros((end_frame - start_frame, self.n_channels), dtype=np.float32) + + +def _reader(args, prefetch): + import spikeinterface as si + recording = si.generate_recording( + num_channels=args.n_channels, sampling_frequency=args.sample_rate, + durations=[args.duration]) + traces = SpikeInterfaceEphysReader(recording, prefetch=prefetch) + traces.recording = _SlowRecording( + args.n_channels, args.sample_rate, args.latency, args.cost_per_second) + return traces + + +def _scroll(traces, args): + window = int(.25 * args.sample_rate) + start = int(args.duration * args.sample_rate) // 3 + latencies = [] + for _ in range(args.steps): + t0 = perf_counter() + traces[start:start + window] + latencies.append(perf_counter() - t0) + sleep(args.pause) + start += window // 10 + return latencies + + +def _snippets(traces, args): + rng = np.random.default_rng(0) + n_samples = int(args.duration * args.sample_rate) + starts = np.sort(rng.integers(0, n_samples - 82, args.n_snippets)) + latencies = [] + for start in starts: + t0 = perf_counter() + traces[start:start + 82] + latencies.append(perf_counter() - t0) + return latencies + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--n-channels', type=int, default=384) + parser.add_argument('--sample-rate', type=float, default=30000.) + parser.add_argument('--duration', type=float, default=3600., help="seconds of data") + parser.add_argument('--latency', type=float, default=.2, help="seconds per get_traces call") + parser.add_argument( + '--cost-per-second', type=float, default=.5, help="seconds per second of data read") + parser.add_argument('--steps', type=int, default=100, help="scroll steps") + parser.add_argument('--pause', type=float, default=.1, help="seconds between scroll steps") + parser.add_argument('--n-snippets', type=int, default=100) + args = parser.parse_args() + + print("pattern prefetch total mean read reads > 0.1 s get_traces data computed") + for name, run in (('scroll', _scroll), ('snippets', _snippets)): + for prefetch in (False, True): + traces = _reader(args, prefetch) + t0 = perf_counter() + latencies = run(traces, args) + total = perf_counter() - t0 + slow = traces.recording + traces.close() + print( + f"{name:<10} {str(prefetch):<8} {total:>7.2f}s {np.mean(latencies):>8.3f}s " + f"{np.sum(np.array(latencies) > .1):>13} {slow.calls:>10} " + f"{slow.seconds:>11.1f}s") + + +if __name__ == '__main__': + main() diff --git a/phylib/io/tests/test_traces.py b/phylib/io/tests/test_traces.py index fced5d6..e914a9b 100644 --- a/phylib/io/tests/test_traces.py +++ b/phylib/io/tests/test_traces.py @@ -7,6 +7,7 @@ #------------------------------------------------------------------------------ import logging +import time import numpy as np from numpy.testing import assert_equal as ae @@ -591,7 +592,8 @@ def test_spikeinterface_reader_multi_segment(): def test_spikeinterface_reader_cache(si_recording): recording, arr = si_recording block_bytes = 300 * arr.shape[1] * arr.itemsize - traces = get_ephys_reader(recording, block_duration=.3, cache_size=2 * block_bytes) + traces = get_ephys_reader( + recording, block_duration=.3, cache_size=2 * block_bytes, prefetch=False) ae(traces[:], arr) assert list(traces._cache) == [6, 7] ae(traces[:10], arr[:10]) @@ -623,3 +625,93 @@ def test_spikeinterface_reader_params_mismatch(si_recording, caplog): assert all(name in messages for name in ('sample_rate', 'n_channels', 'dtype')) # The recording still sets the values. assert (traces.sample_rate, traces.n_channels, traces.dtype) == (1000., 7, np.int16) + + +class _SlowRecording(object): + """Stands in for a recording whose get_traces blocks, fails or counts calls.""" + + def __init__(self, recording, gate=None, fail=()): + self.recording = recording + self.gate = gate + self.fail = set(fail) + self.calls = [] + + def get_traces(self, start_frame=None, end_frame=None, segment_index=0): + self.calls.append(start_frame) + if self.gate is not None and start_frame in self.gate: + self.gate[start_frame].wait(5) + if start_frame in self.fail: + self.fail.discard(start_frame) + raise OSError("transient") + return self.recording.get_traces( + start_frame=start_frame, end_frame=end_frame, segment_index=segment_index) + + +def _wait_prefetches(traces): + with traces._lock: + futures = list(traces._pending.values()) + for future in futures: + try: + future.result(5) + except Exception: + pass + # Callbacks may still be moving results into the cache. + for _ in range(100): + if not traces._pending: + break + time.sleep(.01) + + +def test_spikeinterface_reader_prefetch(si_recording): + recording, arr = si_recording + traces = get_ephys_reader(recording, block_duration=.3) + traces.recording = slow = _SlowRecording(recording) + + # A first read, or a jump, prefetches nothing. + ae(traces[1000:1100], arr[1000:1100]) + _wait_prefetches(traces) + assert slow.calls == [900] + + # Scrolling right prefetches the next block, scrolling left the previous one. + ae(traces[1050:1150], arr[1050:1150]) + _wait_prefetches(traces) + assert sorted(traces._cache) == [3, 4] + ae(traces[950:1050], arr[950:1050]) + _wait_prefetches(traces) + assert sorted(traces._cache) == [2, 3, 4] + # Block 4 comes from the cache, and the read continues to the right. + ae(traces[1200:1300], arr[1200:1300]) + _wait_prefetches(traces) + assert slow.calls == [900, 1200, 600, 1500] + traces.close() + + +def test_spikeinterface_reader_prefetch_failure(si_recording): + recording, arr = si_recording + traces = get_ephys_reader(recording, block_duration=.3) + traces.recording = _SlowRecording(recording, fail={1200}) + traces[1000:1100] + traces[1050:1150] # prefetches block 4, which fails + _wait_prefetches(traces) + assert 4 not in traces._cache + ae(traces[1200:1300], arr[1200:1300]) + traces.close() + + +def test_spikeinterface_reader_demand_not_queued(si_recording): + import threading + recording, arr = si_recording + traces = get_ephys_reader(recording, block_duration=.3) + gate = {1200: threading.Event()} + traces.recording = _SlowRecording(recording, gate=gate) + traces[1000:1100] + traces[1050:1150] # the prefetch of block 4 holds the only worker + # A jump is computed in this thread, not behind the prefetch. + ae(traces[2000:2100], arr[2000:2100]) + assert 4 in traces._pending + gate[1200].set() + _wait_prefetches(traces) + traces.close() + assert traces._pool._shutdown + # Reads after close are computed directly. + ae(traces[0:10], arr[0:10]) diff --git a/phylib/io/traces.py b/phylib/io/traces.py index c74b609..fe8dcc0 100644 --- a/phylib/io/traces.py +++ b/phylib/io/traces.py @@ -10,7 +10,8 @@ import copy import logging from collections import OrderedDict -from functools import reduce +from concurrent.futures import ThreadPoolExecutor +from functools import partial, reduce from math import ceil import multiprocessing as mp from operator import mul @@ -457,11 +458,18 @@ class SpikeInterfaceEphysReader(BaseEphysReader): They are computed in blocks of `block_duration` seconds, and the most recently used blocks are cached, up to `cache_size` bytes, since computing a block can be slow. + With `prefetch`, a read that continues the previous one, as scrolling does, also starts + computing the next block in the direction of travel on a background thread. Other reads + never prefetch and cancel pending prefetches, and a requested block is computed in the + calling thread rather than queued behind prefetches. + The recording sets the sample rate, channel count and dtype. Values passed from params.py are only checked against it, since phy computes trace windows with its own. """ - def __init__(self, recording, block_duration=0.5, cache_size=256 * 1024 ** 2, **kwargs): + def __init__( + self, recording, block_duration=0.5, cache_size=256 * 1024 ** 2, prefetch=True, + **kwargs): super(SpikeInterfaceEphysReader, self).__init__() if isinstance(recording, (tuple, list)): if len(recording) != 1: @@ -489,9 +497,13 @@ def __init__(self, recording, block_duration=0.5, cache_size=256 * 1024 ** 2, ** self._block_size = max(1, int(round(block_duration * self.sample_rate))) block_bytes = self._block_size * max(1, self.n_channels) * self.dtype.itemsize self._n_cached_blocks = max(1, cache_size // block_bytes) + self._n_blocks = int(ceil(n_samples / self._block_size)) # Shared by the clones that lazy operations make, so they share one cache. self._cache = OrderedDict() # block index => traces of the block + self._pending = {} # block index => Future of a prefetch + self._state = {'last_read': None, 'closed': False} self._lock = threading.Lock() + self._pool = ThreadPoolExecutor(max_workers=1) if prefetch else None def _check_params(self, kwargs): n_channels = kwargs.get('n_channels', kwargs.get('n_channels_dat')) @@ -511,26 +523,74 @@ def _check_params(self, kwargs): if kwargs.get('offset'): logger.warning("The params offset is ignored for a SpikeInterface recording.") - def _block(self, i): - with self._lock: - block = self._cache.get(i) - if block is not None: - self._cache.move_to_end(i) - return block + def _compute(self, i): start = i * self._block_size stop = min(start + self._block_size, self.part_bounds[-1]) - block = self.recording.get_traces(start_frame=start, end_frame=stop, segment_index=0) + return self.recording.get_traces(start_frame=start, end_frame=stop, segment_index=0) + + def _store(self, i, block): with self._lock: self._cache[i] = block while len(self._cache) > self._n_cached_blocks: self._cache.popitem(last=False) + + def _block(self, i): + with self._lock: + block = self._cache.get(i) + if block is not None: + self._cache.move_to_end(i) + return block + future = self._pending.get(i) + # A prefetch that has started is nearer done than a new computation would be. + if future is not None and not future.cancel(): + try: + return future.result() + except Exception: # computed again below, so one failure does not stick + pass + block = self._compute(i) + self._store(i, block) return block + def _prefetched(self, i, future): + with self._lock: + if self._pending.get(i) is future: + del self._pending[i] + # A failed prefetch is dropped, so the next read of the block computes it again. + if not self._state['closed'] and not future.cancelled() and future.exception() is None: + self._store(i, future.result()) + + def _prefetch(self, i): + if self._pool is None or self._state['closed'] or not 0 <= i < self._n_blocks: + return + with self._lock: + if i in self._cache or i in self._pending: + return + future = self._pool.submit(self._compute, i) + self._pending[i] = future + # Outside the lock: the callback takes it, and runs here if the future is already done. + future.add_done_callback(partial(self._prefetched, i)) + + def _cancel_prefetches(self): + with self._lock: + futures = list(self._pending.values()) + for future in futures: + future.cancel() + def _read(self, start, stop): if stop <= start: return np.zeros((0, self.n_channels), dtype=self.dtype) bs = self._block_size b0, b1 = start // bs, (stop - 1) // bs + last = self._state['last_read'] + self._state['last_read'] = (start, stop) + # Continues the previous read when it overlaps it or lies within a block of it. + if last is not None and start <= last[1] + bs and stop >= last[0] - bs: + if start >= last[0]: + self._prefetch(b1 + 1) + if start <= last[0]: + self._prefetch(b0 - 1) + else: + self._cancel_prefetches() out = np.concatenate([self._block(i) for i in range(b0, b1 + 1)], axis=0) return out[start - b0 * bs:stop - b0 * bs] @@ -548,8 +608,12 @@ def _get_part(self, part_idx, subitem): return out def close(self): - """Drop the cached blocks.""" + """Stop prefetching and drop the cached blocks; later reads are computed directly.""" + self._state['closed'] = True + if self._pool is not None: + self._pool.shutdown(wait=False, cancel_futures=True) with self._lock: + self._pending.clear() self._cache.clear()