radiens_qc.raw

Fetch raw signal, threshold crossings and spectra for the raw-signal figures.

Nothing here is archived on a :class:~radiens_qc.report.QualityReport. A report is a measurement -- what the KPI pass produced, what save_report writes and load_report round-trips. An excerpt is a view into the recording, which needs the file linked and a server up, so it is requested when a figure is drawn and thrown away afterwards. That is why the raw-signal figures take (vc, dataset) while the report figures stay pure over a report: a figure that needs a server says so in its arguments.

Everything a figure reads is measured on the same signal the rest of the report was: :func:~radiens_qc.preprocess.apply_detection_settings sets the stage-2 DSP group and the detection threshold, get_signals(apply_dsp=True) reads back through that same stage, and the crossings come from a fileset checked to be detected at that threshold. So the filtered trace, the crossings drawn on it, and event_rate in the report all describe one signal rather than three approximations of it.

Classes

Excerpt `dataclass`

One slice of the recording, read twice through different filter stages.

wideband and filtered are (n_channels, n_samples) in the channel order of the owning :class:RawSignal, and cover the same samples: the pair is what makes "did the DSP chain do what we think" answerable.

RawSignal `dataclass`

Excerpts, crossings, geometry and whole-file spectra for raw-signal figures.

Attributes:

Name	Type	Description
`base_name`	`str`	Recording identifier.
`sampling_rate`	`float`	Sampling rate in Hz.
`duration_sec`	`float`	Recording duration in seconds.
`channel_indices`	`tuple[int, ...]`	Amplifier `ntv_idx` per row of every excerpt array.
`geometry`	`DataFrame`	Per-channel probe geometry, indexed by `ntv_idx`.
`excerpts`	`tuple[Excerpt, ...]`	One per entry of :data:`EXCERPT_FRACTIONS`, in time order.
`crossings`	`dict[int, NDArray[float64]]`	`ntv_idx -> crossing times` in seconds on the dataset's own time base, covering the excerpts only. Empty when crossings were not requested; a channel that fired in no excerpt is simply absent.
`detection`	`ResolvedDetection`	Stage-2 filters and detection threshold the excerpts were read through and the crossings found at.
`freqs`	`NDArray[float64]`	Frequency axis in Hz for whole-file spectral estimates.
`psd_wideband`	`NDArray[float64]`	Whole-file wideband Welch power spectral density, `(n_channels, n_freqs)` in µV²/Hz.
`psd_filtered`	`NDArray[float64]`	Whole-file stage-2 filtered Welch power spectral density, `(n_channels, n_freqs)` in µV²/Hz.

Methods:

depth_order

depth_order()

Row order that puts spatially adjacent sites next to each other.

See :func:~radiens_qc._dataset.depth_order.

window_crossings

window_crossings(
    excerpt, ntv_idx, window_sec=TRACE_WINDOW_SEC
)

Crossing times on ntv_idx inside the drawn window, on the dataset's own time base.

window_slice

window_slice(excerpt, window_sec=TRACE_WINDOW_SEC)

Sample slice of the centered window_sec of excerpt.

window_times

window_times(excerpt, window_sec=TRACE_WINDOW_SEC)

Sample times of the drawn window, on the dataset's own time base.

Functions:

compute_welch_overlap

compute_welch_overlap(
    duration_sec, segment_sec=1.0, max_segments=120
)

Compute overlap_frac in [0.01, 0.5] to cap total Welch segments across a recording.

Enforces overlap_frac >= 0.01 because the Radix server (common.go:200) checks overlapFrac > 0 and falls back to 0.5 if 0.0 is sent.

excerpt_starts

excerpt_starts(
    duration_sec,
    t0_sec,
    *,
    fractions=EXCERPT_FRACTIONS,
    excerpt_sec=EXCERPT_SEC,
)

Excerpt start times on the dataset's own time base.

Parameters:

Name	Type	Description	Default
`duration_sec`	`float`	Recording duration.	required
`t0_sec`	`float`	The dataset's own start time, which is not necessarily zero.	required
`fractions`	`Sequence[float]`	Where in the recording to sample.	`EXCERPT_FRACTIONS`
`excerpt_sec`	`float`	Length of each excerpt.	`EXCERPT_SEC`

Raises:

Type	Description
`ValueError`	If the recording is shorter than :data:`MIN_DURATION_SEC`.

fetch_raw_signal

fetch_raw_signal(
    vc,
    data,
    *,
    channels=None,
    fractions=EXCERPT_FRACTIONS,
    excerpt_sec=EXCERPT_SEC,
    detection=DEFAULT_DETECTION,
    crossings_spikes_id=None,
    with_spectra=True,
)

Read paired wideband/filtered excerpts, crossings, and whole-file Welch spectra.

Configures read-time DSP and the detection threshold first, so the filtered excerpt is the signal the KPI engine measured. Whole-file Welch spectra are queried via radiens-core's spectral analysis API for both wideband and stage-2 filtered signals.