radiens_qc.compute

Measure a recording: walk it in windows and classify its channels.

This module is the package's only point of contact with a live server. It knows nothing about where recordings are stored -- callers materialize a file locally (from Drive, S3, a share, wherever) and hand over a path or an already-linked dataset.

Classes

Functions:

compute_report

compute_report(
    vc,
    data,
    *,
    source=None,
    window_sec=None,
    channels=None,
    metrics=DEFAULT_METRICS,
    thresholds=None,
    detection=DEFAULT_DETECTION,
)

Compute a quality report for one recording.

Links the recording if needed, selects the channels to analyze, configures the stage-2 filters and detection threshold so the KPIs reflect them, triggers KPI computation, then reads the whole per-channel metric timeseries in one request. Whole-recording per-channel values are the mean across windows; the full per-window matrices are retained for temporal-stability panels.

Leaves channels selected on the datasource when it returns. Selection is shared server-side state, so other clients viewing the same datasource see the change -- as they already do for the DSP group and detection threshold this configures.

Parameters:

Name	Type	Description	Default
`vc`	`VidereClient`	Client connected to the server that will do the computation.	required
`data`	`DatasetMetadata \| Path`	An already-linked recording, or a local filesystem path to link. A path is linked via `vc.link_data_file`; linking is idempotent, so passing a path for a file already linked is free. Note this is deliberately not `str` -- in radiens-core a bare string means a dataset id, and accepting one here would silently mean something different.	required
`source`	`str \| None`	Provenance string recorded on the report (e.g. the Drive folder or experiment the recording came from). Defaults to the dataset's own path. Never parsed by this package.	`None`
`window_sec`	`float \| None`	Requested width of each analysis window, in seconds. The server bins its KPI packets, so actual windows are quantized to the packet duration and the last one may be shorter; a trailing window under half the resolved width is dropped rather than averaged in. `None` (the default) uses the dataset's native KPI packet duration -- one window per packet, the finest granularity the server has on hand. This is a choice of temporal resolution, not of value: every metric the report aggregates is an intensive quantity, so a narrower window yields more and noisier windows rather than systematically different per-channel numbers.	`None`
`channels`	`Sequence[int] \| None`	Amplifier `ntv_idx` values to analyze. `None` (the default) analyzes every amplifier channel, so the report's counts are against the probe's full site count. Whatever is passed becomes the datasource's amp selection, which is what makes it the report's denominator; a caller narrowing this to its own notion of good channels is where screening policy belongs.	`None`
`metrics`	`Sequence[FlexKpiMetricId]`	KPI metric names to compute (e.g. `"snr"`, `"noise_uv"`).	`DEFAULT_METRICS`
`thresholds`	`QualityThresholds \| None`	Channel-classification thresholds; defaults to `QualityThresholds()`.	`None`
`detection`	`DetectionSettings`	Stage-2 filters and detection threshold to measure through, applied before KPI computation and recorded on the report. Hand the same object to :func:`~radiens_qc.raw.fetch_raw_signal` so the raw-signal figures show the signal the report graded.	`DEFAULT_DETECTION`

Returns:

Type	Description
`QualityReport`	The computed report.

Raises:

Type	Description
`ValueError`	If `channels` names an index the recording does not have, if the server returns a different channel set than was selected, or if the recording yields no analyzable windows.

derive_ratios

derive_ratios(matrices)

Per-window ratio matrices derived from the server's own metrics.

Folded per window, before any reduction. The per-channel columns of a report are means over windows and its headline numbers are medians over channels, and neither commutes with division -- a crest factor built from a mean peak over a mean noise floor is a different quantity from the mean of the per-window crest factors, and only the latter answers "how spiky did this channel get".

Returns only the ratios whose inputs are present, so a report computed with a narrower metrics set simply has fewer derived columns rather than failing.