radiens_core.models.spectral

Spectral analysis domain models and enums.

CLASS	DESCRIPTION
BatchSpectralResult	Result of a batch spectral analysis request.
SpectralAlgorithm	Spectral estimation algorithm.
SpectralChannelResult	Spectral power for a single channel.
SpectralInfoResult	Preview of the spectral parameters a request would produce, computed without reading signal data.
SpectralMode	Whether a spectral result is a single spectrum or a spectrogram.
SpectralQuery	Parameters for a spectral analysis request.
SpectralRange	One alignment window over which a spectrum is computed.
SpectralRangeResult	Spectral results for one alignment window, across channels.
SpectralResult	Result of a spectral analysis request.
SpectralUnit	Power scale of a spectral result.
SpectralWindowType	Windowing function applied before the FFT.
StftConfig	Short-time Fourier transform parameters.
WelchConfig	Welch-algorithm parameters.

ATTRIBUTE	DESCRIPTION
FlexSpectralAlgorithm	SpectralAlgorithm that also accepts a case-insensitive name string.
FlexSpectralMode	SpectralMode that also accepts a case-insensitive name string.
FlexSpectralRange	SpectralRange that also accepts a (ref_sec, pre_sec, post_sec) tuple or dict.
FlexSpectralUnit	SpectralUnit that also accepts a case-insensitive name string.
FlexSpectralWindowType	SpectralWindowType that also accepts a case-insensitive name string.

Attributes

FlexSpectralAlgorithm module-attribute

FlexSpectralAlgorithm = SpectralAlgorithm | SpectralAlgorithmStr

SpectralAlgorithm that also accepts a case-insensitive name string.

FlexSpectralMode module-attribute

FlexSpectralMode = SpectralMode | SpectralModeStr

SpectralMode that also accepts a case-insensitive name string.

FlexSpectralRange module-attribute

FlexSpectralRange = SpectralRange | tuple[float, float, float] | dict[str, float]

SpectralRange that also accepts a (ref_sec, pre_sec, post_sec) tuple or dict.

FlexSpectralUnit module-attribute

FlexSpectralUnit = SpectralUnit | SpectralUnitStr

SpectralUnit that also accepts a case-insensitive name string.

FlexSpectralWindowType module-attribute

FlexSpectralWindowType = SpectralWindowType | SpectralWindowTypeStr

SpectralWindowType that also accepts a case-insensitive name string.

Classes

BatchSpectralResult

Bases: BaseModel

Result of a batch spectral analysis request.

ATTRIBUTE	DESCRIPTION
results	One SpectralResult per submitted request, in request order. TYPE: tuple[SpectralResult, ...]

SpectralAlgorithm

Bases: IntEnum

Spectral estimation algorithm.

ATTRIBUTE	DESCRIPTION
PERIODOGRAM	Single FFT over the range. Requires STATIC.
WELCH	Average of overlapping windowed FFTs. Requires STATIC.
STFT	Short-time Fourier transform. Requires TIME_RESOLVED.

SpectralChannelResult

Bases: BaseModel

Spectral power for a single channel.

ATTRIBUTE	DESCRIPTION
ntv_chan_idx	Native channel index. TYPE: int
power	Power values. Shape (n_freq,) for STATIC mode, or (n_freq, n_times) for TIME_RESOLVED mode (rows are frequency bins, columns are time bins). TYPE: NDArray[float64]

SpectralInfoResult

Bases: BaseModel

Preview of the spectral parameters a request would produce, computed without reading signal data.

ATTRIBUTE	DESCRIPTION
achieved_df_hz	Actual frequency bin spacing, in Hz. TYPE: float
num_bins	Number of frequency bins in the result. TYPE: int
nfft_length	FFT length used. TYPE: int
achieved_time_res_sec	Time bin spacing, in seconds. None unless algorithm is STFT. TYPE: float | None
num_time_steps	Number of time bins in each range. None unless algorithm is STFT. TYPE: int | None
welch_num_segments	Number of averaged segments. None unless algorithm is WELCH. TYPE: int | None
welch_overlap_percent	Achieved segment overlap, as a percentage. None unless algorithm is WELCH. TYPE: float | None
variance_reduction_factor	Variance reduction from segment averaging. None unless algorithm is WELCH. TYPE: float | None
output_dimensions	Shape of the spectral result this request would produce. TYPE: tuple[int, ...]
estimated_memory_mb	Estimated size of one range's result in MiB, at 8 bytes per value (this client returns float64 arrays). Multiply by the number of ranges. TYPE: float
warnings	Warnings about the request. Currently always empty. TYPE: tuple[str, ...]
errors	Currently always empty; an invalid request raises instead. TYPE: tuple[str, ...]
applied_dsp_params	DSP filter parameters that would be applied, populated only when the request set apply_dsp=True with a dataset attached. TYPE: tuple[DSPParams, ...]

SpectralMode

Bases: IntEnum

Whether a spectral result is a single spectrum or a spectrogram.

ATTRIBUTE	DESCRIPTION
STATIC	One spectrum per channel over the whole time range.
TIME_RESOLVED	A spectrogram: one spectrum per time window.

SpectralQuery

Bases: BaseModel

Parameters for a spectral analysis request.

ATTRIBUTE	DESCRIPTION
ntv_chan_idxs	Native channel indices to compute spectra for. TYPE: tuple[int, ...]
ranges	Alignment windows to compute spectra over. TYPE: tuple[FlexSpectralRange, ...]
f_min	Minimum frequency to include, in Hz. None uses 0. TYPE: float | None
f_max	Maximum frequency to include, in Hz. None uses the Nyquist frequency. TYPE: float | None
mode	Whether to return a single spectrum (STATIC) or a spectrogram (TIME_RESOLVED). STFT requires TIME_RESOLVED; PERIODOGRAM and WELCH require STATIC — the server rejects a mismatched pair. TYPE: SpectralMode
algorithm	Spectral estimation algorithm. TYPE: SpectralAlgorithm
units	Power scale of the result. TYPE: SpectralUnit
window_type	Windowing function applied before the FFT. TYPE: SpectralWindowType
welch_config	Welch-specific parameters. Only meaningful when algorithm is WELCH; set at most one of welch_config / stft_config. TYPE: WelchConfig | None
stft_config	STFT-specific parameters. Only meaningful when algorithm is STFT; set at most one of welch_config / stft_config. TYPE: StftConfig | None
apply_dsp	Filter through the dataset's stage-2 chain before computing spectra. Filter state carries over from the previous call only when this range starts where that one ended; otherwise the filter warms up on the data before the range. TYPE: bool

SpectralRange

Bases: BaseModel

One alignment window over which a spectrum is computed.

ATTRIBUTE	DESCRIPTION
ref_sec	Alignment point, in seconds of stream time. TYPE: float
pre_sec	Seconds before ref_sec included in the window. Defaults to 0. TYPE: float
post_sec	Seconds after ref_sec included in the window. TYPE: float

SpectralRangeResult

Bases: BaseModel

Spectral results for one alignment window, across channels.

ATTRIBUTE	DESCRIPTION
range_idx	Index of the source SpectralRange this result covers. TYPE: int
channels	Per-channel spectral results. TYPE: tuple[SpectralChannelResult, ...]

SpectralResult

Bases: BaseModel

Result of a spectral analysis request.

ATTRIBUTE	DESCRIPTION
freq_axis	Frequency bin centers, in Hz. TYPE: NDArray[float64]
time_axis	Time bin centers, in seconds, relative to each range's ref_sec, shared by all ranges. Time bins a range does not reach hold NaN. Empty for STATIC mode. TYPE: NDArray[float64]
ranges	Per-range spectral results. A range that is not fully inside the dataset is omitted with a warning, so match results by range_idx. TYPE: tuple[SpectralRangeResult, ...]
warnings	Non-fatal warnings emitted while computing spectra. TYPE: tuple[str, ...]
applied_dsp_params	DSP filter parameters actually applied, populated only when the query set apply_dsp=True. TYPE: tuple[DSPParams, ...]

SpectralUnit

Bases: IntEnum

Power scale of a spectral result.

ATTRIBUTE	DESCRIPTION
POWER_UV2_HZ	Power spectral density in µV²/Hz.
POWER_DB_HZ	Power spectral density in dB/Hz.

SpectralWindowType

Bases: IntEnum

Windowing function applied before the FFT.

ATTRIBUTE	DESCRIPTION
RECT	Rectangular (no windowing).
HANN	Hann.
HAMMING	Hamming.
BLACKMAN	Blackman.

StftConfig

Bases: BaseModel

Short-time Fourier transform parameters.

ATTRIBUTE	DESCRIPTION
window_duration_sec	Duration of each STFT window, in seconds. None defaults to half the longest requested range. TYPE: float | None
window_step_sec	Step between consecutive STFT windows, in seconds. None defaults to half the window duration. TYPE: float | None

WelchConfig

Bases: BaseModel

Welch-algorithm parameters.

ATTRIBUTE	DESCRIPTION
segment_duration_sec	Duration of each averaged segment, in seconds. None defaults to half the longest requested range. TYPE: float | None
overlap_frac	Fractional overlap between segments, in [0, 1). None or 0 uses 0.5. TYPE: float | None