pyntbci.utilities.RunningCovariance
- class pyntbci.utilities.RunningCovariance(n_features: int = None)[source]
A running (weighted) covariance accumulator over a joint feature vector, kept in uncentered-moment form.
Unlike covariance()’s Welford-style running mode, this stores the raw (weighted) zeroth, first, and second moments of the observed data, which are purely additive and subtractive across chunks. This makes three operations exact and cheap, none of which the Welford form supports: peeking at “current state plus a candidate chunk” without committing it (update() with commit left to the caller, or peek()), committing a chosen chunk, and later removing a previously added chunk (update() with sign=-1). It also supports per-sample weights. These are exactly the access patterns needed to fit one CCA per candidate class off a shared history, to commit only the winner, and to relabel (remove-then-re-add) a past trial, as in unsupervised adaptive rCCA.
The covariance is centered (the running mean is subtracted) only when read out via covariance, so no mean needs to be tracked incrementally with a correction term. Moments are accumulated in float64 for numerical precision; this is safe for (near) zero-mean inputs such as band-pass filtered EEG, where the uncentered second moment and the outer product of the mean are of a similar, moderate magnitude (little catastrophic cancellation).
Note, the overall normalization of the covariance (dividing by the total weight) is irrelevant when the result is used for CCA: the whitening Cxx^(-1/2) Cxy Cyy^(-1/2) is invariant to a common positive scale on all three blocks, so the learned filters are identical regardless of the (weighted) sample count.
- Parameters:
n_features (int (default: None)) – The number of features of the joint feature vector. If None, it is inferred from the first update().
- n_
The total weight (i.e., the (weighted) number of samples) accumulated so far.
- Type:
float
- sum_
The (weighted) sum of the data of shape (n_features,).
- Type:
NDArray
- moment_
The (weighted) sum of the outer products of the data of shape (n_features, n_features).
- Type:
NDArray
- copy() RunningCovariance[source]
Return a deep copy of the accumulator.
- Returns:
other – A new accumulator with the same accumulated moments.
- Return type:
- property covariance: NDArray
The (weighted, centered) covariance of the accumulated data of shape (n_features, n_features).
- property mean: NDArray
The (weighted) mean of the accumulated data of shape (n_features,).
- peek(data: NDArray, weights: float | NDArray = None) RunningCovariance[source]
Return a copy of the accumulator with a chunk added, without mutating this instance.
- Parameters:
data (NDArray) – Data matrix of shape (n_samples, n_features).
weights (float | NDArray (default: None)) – Per-sample weights, see update().
- Returns:
combined – A new accumulator equal to this one plus the given chunk.
- Return type:
- update(data: NDArray, weights: float | NDArray = None, sign: int = 1) RunningCovariance[source]
Add (sign=1) or remove (sign=-1) a chunk of samples to/from the accumulated moments, in place.
- Parameters:
data (NDArray) – Data matrix of shape (n_samples, n_features).
weights (float | NDArray (default: None)) – Per-sample weights of shape (n_samples,), or a single scalar weight applied to all samples. If None, all samples get unit weight.
sign (int (default: 1)) – Use 1 to add the chunk to the accumulator, or -1 to remove a previously added chunk.
- Returns:
self – Returns the instance itself.
- Return type: