[h-mayorquin]

Right now a standard-format Blackrock file (spec 2.2, 2.3 and 3.0) gets one segment per data block and gap_tolerance_ms is accepted but ignored. Files can arrive split into hundreds of segments this way (the recording in SpikeInterface #2306 loads as 280 blocks in its ns2 and 387 in its ns5). This PR extends gap_tolerance_ms, which already works for PTP (Precision Time Protocol) files since #1789, to the standard formats. The gaps are detected between the block timestamps and by default the reader throws an error with a gap report. gap_tolerance_ms=0 keeps every block as its own segment, as before, and a larger value merges the blocks whose gap is below it.

Some choices to discuss:

• In the standard formats, a block that starts before the previous one ends (a clock reset) has no duration to compare with a tolerance, so it always starts a new segment with a warning, as every block already did. Whether a reset should start a new block instead is the question in Are the segments of a block ordered in time? #1937 and this PR does not change it. Backward steps between PTP samples stay as they are on master: they come from packets written out of order, and how to handle them is also being discussed in Are the segments of a block ordered in time? #1937.
• After a merged gap, t_start + index / sampling_rate places the samples earlier than they were recorded, by the length of the gap. _get_blackrock_timestamps keeps returning the recorded times whatever the tolerance.
• This is a breaking change: a multi-block standard file that used to load now throws an error unless a tolerance is given. I did this on purpose so gap_tolerance_ms=None means the same for every Blackrock variant, as it already does for PTP files.

I also tested this against the new example datasets on gin (https://gin.g-node.org/NeuralEnsemble/ephy_testing_data/pulls/192) and fixed two problems they showed. Empty blocks (0 samples, some with a placeholder timestamp) are now left out of the gap detection, and matching a spec 2.3 nev to a merged segment now uses the end of its last block. Files whose nev and nsX disagree on their segments (for example three_data_blocks with gap_tolerance_ms=0) still fail as on master, as that comes from _match_nsx_and_nev_segment_ids and is a separate problem.

[cboulay]

Thanks Heberto, I like where this lands: gap_tolerance_ms means the same thing for every Blackrock variant, and _segment_nsx is split into per-format segmenters. It also fixes three_data_blocks / ten_data_blocks_with_millisecond_gaps at a large tolerance. I ran it on all 53 gin Blackrock sets at None, 0 and 1e6 against master, and on a couple of our spec 3.0 PTP recordings. Two bugs and one memory concern before I'd approve:

1. _read_multi_block_chunk doesn't clamp i_stop. On two_data_blocks_after_pause merged into one 200-sample segment, get_analogsignal_chunk(0, 0, 50, 250) returns 200 rows, and the last 50 come from np.empty. A range inside one block returns a shorter slice, as before.
2. An nsX with only empty blocks raises IndexError at block_infos[0]. I made one from a basic header plus a single 0-point data header. On master it loads with 0 segments.
3. In the PTP path, last_sample_indices and last_sample_positions are built for every sample just to describe the few gaps. Peak memory in parse_header goes from about 17 to 34 bytes per sample (tracemalloc on a 1.1 M-sample file), which matters for large PTP files on small cloud runners. Could _classify_gaps return the forward gap indices and let each caller build the report only for those? That would also let a segmenter drop gaps it knows are harmless before deciding whether to raise. That's exactly what packets written out of order need (#1937).

Two smaller points:

• gap_tolerance_ms=0 isn't quite "every block its own segment": blocks ≤ 2 periods apart still merge. So one_sample_blocks gives 101-sample segments starting one tick earlier, where master gave 100. I think that's fine, but the description and docstring should say so.
• On the default: every paused 2.2/2.3 file in gin now raises out of the box, which will reach SpikeInterface users quickly. Would you consider a release where None still splits at every block and emits a FutureWarning naming gap_tolerance_ms, before switching to the error?

On our spec 3.0 test recording (signal generator, linked in #1924) the PTP behaviour matches master, as the description says. With the reordered copy, the default raises on the out-of-order packets, and gap_tolerance_ms=0 produces 52- and 3-sample segments around them. That's the #1937 case, not a regression here.

Line notes

• neo/rawio/blackrockrawio.py:794: i_stop past the end of the segment leaves rows of out uninitialized when the range spans more than one block, while a single-block range returns fewer rows instead. Suggest i_stop = total_samples if i_stop is None else min(i_stop, total_samples). A regression test would be cheap: two_data_blocks_after_pause with a large tolerance and i_stop = size + 50.
• neo/rawio/blackrockrawio.py:1634: If every block is empty this list is empty, and block_infos[0] at 1681 raises IndexError. Master returned 0 segments here; an early return [] would restore that.
• neo/rawio/blackrockrawio.py:1722: These two N-length arrays, plus the float64 copy and diff above, double peak memory for large PTP files, but they're only needed at the gap indices. Could _classify_gaps return forward gap indices and the caller build the report from timestamps[idx]? Doing the diff on the integer ticks rather than float seconds would also save a copy.
• neo/rawio/blackrockrawio.py:1582: Raising here means a caller can't remove gaps it knows are benign before the error. Splitting "find gaps" from "raise / apply tolerance" would make that possible; the out-of-order packets in #1937 are the case I have in mind.
• neo/rawio/blackrockrawio.py:129: This note says pauses in 2.2/2.3 are split into segments automatically, which is no longer true by default. Could it point to gap_tolerance_ms?
• neo/rawio/blackrockrawio.py:125: Worth documenting here three things: a non-zero tolerance places samples after a merged gap early under t_start + i / sampling_rate; _get_blackrock_timestamps keeps the recorded times; and 0 still merges blocks closer than 2 sampling periods.

[h-mayorquin]

Thanks for the review,

1. I fixed the bug that extracted values outside of the segment. There is a test for this now.
2. I am not sure this is the right behavior but I changed the code so this keeps doing what master does.
3. Yes, I refactor this part of the code so only what needs reported gets loaded. Thanks for taking a look at this.

On your two smaller points:
The docstrings are fixed and I have added a deprecation period for the change of behavior. The deprecation will be a future warning for 0.16 which carries the report already so useres will get information about the temporal structure of their samples as soon as possible but not a breaking change.