radiens_qc.preprocess

Configure read-time DSP and event detection so KPI metrics mean what the report claims.

Kept in the package rather than left to callers because the report's correctness depends on the ordering: configure, then kpi_calculate, then read metrics. The server clears its KPI cache asynchronously when either setting changes, so a caller who reads metrics without re-triggering computation silently gets stale values that do not reflect the filters the report says were applied.

Functions:

amp_ports

amp_ports(dataset)

Distinct hardware ports the recording's amplifier channels occupy.

A DSP filter targets one port, so filters must be replicated across every port present. The port is the leading letter of a channel's hardware-native name (e.g. "A-000" → port A). Falls back to a single port A if no native name parses (single-headstage recordings).

apply_kpi_preprocessing

apply_kpi_preprocessing(
    vc,
    dataset,
    *,
    dsp_params=DEFAULT_EVENT_DSP,
    event_threshold_sd=DEFAULT_EVENT_THRESHOLD_SD,
)

Configure read-time DSP filters and event threshold for KPI compute.

Sets STAGE2 DSP filters (the only stage the KPI engine reads through) and/or the per-channel event-detection threshold on the datasource, so that subsequently computed KPI metrics (SNR, event rate, noise, RMS) reflect them. No data files are rewritten — this is read-time filtering.

The server auto-clears and recomputes the KPI cache when either changes, but that recompute is asynchronous. Callers must therefore trigger and await KPI computation (:meth:VidereClient.kpi_calculate) after this returns, before reading metrics, or get_kpi_metrics may return stale/partial values. :func:~radiens_qc.compute.compute_report handles that ordering for you.

Parameters:

Name	Type	Description	Default
`vc`	`VidereClient`	Client connected to the server holding `dataset`.	required
`dataset`	`DatasetMetadata`	The linked recording to configure.	required
`dsp_params`	`Sequence[FlexDSPParams] \| None`	DSP filters applied at `STAGE2`, in order. Any param that does not name a `port` is replicated across every amplifier port the recording occupies; `stage` is injected. `None` or empty leaves the DSP group unchanged.	`DEFAULT_EVENT_DSP`
`event_threshold_sd`	`float \| None`	Symmetric event-detection threshold in noise-SD multiples (applied as `[-sd, +sd]` on every amplifier channel). `None` leaves the threshold unchanged.	`DEFAULT_EVENT_THRESHOLD_SD`

resolve_dsp_params

resolve_dsp_params(dataset, dsp_params)

Normalize DSP params to what will actually be applied to dataset.

Coerces the DSPParamsDict shorthand into real :class:DSPParams, injects STAGE2, and replicates any param that does not name a port across every amplifier port the recording occupies (a DSP filter targets one port, so a port-less param means "all of them").

A param that names a port explicitly is left on that port -- a caller who targeted one port meant it, and silently fanning it out would apply filtering they did not ask for.

Returning fully-resolved params rather than passing the shorthand straight through lets the report record exactly what was applied, instead of recording the request and hoping it matches.