IncrementalWhitening¶
Perform a whitening (sphering) transform of the signal incrementally.
This node progressively updates, over the course of a recording, a linear spatial transform that can be interpreted as a ZCA or decorrelation (and scaling to unit norm) of channels. The method supports shrinkage for rank-deficient and/or high-channel data, block updates for increased performance, riemannian or euclidean geometry (riemannian can work better for decent-quality but non-stationary data, but euclidean will likely be more resilient in the presence of bad-quality data). The method can also use robust (outlier-tolerant) updates, but note that this likely requires parameter tuning for the given data (while the non-robust mode uses optimal recursive updates). Robustness works best if the initial part of the data is reasonably clean since bad onset artifacts can potentially throw off the estimator. There is also an experimental mode that can track the principal subspace of the data more efficiently, although this should rarely be needed. Another advanced use case is that for very high-dimensional data, a spatial prior matrix can be passed in that encodes the likelihood of any two channels being correlated. This matrix can be obtained with the CovarianceTaper node. Version 1.0.0
Ports/Properties¶
data¶
Data to process.
spatial_taper¶
Spatial taper.
subtract_mean¶
Subtract signal mean. If set to False, the signal must already be approx. zero mean (e.g., highpass filtered).
regularization¶
Shrinkage regulariation strength. Larger values yield more conservative (but less adapted) whitening transforms. Typically only a very small value (e.g., 1e-6 to 1e-3) is necessary to avoid degenerate solutions. The Riemannian variants may require a slightly larger regularization.
step_size¶
Step size when performing block updates. Processing performance at very high channel counts is increased by this factor. When selecting Riemann geometry (or blockwise Euclidean), then this is also used as the effective block size. When doing robust estimation, could be matched to the time scale of expected artifacts (e.g., 1-5 seconds), or, for Riemannian estimation, this may be set to be long enough to obtain good block covariance estimates.
step_size_unit¶
Unit for the step size value.
method¶
Method to use for sphereing. The typical choice is eigh. The pinv method is mostly included for reference (it works even if regularization is zero). The rhh method is experimental for the special case where only a lower-dimensional dominant subspace shall be tracked and fast per-sample updates are desired. This method can be more brittle in the presence of artifacts, and is not compatible robust and/or riemannian modes.
geometry¶
Whether to average covariance matrices using a Riemannian assumption. This is theoretically a more ideal way to average covariance matrices, particularly in the presence of non-stationarity, but it can be more brittle due its need for well-behaved matrices in each block update (stepsize samples). The Euclidean (blockwise) mode can be chosen to use the same processing pathway as the Riemannian mode, except that the geometry is Euclidean.
robust¶
Whether to use a robust estimator. When enabled, the Robbins-Monro algorithm is used, which is configured via the parameters rm_gamma, rm_alpha, and rm_sag. The type of estimator is configured using the huber_thresold parameter. These parameters can be somewhat finicky to tune and they interact. Some settings worth trying are: 1) sag=False, huber=0, gamma=median covariance deviation, alpha=1; 2) sag=True; huber=1.35*median covariance deviation, gamma=1.5 to 2.5, alpha=0.75.
huber_threshold¶
Huber threshold, applies only when using a robust estimator. If set to 0, the geometric (or l1) median is used. This has the highest breakdown point (50% data corruption), but, like the median, it will effectively utilize the most central covariance matrix in the data sample (pooled across blocks or across samples), which may not be a good estimate if raw block estimates are low quality (e.g., estimated on too-short blocks). If set to >0, a Huber estimator is used. This value is then ideally set to a value that's some factor of the median deviation of each covariance matrix to the centroid (in terms of Euclidean or Riemannian distance), and a typical choice is 1.35x (which retains 95% of the variance). Due to the median deviation being data-specific, this needs to be tuned for a given study. If set to None, the non-robust least-squares estimator (i.e., mean covariance) is used, which can be used to assess convergence with a given set of gamma, sag and alpha parameters (comparing to the robust=False behavior, which uses the exact recursive mean). In verbose mode, this will print the per-sample deviation values, which can be used to set the huber threshold appropriately.
rm_sag¶
Use stochastic average gradient descent for robust estimation. In theory this causes the estimator to converge more quickly. However, on non-stationary time-series data and/or bad initial data (at the beginning of the recording), this can likely also backfire and make the other parmameters more difficult to tune.
rm_gamma¶
Gamma parameter (learning rate) of Robbins-Monro algorithm when using a robust method. To tune this parameter, several heuristics are available: 1) exponentially spaced grid search up to some multiple of the median covariance deviation, 2) a value near the covariance deviation (e.g., if huber=0, sag=False, alpha~1), 3) a value between 1 and 3, (if sag=True and alpha=0.75). Note that the deviation will differ starkly between sample-wise or block-wise covariance matrices, across different block sizes, as well as riemannian vs euclidean settings.
rm_alpha¶
Alpha parameter of Robbins-Monro algorithm when using a robust method. This parameter typically does not require much tuning, but can instead be set to close to or exactly 1 (if sag=False), or 3/4 (if sag=True). A setting of 2/3 has also been proposed for sag=True, but results may not differ much from the 3/4 setting.
subspace_dim¶
Dimensionality of the subspace when using the rhh method. This can be an integer, or if <1 it is taken as a fraction of the number of channels. The compute time of the method is proportional to this.
forget_factor¶
Forget factor when the rhh method is being used.
min_ev¶
Minimum eigenvalue threshold when inverting the covariance matrix. This can prevent errors when whitening data with very high channel counts on very little data.
regularize_towards¶
Target matrix for regularization. The 'eye' option is the identity matrix, the 'scaled-eye' option is the identity matrix scaled to the average variance of the data, and the 'diag' option is a diagonal matrix with the same diagonal as the covariance matrix. This is mostly relevant for very high regularization values (>0.1).
update_on¶
Time range to initialize on. If two numbers are given, in seconds from the first sample, then the filter will be updated only on that sub-slice of the data.
update_on_markers¶
List of markers on which to update. This can contain wildcard characters. This mode is useful if trials should not be interrupted by changes of the whitening matrix. Instead the node can be configured to update e.g., only after each trial has completed.
apply_retroactive¶
Apply the transform retroactively to the segment that it was estimated on. This is all data since the last update. Note that this is not currently online capable, and would effectively only emit a chunk on each update.
warnings_as_errors¶
Treat numerics warnings as errors. This applies when invalid eigenvalues (usually due to rank-deficient matrices) occur in the data, which can help detect potential issues early during processing.
nan_check¶
Check for NaN or infinity values.
ignore_resets¶
Ignore signal resets.
backend¶
Compute backend to use. The cupy and torch backends can be faster on data with many channels (e.g., >500) and if the system has a CUDA-capable GPU installed. Keep means to use whatever was used to create the incoming data.
precision¶
Numeric precision to use. Can be reduced to save memory (e.g. if running on GPU). Only needed for the largest of problems, and only used by the geometric and huber centroids.
use_caching¶
Use caching.
verbose¶
Use verbose output.
print_interval¶
Print interval in seconds for verbose output.
channel_grouping¶
Optional channel grouping. Given as a list/vector of group indices per channel (0-based). Whitening will only take place within each group. This can also be set to True to effectively perform adaptive per-channel scaling with no decorrelation.
group_average¶
Average the whitening coefficients across groups. This effectively forces channels in different groups to share the same whitening. This requires equal-sized groups, and channels must be sorted in a compatible (e.g., identical) order in each groups.
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.