radiens_qc.plot_events

Render a recording's event stream as a raster over per-channel rate traces.

Takes an :class:~radiens_qc.events.EventTrains rather than a :class:~radiens_qc.report.QualityReport, for the reason :mod:radiens_qc.plot_raw does: this describes the recording, not the measurement, and cannot be drawn from a saved report directory.

Both panels are computed from one binning of the crossings, so they cannot disagree about when something happened. Bin width follows the plotted span rather than being fixed, so drawing a shorter window sharpens the raster. The smoothing does not follow the span: its kernel is fixed in seconds, because the estimate at an instant should not depend on how far the figure is zoomed. It is fixed rather than scaled to the recording's duration as well, which is where this parts company with the report figures' bandwidth (:func:~radiens_qc._smooth.time_sigma_sec): burst structure sits at a timescale of its own, and a width chosen for a drift readout on a long recording averages it away. That is also why :class:~radiens_qc.figures.RenderOptions does not reach this figure -- a run pinning one width is pinning it for the drift question. Pass smooth_sec here to set this one.

Neither panel reduces across channels. The rate panel draws every channel and overlays the median, rather than summarizing the population as a mean or as a median with a percentile band. A mean is carried by whichever sites are busiest, so on an uneven array it invents a population: two sites at ~90 Hz report a 10-25 Hz/chan baseline that fourteen sites under 2 Hz never approach. A filled band fixes that but brings its own defect -- it sets the axis limits, so it always fills the panel, and on a small array where a quartile lands on a genuinely extreme site it is a slab covering the median it exists to qualify.

Drawing every channel escapes both, and matches what :mod:radiens_qc.plot_raw already does with traces: any subset is a claim about what matters made before looking. Line color follows the raster's own depth ordering, so a burst confined to one stretch of the probe reads as one color group lifting out of the rest -- which a single-color cloud cannot show. Opacity falls with channel count, so the same call draws four legible lines or a thousand-line density, with no threshold to tune and no second code path.

The rate axis is symlog rather than linear. One transient otherwise sets the scale and flattens everything before it: a recording whose 60 Hz burst is preceded by 80 s of rhythmic 1-3 Hz bursting shows the burst and a hairline. Symlog rather than log because zero has to stay on the axis -- "activity ceased" is among the readings this figure exists to support.

The raster is an image of per-bin counts, not a mark per crossing. At low density every cell holds 0 or 1 and it renders as an ordinary raster; as density rises the same call becomes a density image. It also keeps a multi-million crossing recording to one histogram rather than millions of artists.

Classes

ChannelRates

Bases: NamedTuple

Firing rate over time, in Hz, for every channel and for the typical one.

Attributes:

Name	Type	Description
`per_channel`	`NDArray[float64]`	`(channel, bin)` rates, rows in the raster's depth order, so row i of one panel is row i of the other.
`median`	`NDArray[float64]`	Across-channel median in each bin -- what a typical site does.
`sigma_sec`	`float`	Kernel these rates were estimated with, and 0.0 when they were not filtered. Carried on the result so the panel cannot name a width other than the one applied.

Functions:

bin_crossings

bin_crossings(events, *, columns, span_sec=None)

Crossings counted into a (channel, time) matrix, in depth order.

Rows follow :meth:~radiens_qc.events.EventTrains.depth_order, so a contiguous band of rows is a contiguous stretch of the probe.

bin_spike_times

bin_spike_times(trains, *, columns, span_sec)

Spike times counted into a (row, time) matrix on one shared set of edges.

Rows are taken in the order given, so the caller owns what a row means -- a site for the events level, a unit for the units level -- and both get the same binning, and with it the same guarantee that a raster and the rate traces below it cannot disagree about when something happened.

Returns:

Type	Description
`tuple[NDArray[float64], NDArray[float64]]`	The count matrix and the `columns + 1` bin edges it was cut on.

channel_rates

channel_rates(counts, edges, *, sigma_sec=None)

Smoothed per-channel firing rates, with the across-channel median.

Per second rather than per bin, so the axis means the same thing at every span -- a bin width that halves would otherwise halve the rate for identical activity.

Each channel is smoothed before the median is taken, not after: a median over raw per-bin counts is 0 nearly everywhere at the bin widths this figure uses, so reducing first would pin it to the floor.

sigma_sec pins the kernel; None takes :data:RATE_SIGMA_FLOOR_SEC. A pinned width is never narrower than one bin, which is itself a boxcar of that width, and 0 returns the rates unfiltered.

depth_shades

depth_shades(n_channels)

One RGBA color per channel, running the depth ramp from row 0 downward.

draw_raster

draw_raster(
    ax,
    counts,
    edges,
    shades,
    *,
    row_labels,
    row_axis_label,
    title,
)

A (row, time) count matrix as a density image, rows already in draw order.

draw_rate_lines

draw_rate_lines(
    ax, edges, rates, shades, *, row_noun="channel"
)

Every row's smoothed rate as one collection, with the median opaque on top.

The time axis names the kernel the rates were estimated with, the way the report's heatmaps do, so the two figure families can be compared at all.

plot_event_raster

plot_event_raster(
    events, *, span_sec=None, columns=None, smooth_sec=None
)

Raster over per-channel rate traces, on one shared time axis.

Stacked rather than overlaid: the two carry different units, so co-locating them needs a twin y axis that leaves neither labelable, and puts the rate lines over the channels being inspected exactly during the burst being inspected. Sharing x is what makes the comparison work, and both panels order channels by depth and color them alike, so a row in one is findable in the other.

Parameters:

Name	Type	Description	Default
`events`	`EventTrains`	The fetched crossings.	required
`span_sec`	`tuple[float, float] \| None`	Time range to draw. `None` draws the whole recording.	`None`
`columns`	`int \| None`	Time bins across the panel. `None` uses one per horizontal pixel at the drawn width.	`None`
`smooth_sec`	`float \| None`	Kernel the rate traces are estimated with, in seconds. Fixed rather than derived from the span, for the reason the module docstring gives. Never narrower than one bin, and `0` draws the rates unfiltered; the rate axis names whichever width was used.	`None`

Returns:

Type	Description
`Figure`	The figure, with the raster above and the rate lines below.