radiens_core.models.kpi

KPI (Key Performance Indicator) signal metrics domain models and enums.

CLASS	DESCRIPTION
BundleStatId	Identifies one cross-channel bundle summary.
ChannelReduction	How a bundle summary collapses a per-channel metric across channels.
KpiBundleStatsResult	Cross-channel KPI summaries over time.
KpiBundleStatsWindow	One time bin of a KPI bundle-stats series.
KpiMetric	KPI metric identifier.
KpiMetricId	Identifies a single KPI metric.
KpiMetricsResult	Result of a KPI metrics query.
KpiMetricsSeriesResult	Per-channel KPI metric timeseries.
KpiMetricsWindow	One time bin of a KPI metrics series.
KpiServiceMode	Which answering mode a KPI metrics request wants.
KpiStatus	Status of KPI computation for a dataset or stream.

ATTRIBUTE	DESCRIPTION
FlexBundleStatId	BundleStatId that also accepts a metric name or KpiMetric (reduced by MEAN), a
FlexChannelReduction	ChannelReduction that also accepts a case-insensitive name string.
FlexKpiMetricId	KpiMetricId that also accepts a metric name string or enum member.
FlexKpiServiceMode	KpiServiceMode that also accepts a case-insensitive name string.

Attributes

FlexBundleStatId module-attribute

FlexBundleStatId = (
    BundleStatId | KpiMetric | str | tuple[str | KpiMetric, str | ChannelReduction]
)

BundleStatId that also accepts a metric name or KpiMetric (reduced by MEAN), a (metric, reduction) pair, or a {"metric": ..., "reduce": ...} dict whose reduce defaults to MEAN.

Example

# Metric name only — reduction defaults to MEAN
stats = ["rms", "noise_uv"]

# Explicit reduction
stats = [("rms", "mean"), ("snr", "min"), (KpiMetric.NOISE_UV, ChannelReduction.COUNT)]

FlexChannelReduction module-attribute

FlexChannelReduction = ChannelReduction | ChannelReductionStr

ChannelReduction that also accepts a case-insensitive name string.

FlexKpiMetricId module-attribute

FlexKpiMetricId = KpiMetricId | KpiMetric | str

KpiMetricId that also accepts a metric name string or enum member.

Metric name strings are case-insensitive.

Example

# String shorthand
metrics = ["mean", "rms", "snr"]

# Enum member
metrics = [KpiMetric.MEAN, KpiMetric.RMS]

# Full object (pass-through)
metrics = [KpiMetricId(name=KpiMetric.MEAN)]

FlexKpiServiceMode module-attribute

FlexKpiServiceMode = KpiServiceMode | KpiServiceModeStr

KpiServiceMode that also accepts a case-insensitive name string.

Classes

BundleStatId

Bases: BaseModel

Identifies one cross-channel bundle summary.

A per-channel metric reduced across the selected channels — for example {RMS, MEAN} is the average RMS over the probe.

ATTRIBUTE	DESCRIPTION
metric	The per-channel metric to reduce. TYPE: KpiMetric
reduce	How to collapse that metric across channels. TYPE: ChannelReduction

ChannelReduction

Bases: IntEnum

How a bundle summary collapses a per-channel metric across channels.

Reductions skip non-finite values (NaN or ±inf: no data or no events).

ATTRIBUTE	DESCRIPTION
MEAN	Mean of the finite values. NaN when none are finite.
MAX	Largest finite value. NaN when none are finite.
MIN	Smallest finite value. NaN when none are finite.
SUM	Sum of the finite values. 0 when none are finite.
COUNT	Number of finite values.

KpiBundleStatsResult

Bases: BaseModel

Cross-channel KPI summaries over time.

ATTRIBUTE	DESCRIPTION
stats	Bundle stat IDs, in the order their values appear in each window. TYPE: tuple[BundleStatId, ...]
windows	Time windows, ordered by time. TYPE: tuple[KpiBundleStatsWindow, ...]
answered_mode	Which mode produced these values. TYPE: KpiServiceMode

KpiBundleStatsWindow

Bases: BaseModel

One time bin of a KPI bundle-stats series.

ATTRIBUTE	DESCRIPTION
time_range	Time range this window covers. TYPE: TimeRange
values	One value per requested bundle stat, in stats order. TYPE: tuple[float, ...]

KpiMetric

Bases: IntEnum

KPI metric identifier.

Member values are not stable across releases; refer to metrics by name.

KPI covers amplifier channels only. Amplitudes are in µV.

For a window with no events, SNR is NaN, EVENT_RATE is 0, EVENT_MIN is +inf, and the other event metrics are -inf. SNR and the event metrics are NaN on a channel whose signal is unsuitable for event detection.

ATTRIBUTE	DESCRIPTION
NUM_PTS	Number of samples measured.
NUM_PTS_ISI	Number of samples NOISE_UV was estimated from. Despite the name, not an inter-spike-interval count.
DUR_SEC	Duration measured, in seconds.
MEAN	Mean signal level.
MIN	Minimum signal level.
MAX	Maximum signal level.
MAX_ABS	Largest absolute signal level.
MAX_MIN_DIFF_ABS	Signal range, |MAX - MIN|.
SD	Signal standard deviation.
RMS	Signal root mean square.
NOISE_UV	The spike detector's noise estimate, which its thresholds are scaled by. NaN when nothing was measured.
SNR	EVENT_MEAN_MAX_ABS / NOISE_UV.
EVENT_RATE	Events per second.
EVENT_MAX	Largest event peak.
EVENT_MIN	Smallest event trough.
EVENT_MAX_ABS	Largest absolute event peak.
EVENT_MAX_MIN_DIFF_ABS	Largest event peak-to-peak.
EVENT_MEAN_MAX_ABS	Mean absolute peak of the events.
EVENT_MEAN_MAX_MIN_DIFF_ABS	Mean peak-to-peak of the events.

KpiMetricId

Bases: BaseModel

Identifies a single KPI metric.

ATTRIBUTE	DESCRIPTION
name	The metric to compute. TYPE: KpiMetric

KpiMetricsResult

Bases: BaseModel

Result of a KPI metrics query.

values is a 2-D numpy array of shape (n_channels, n_metrics) where rows correspond to channel_indices and columns to metrics.

ATTRIBUTE	DESCRIPTION
channel_indices	Native channel indices in row order. TYPE: tuple[int, ...]
metrics	KPI metric IDs in column order. TYPE: tuple[KpiMetricId, ...]
signal_type	Signal type for all channels in this result. TYPE: SignalType
values	Metric values: shape (n_channels, n_metrics). TYPE: NDArray[float64]
time_range	Time range over which these metrics were computed. In STREAM mode, the span streamed so far rather than the averaging window. TYPE: TimeRange
answered_mode	Mode that produced these values. Extrema from STREAM are envelopes rather than exact min/max. TYPE: KpiServiceMode

KpiMetricsSeriesResult

Bases: BaseModel

Per-channel KPI metric timeseries.

N time windows sharing the same channel_indices / metrics ordering.

ATTRIBUTE	DESCRIPTION
channel_indices	Native channel indices in row order. TYPE: tuple[int, ...]
metrics	KPI metric IDs in column order. TYPE: tuple[KpiMetricId, ...]
signal_type	Signal type for all channels in this result. TYPE: SignalType
windows	Time windows, ordered by time. TYPE: tuple[KpiMetricsWindow, ...]
answered_mode	Which mode produced these values. TYPE: KpiServiceMode

KpiMetricsWindow

Bases: BaseModel

One time bin of a KPI metrics series.

ATTRIBUTE	DESCRIPTION
time_range	Time range this window covers. TYPE: TimeRange
values	Metric values: shape (n_channels, n_metrics). TYPE: NDArray[float64]

KpiServiceMode

Bases: IntEnum

Which answering mode a KPI metrics request wants.

ATTRIBUTE	DESCRIPTION
RANGE	Exact fold over the requested time range. Not available on a live stream.
STREAM	Exponential moving average over a lookback window. Live streams only; on a recording it returns NaN.

KpiStatus

Bases: BaseModel

Status of KPI computation for a dataset or stream.

ATTRIBUTE	DESCRIPTION
stream_group_id	Unique ID (UID) of the dataset the status belongs to. Not the ID the call was made with. TYPE: str
num_packets_memory	Capacity of the in-memory KPI cache, in packets, derived from persistence. TYPE: int
packet_dur	Duration of each KPI packet in seconds. TYPE: float
update_period	How often newly arrived signal is processed, in seconds. TYPE: float
persistence	How long computed KPI packets are kept in memory, in seconds. TYPE: float
beta	Processing headroom, 1 - processing time / data duration, smoothed. Near 1 is fast; 0 or below means falling behind. NaN before any data is processed. TYPE: float
num_packets	Length of time_range in packets. TYPE: int
memory_bytes	Approximate capacity of the in-memory KPI cache in bytes. TYPE: float
num_sigs	Number of amplifier channels, enabled or not. TYPE: int | None
time_range	Time range KPI has been computed over. TYPE: TimeRange | None