← signal_processing package

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.

• verbose name: Data
• default value: None
• port type: DataPort
• value type: Packet (can be None)
• data direction: INOUT

spatial_taper

Spatial taper.

• verbose name: Spatial Taper
• default value: None
• port type: DataPort
• value type: Packet (can be None)
• data direction: IN

subtract_mean

Subtract signal mean. If set to False, the signal must already be approx. zero mean (e.g., highpass filtered).

• verbose name: Subtract Mean
• default value: False
• port type: BoolPort
• value type: bool (can be None)

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.

• verbose name: Regularization Strength
• default value: 1e-06
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Step Size
• default value: 1
• port type: IntPort
• value type: int (can be None)

step_size_unit

Unit for the step size value.

• verbose name: Step Size Unit
• default value: samples
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Sphereing Method
• default value: eigh
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Geometry
• default value: euclidean
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Robust
• default value: False
• port type: BoolPort
• value type: bool (can be None)

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.

• verbose name: Huber Threshold
• default value: 0.0
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Stochastic Average Gradient
• default value: True
• port type: BoolPort
• value type: bool (can be None)

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.

• verbose name: Robust Learning Rate
• default value: 2.0
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Robust Learning Rate Decay
• default value: 0.75
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Subspace Dim
• default value: None
• port type: FloatPort
• value type: float (can be None)

forget_factor

Forget factor when the rhh method is being used.

• verbose name: Forget Factor
• default value: 0.9999
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Min Ev
• default value: None
• port type: FloatPort
• value type: float (can be None)

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

• verbose name: Regularize Towards
• default value: diag
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Update During This Time Range
• default value: []
• port type: ListPort
• value type: list (can be None)

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.

• verbose name: Update On Markers
• default value: []
• port type: ListPort
• value type: list (can be None)

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.

• verbose name: Apply Retroactive
• default value: False
• port type: BoolPort
• value type: bool (can be None)

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.

• verbose name: Warnings As Errors
• default value: False
• port type: BoolPort
• value type: bool (can be None)

nan_check

Check for NaN or infinity values.

• verbose name: Nan Check
• default value: True
• port type: BoolPort
• value type: bool (can be None)

ignore_resets

Ignore signal resets.

• verbose name: Ignore Resets
• default value: False
• port type: BoolPort
• value type: bool (can be None)

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.

• verbose name: Backend
• default value: keep
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Precision
• default value: keep
• port type: EnumPort
• value type: str (can be None)

use_caching

Use caching.

• verbose name: Use Caching
• default value: False
• port type: BoolPort
• value type: bool (can be None)

verbose

Use verbose output.

• verbose name: Verbose
• default value: False
• port type: BoolPort
• value type: bool (can be None)

print_interval

Print interval in seconds for verbose output.

• verbose name: Print Interval
• default value: 30
• port type: IntPort
• value type: int (can be None)

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.

• verbose name: Channel Grouping
• default value: None
• port type: Port
• value type: object (can be None)

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.

• verbose name: Identical Across Groups
• default value: False
• port type: BoolPort
• value type: bool (can be None)

set_breakpoint

Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

• verbose name: Set Breakpoint (Debug Only)
• default value: False
• port type: BoolPort
• value type: bool (can be None)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

• verbose name: Metadata
• default value: {}
• port type: DictPort
• value type: dict (can be None)