mne_rt.combiners.ZScoredNormCombiner

class mne_rt.combiners.ZScoredNormCombiner(features: list[str], warmup: int = 30)

Bases: FeatureCombiner

Euclidean norm after online z-score normalisation of each feature.

Each feature stream is independently normalised using the mean and standard deviation estimated from the first warmup windows:

zᵢ = (xᵢ − μᵢ) / σᵢ
mixed = ‖z‖ / √n  =  sqrt(Σ zᵢ²) / sqrt(n)

Dividing by √n keeps the output near 1 when all features hover at their baseline mean, and it grows when any feature deviates — making it a natural “how different from baseline are we?” score.

Statistics are frozen after warmup (no drift tracking). To re-fit (e.g. between blocks), call reset().

Parameters:

featureslist of str

Modality names to include.

warmupint, default 30

Number of windows collected before statistics are fixed and the combiner starts producing non-zero output. Returns 0.0 during the warmup phase.

Notes

A feature with no usable spread (a constant signal) contributes 0.0 rather than being divided by a floor: it has no z-score to give. Feature magnitude is irrelevant — a band-power feature at ~1e-14 normalises to the same range as a connectivity index at ~1.

Changed in version 1.2.0: Standard deviations were previously floored at 1e-9, which for power-like features replaced the real spread and left the normalised output orders of magnitude too small.

Examples

from mne_rt.combiners import ZScoredNormCombiner

combiner = ZScoredNormCombiner(
    features=["sensor_power", "laterality", "connectivity_ratio"],
    warmup=30,
)
for window_vals in session_data:         # first 30 calls return 0.0
    mixed = combiner.combine(window_vals)

__init__(features: list[str], warmup: int = 30) → None

Methods

__init__(features[, warmup])
combine(values)	Return the z-scored Euclidean norm, or 0.0 during warmup.
reset()	Clear collected statistics and restart the warmup phase.

reset() → None

Clear collected statistics and restart the warmup phase.

Useful when called between NF blocks so the combiner re-fits its baseline to the new block’s distribution.

combine(values: dict[str, float]) → float

Return the z-scored Euclidean norm, or 0.0 during warmup.