radiens_qc.compute

Measure a recording: screen it, walk it in windows, 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=10.0,
    metrics=DEFAULT_METRICS,
    thresholds=None,
    dsp_params=DEFAULT_EVENT_DSP,
    event_threshold_sd=DEFAULT_EVENT_THRESHOLD_SD,
)

Compute a quality report for one recording.

Links the recording if needed, optionally configures read-time DSP filters and an event-detection threshold so the KPIs reflect them, triggers KPI computation, then walks the recording in window_sec-wide windows, querying per-channel metrics for each. Whole-recording per-channel values are the mean across windows; the full per-window matrices are retained for temporal-stability panels.

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`	Width of each analysis window, in seconds.	`10.0`
`metrics`	`Sequence[FlexKpiMetricId]`	KPI metric names to compute (e.g. `"snr"`, `"noise_uv"`).	`DEFAULT_METRICS`
`thresholds`	`QualityThresholds \| None`	Channel-quality thresholds; defaults to `QualityThresholds()`.	`None`
`dsp_params`	`Sequence[FlexDSPParams] \| None`	Read-time DSP applied before KPI computation (e.g. a spike-band bandpass). `None` computes KPIs on the unfiltered signal.	`DEFAULT_EVENT_DSP`
`event_threshold_sd`	`float \| None`	Event-detection threshold in noise-SD multiples, applied before KPI computation. `None` uses the server default.	`DEFAULT_EVENT_THRESHOLD_SD`

Returns:

Type	Description
`QualityReport`	The computed report.

Raises:

Type	Description
`ValueError`	If the recording yields no analyzable windows.

screen_dataset

screen_dataset(
    dataset,
    *,
    min_duration_sec,
    default_probe_markers=DEFAULT_PROBE_MARKERS,
    recorded_after=None,
    recorded_before=None,
)

Decide whether a linked recording should be reported on.

Screens the recording's own metadata — cheap checks made after link but before the expensive KPI compute — so junk datasets are skipped without paying for a full report.

Parameters:

Name	Type	Description	Default
`dataset`	`DatasetMetadata`	The linked recording metadata to screen.	required
`min_duration_sec`	`float`	Reject recordings shorter than this (too little data for reliable per-window KPIs).	required
`default_probe_markers`	`Sequence[str]`	Substrings that mark a placeholder/default probe; a recording using one is unmapped/test data.	`DEFAULT_PROBE_MARKERS`
`recorded_after`	`datetime \| None`	If set, reject recordings whose wall-clock start is before this (or unknown). Must be tz-aware (recording wall time is UTC-aware).	`None`
`recorded_before`	`datetime \| None`	If set, reject recordings whose wall-clock start is at or after this (or unknown). Must be tz-aware.	`None`

Returns:

Type	Description
`str \| None`	A short human-readable reason to skip the recording, or `None` if it
`str \| None`	passes all checks.