radiens_qc.events

Fetch every threshold crossing in a recording, for the events-in-time figures.

Distinct from :mod:radiens_qc.raw, which reads bounded excerpts. The questions this level answers -- does activity start or stop mid-recording, is a burst array-wide or local, is this bursty or continuous -- are all statements about the recording's span, and none of them is answerable from three one-second windows. So the whole event stream is read, and the object holding it is organized around the span rather than around excerpts.

The crossings come from a detect-only fileset the caller produced; see :mod:radiens_qc.spikes for how, and for why a clustered sort will not do.

Nothing here is archived on a :class:~radiens_qc.report.QualityReport, for the same reason an excerpt is not: a report is a measurement the KPI pass produced, while this is a view into the recording, fetched when a figure is drawn.

Classes

EventTrains dataclass

Every threshold crossing in one recording, per channel.

Attributes:

Name	Type	Description
base_name	str	Recording identifier.
sampling_rate	float	Sampling rate in Hz.
time_range_sec	tuple[float, float]	(start, end) on the dataset's own time base, which does not generally start at zero.
channel_indices	tuple[int, ...]	Amplifier ntv_idx values read, ascending.
geometry	DataFrame	Per-channel probe geometry, indexed by ntv_idx.
crossings	dict[int, NDArray[float64]]	ntv_idx -> crossing times in seconds on that same time base. A channel that never fired is absent rather than empty, which is why :meth:times exists.
detection	ResolvedDetection	Stage-2 filters and threshold the crossings were found at.
spikes_id	str	Fileset the crossings were read from. Carried so a caller wanting waveforms for these same events reads the fileset that produced them rather than whichever the dataset offers by default.

Attributes

num_events property

num_events

Total crossings across every channel.

Methods:

depth_order

depth_order()

Row order for the raster: shank, then depth.

See :func:~radiens_qc._dataset.depth_order. This level takes depth rather than the SNR rank the report's panels share, because what it is drawn to show -- an array-wide stripe, a burst confined to one shank -- is spatial structure that a quality ranking scatters.

times

times(ntv_idx)

Crossing times on one channel, empty when it never fired.

The distinction between a silent channel and an unread one is carried by :attr:channel_indices, not by the presence of a key -- so a figure can draw an empty row for a channel that was measured and found silent.

Functions:

fetch_events

fetch_events(
    vc,
    data,
    spikes_id,
    *,
    channels=None,
    detection=DEFAULT_DETECTION,
)

Read every threshold crossing in the recording from a detect-only fileset.

Parameters:

Name	Type	Description	Default
vc	VidereClient	Client connected to the server holding the recording.	required
data	DatasetMetadata | Path	An already-linked recording, or a path to link.	required
spikes_id	str	Detect-only fileset to read, detected at detection's threshold.	required
channels	Sequence[int] | None	Amplifier ntv_idx values to read. None (the default) reads the datasource's current selection, which is the population compute_report measured. Whatever is passed becomes the selection, as it does for a report.	None
detection	DetectionSettings	Stage-2 filters and detection threshold. Pass the same object given to :func:~radiens_qc.compute.compute_report.	DEFAULT_DETECTION

Returns:

Type	Description
EventTrains	The crossings, with the geometry needed to order them by depth.

Raises:

Type	Description
ValueError	If no amplifier channels are selected, or the fileset does not hold per-site crossings at detection's threshold for every channel.