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.
KpiMode	Per-metric KPI computation mode.
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 (metric, reduction) pair.
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 (metric, reduction) pair.

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 | tuple[KpiModeStr | KpiMode, str | KpiMetric]
)

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)]

The (mode, name) tuple form is deprecated and its mode is ignored — pass service_mode to get_kpi_metrics() instead.

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). MEAN, MAX and MIN return NaN when nothing is finite, SUM returns 0, and COUNT counts the 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.

NOISE_UV is the spike detector's noise estimate, which its thresholds are scaled by. SNR is EVENT_MEAN_MAX_ABS / NOISE_UV. EVENT_MEAN_MAX_ABS is the mean absolute peak of the events in the window, and EVENT_MEAN_MAX_MIN_DIFF_ABS is their mean peak-to-peak.

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.

KpiMetricId

Bases: BaseModel

Identifies a single KPI metric.

ATTRIBUTE	DESCRIPTION
name	The metric to compute. TYPE: KpiMetric
mode	Deprecated and ignored. Retained so existing callers keep working; see KpiMode. TYPE: KpiMode

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]

KpiMode

Bases: IntEnum

Per-metric KPI computation mode.

Deprecated

Ignored. Pass service_mode to get_kpi_metrics() instead. Removed in 0.1.0.

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