radiens_qc.report

The per-recording quality report and the thresholds that grade it.

Deliberately free of matplotlib: :class:QualityReport is a data object that :mod:radiens_qc.plot renders and :mod:radiens_qc.persist serializes, not something that knows how to draw or save itself.

Classes

QualityReport `dataclass`

Self-contained quality report for a single recording.

Attributes:

Name	Type	Description
`base_name`	`str`	Recording identifier.
`source`	`str`	Caller-supplied provenance string describing where the recording came from (a Drive path, an experiment id, a bare filesystem path). Opaque to this package -- it is recorded and displayed, never parsed.
`recorded_at`	`datetime \| None`	Wall-clock recording start (UTC), or `None` if unknown.
`duration_sec`	`float`	Recording duration in seconds.
`sampling_rate`	`float`	Sampling rate in Hz.
`num_channels`	`int`	Number of amplifier channels analyzed.
`probe_ids`	`list[str]`	Distinct probe identifiers present.
`headstage_ids`	`list[str]`	Distinct headstage identifiers present.
`window_sec`	`float`	Window width used for the temporal analysis.
`metrics`	`list[str]`	KPI metric names in column order (as returned by the server).
`thresholds`	`QualityThresholds`	Quality thresholds used for channel classification.
`channels`	`DataFrame`	One row per channel, indexed by native channel index (`ntv_idx`). Columns: `site_num`, `probe_x`, `probe_y`, `name`, one column per metric (whole-recording per-channel mean), and `quality` (`good`/`fair`/`poor`/`dead`).
`window_centers_sec`	`NDArray[float64]`	Window center times, in seconds relative to the recording start.
`matrices`	`dict[str, NDArray[float64]]`	`metric -> (n_windows, n_channels)` arrays; channel columns are aligned to `channels.index` order. Empty when a report is loaded from a pre-v1 folder that did not persist them.
`dsp_params`	`list[DSPParams]`	Read-time DSP applied before KPI computation (provenance).
`event_threshold_sd`	`float \| None`	Event-detection threshold in noise-SD multiples applied before KPI computation, or `None` if the server default was used (provenance).

Methods:

grade

grade()

Single-letter overall grade (A-D) from good/dead channel fractions.

mean

mean(metric)

Whole-recording mean of metric across channels.

median

median(metric)

Whole-recording median of metric across channels.

quality_counts

quality_counts()

Number of channels in each quality tier (good/fair/poor/dead).

rank_order

rank_order()

Channel positions ordered by descending :data:PRIMARY_METRIC (best first).

The report's canonical display order. Every panel that lists channels -- the ranked bar and both channel x time heatmaps, including the event-rate one -- uses this same array, so a given row is the same physical channel across panels and they stay comparable row-for-row.

Falls back to natural channel order when the report has no :data:PRIMARY_METRIC column (a metrics set that excluded it). The panels that consume this already degrade gracefully in that case, so raising here would defeat their guards.

summary_stats

summary_stats(metric)

Distribution stats (min/p25/median/mean/p75/max/std) for metric.

QualityThresholds `dataclass`

Heuristic thresholds for classifying per-channel signal quality.

These are deliberately conservative, adjustable defaults — the KPI SNR is a continuous signal-band/noise-band ratio, not a spike SNR, so tune them to your probe/prep rather than treating them as universal.

Attributes:

Name	Type	Description
`snr_good`	`float`	Channels at or above this SNR are `"good"`.
`snr_fair`	`float`	Channels between `snr_fair` and `snr_good` are `"fair"`; below `snr_fair` they are `"poor"`.
`dead_noise_uv`	`float`	Channels whose noise floor falls below this (µV), or whose SNR is non-finite, are treated as `"dead"` (disconnected/flatline).
`snr_scale_min`	`float`	Lower bound of the fixed SNR color scale used by the spatial map and stability heatmap.
`snr_scale_max`	`float`	Upper bound of the fixed SNR color scale used by the spatial map and stability heatmap. These scales are intentionally not autoscaled to each report's own min/max -- a probe that's uniformly excellent would otherwise still show "red" at the low end of its own compressed range, giving a false impression of poor sites.
`noise_scale_min_uv`	`float`	Lower bound of the fixed noise-floor color scale used by the spatial map.
`noise_scale_max_uv`	`float`	Upper bound of the fixed noise-floor color scale used by the spatial map, for the same reason.
`event_rate_scale_max_hz`	`float`	Upper bound of the fixed activity/event-rate color scale used by the spatial map, for the same reason.

Functions:

mask_non_finite

mask_non_finite(matrix)

Replace non-finite entries with NaN so nan-aware aggregates ignore them.

The KPI server uses -inf as a "zero events this window" sentinel for snr (an accumulator that is never overwritten when no spikes are found) rather than NaN or 0. np.nanmean/nanmedian/nanpercentile only strip NaN -- left as-is, a single -inf window would drag an entire whole-recording or whole-window aggregate to -inf, even when most windows have a well-defined value.

Lives here rather than in :mod:radiens_qc.compute because it encodes how :attr:QualityReport.matrices is written, so both the module that builds those matrices and the module that plots them read the rule from one place.