← neural package

ArtifactRemoval

Remove various kinds of high-amplitude artifacts from the signal.

Artifacts are identified based on a threshold, given in standard deviations relative to (fairly) clean calibration data. This filter will work best on signals with multiple correlated channels, such as EEG or MEG. Important: This filter assumes the the input signal has already been highpass filtered to remove drifts (e.g., using an IIR filter). It makes no assumption on stationarity of the artifact sources, or repeating artifact patterns, and can handle anything from blinks to muscle and movement artifacts, to high-amplitude sensor glitches or EM interference. If this filter is used on streaming data and has not yet been calibrated, then it will first buffer n seconds of calibration data to determine some statistics, before any output is produced. This filter operates on a sliding window, and by default outputs processed data only after a certain amount of future data has been seen, in order to make a good decision on what is an artifact and what isn't, and this timing behavior is tunable through two parameters. One can also tune how robust the method is to artifacts in the calibration data (the default is quite robust). If you are running this filter on data where you stimulate with high-amplitude signals, and want to retain the EEG response, such as in SSVEP, you need to make the filter completely 'blind' to the stimulation frequencies, by overriding the IIR filter coefficients A and B, for instance with a hard Elliptic filter with high stopband suppression. The implementation is partially based on the paper by S. Blum et. al [1]., although it has been modified to improve the performance. [1] S. Blum, N. S. J. Jacobsen, M. G. Bleichner and S. Debener, "A Riemannian Modification of Artifact Subspace Reconstruction for EEG Artifact Handling," Front. Hum. Neurosci., 26 April 2019 | https://doi.org/10.3389/fnhum.2019.00141 Version 2.4.2

Ports/Properties

data

Data to process.

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

diagnostic

Diagnostic information indicating the average ratio of artifact to the clean eeg, per channel.

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

diagnostic_time

Diagnostic information indicating the difference between the raw and clean eeg, per time point, per channel.

• verbose name: Diagnostic Time
• default value: None
• port type: DataPort
• value type: Packet (can be None)
• data direction: OUT

cutoff

Threshold for artifact removal, in standard deviations. Data portions whose amplitude is larger than this threshold (relative to the calibration data) are considered bad data and will be removed. Note that salient EEG phenomena such as event-related potentials or occipital alpha lie somewhat outside this Gaussian distribution of background EEG, and therefore the most aggressive value that can be reasonably used is 3.5. Values between 5 and 7.5 are still fairly aggressive and will attenuate these large phenomena, while 10-15 standard deviations are reasonable choices that will preserve most of the EEG signal.

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

window_length

Window length used to check the data for artifact content. This is ideally as long as the expected time scale over which artifact components persist and their locations remain reasonably stationary, but short enough that there are several 100s of windows extracted for the calibration data.

• verbose name: Sliding Window Length
• default value: 0.5
• port type: FloatPort
• value type: float (can be None)

lookahead

Amount of look-ahead that the algorithm should use. Since the processing is causal, the output signal will be delayed by this amount. This value is in seconds and should be between 0 (no lookahead) and half the window length (optimal lookahead). The recommended value and default is window length/2.

• verbose name: Override Lookahead
• default value: None
• port type: Port
• value type: object (can be None)

window_overlap

Window overlap fraction. The fraction of two successive windows that overlaps. Higher overlap ensures that fewer artifact portions are going to be missed (but is slower).

• verbose name: Window Overlap Fraction
• default value: 0.66
• port type: FloatPort
• value type: float (can be None)

max_dims

Maximum fraction or number of simultaneous artifact components to remove. Up to this many components can be removed for a given data segment (can also be given as a fraction of the number of channels, if below 1.0). In low-channel settings, one might limit this to between 0.25 and 0.5. One can also use a higher value if it needs to be guaranteed that no artifacts make it through, even in extremely noisy situations. If this is set to 0, a heuristic will be used where for 4 or less channels, this value resolves to 1, and for 16 or more channels, it is 66%, with linear interpolation in between.

• verbose name: Max Simultaneous Artifacts Fraction
• default value: 0
• port type: FloatPort
• value type: float (can be None)

max_dropout_fraction

Max fraction of calibration data where channels may be unplugged. This is used for estimating the threshold accurately. Also refers to any other condition where a channel may have lower amplitude than regular EEG.

• verbose name: Max Fraction Of Unplugged Calib Data
• default value: 0.1
• port type: FloatPort
• value type: float (can be None)

min_clean_fraction

Min fraction of calibration data that is assumed to be clean. This is used for estimating the threshold accurately. This actually refers to the percentage of time windows which are clean, and since time windows have a certain length, a single brief spike can pollute an entire time window worth of data. If you know that your calibration data is clean, you could increase this number to get somewhat higher-quality threshold estimates.

• verbose name: Min Fraction Of Clean Calibration Data
• default value: 0.25
• port type: FloatPort
• value type: float (can be None)

step_size

Update statistics at least every this many seconds. The larger this is, the faster the algorithm will be, at least on large (offline) chunks, but as a downside it may occasionally miss brief or small artifacts. This value must not be larger than the window length. Using a too-short value is also not ideal since it may give you sharp discontinuities in the data. The minimum value is 1/sampling rate ( update for every sample) while a good value is 1/3 of a second. Note that generally an update is performed on the last sample of each data chunk, so during real-time processing of short chunks this value rarely plays a role. Values larger than one are interpreted to be in samples (for backwards compatibility).

• verbose name: Internal Step Size In Seconds
• default value: 0.2
• port type: FloatPort
• value type: float (can be None)

max_mem

The maximum amount of memory used by the algorithm, in MB. The recommended value is at least 256. Using smaller amounts of memory is less CPU-efficient, but does not affect the cleaning result.

• verbose name: Max Memory Gb
• default value: 256
• port type: Port
• value type: object (can be None)

init_on

Time range to calibrate (initialize) the filter on. This parameter can take a single number or two numbers. In case of streaming data, this should always be a single number, representing the number of seconds to buffer from the start of the data, for calibration. In case of offline (recorded) data, this can either be a single number, in which case it represents the window of time in seconds from the beginning of the recording to be used; or, it can be a list of two numbers, in which case this refers to a range of data in seconds, relative to the start of the data, to be used for calibration. The latter allows you to calibrate on data other than the first segment of the data (i.e., if known to be bad), or to avoid running the (fairly expensive) filter on a very long file or on each fold of a cross-validation. Note that a value of 0 here will in the case of offline data be interpreted as the entire file, and in the case of streaming data will raise an error.

• verbose name: Calibration Range
• default value: []
• port type: ListPort
• value type: list (can be None)

calib_seconds

Amount of data, in seconds, to buffer for calibration on streaming data. For offline (non-streaming) data use the "calibration range" (init_on) parameter instead.

• verbose name: Calib Seconds
• default value: 45
• port type: IntPort
• value type: int (can be None)

emit_calib_data

Emit the data buffer that was used for calibration, after calibration is complete, in a single chunk. If False, this filter will discard the calibration data. Since this chunk can be quite long, it is often preferable to discard it in a real-time pipeline, but if subsequent nodes need to see the processed calibration data to calibrate themselves (quite likely the case), it needs to be emitted.

• verbose name: Emit Calibration Data
• default value: True
• port type: BoolPort
• value type: bool (can be None)

block_size

Block size for robust estimator. Data statistics will be estimated in blocks of this many samples and then robustly averaged. If this is too small, especially for a large number of channels, you may end up with lower-quality estimates.

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

use_clean_window

Use clean time windows for calibration. This is available only during offline processing.

• verbose name: Use Clean Time Windows For Calibration
• default value: True
• port type: BoolPort
• value type: bool (can be None)

zscore_thresholds

Minimum and maximum of clean signal range (for use clean window option). The minimum and maximum standard deviations within which the power of a channel must lie (relative to a robust estimate of the clean EEG power distribution in the channel) for it to be considered not bad.

• verbose name: Clean Signal Range
• default value: [-5, 7]
• port type: ListPort
• value type: list (can be None)

max_bad_channels

Maximum fraction of bad channels allowed (for use clean window option). The maximum fraction of bad channels that a retained window may still contain (more than this and it is removed). Reasonable range is 0.05 (very clean output) to 0.3 (very lax cleaning of only coarse artifacts).

• verbose name: Max Fraction Of Bad Channels
• default value: 0.2
• port type: FloatPort
• value type: float (can be None)

window_len_cleanwindow

Length of sliding window (for use clean window option). This is the window length used to check the data for artifact content, in seconds. This is ideally as long as the expected time scale of the artifacts but short enough to allow for several 1000 windows to compute statistics over.

• verbose name: Window Length
• default value: 0.5
• port type: FloatPort
• value type: float (can be None)

window_overlap_cleanwindow

Window overlap fraction (for use clean window option). The fraction of two successive windows that overlaps. Higher overlap ensures that fewer artifact portions are going to be missed, in expense of being slower.

• verbose name: Window Overlap Fraction
• default value: 0.66
• port type: FloatPort
• value type: float (can be None)

stddev_cutoff

The number of standard devations between clean data and data with artifacts, at which the artifactual data is clamped when computing the artifact ratio that is output through the diagnostics port. (In other words, all values above this std.dev will have the same artifact ratio in order to provide a more robust measure that is not impacted by abnormally high artifacts.) This is only used for diagnostics and does not impact the cleaning of the data itself.

• verbose name: Stddev Cutoff
• default value: 20
• port type: IntPort
• value type: int (can be None)

min_required_channels

Minimum number of channels required to preform artifact removal. Setting this to a value below 2 will likely cause this node to fail and is not recommended. Setting this param to 0 disables this check.

• verbose name: Min Required Channels
• default value: 2
• port type: IntPort
• value type: int (can be None)

riemannian

Use Riemannian methods if applicable.

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

preserve_band

Optionally a dictionary to define the frequency band to preserve. This is given via fields 'freqs', which has the frequency points of interest, and a field 'gains' which has for each frequency point the desired relevance (gain), typically between 0 and 1. An example is {'freqs': [7,8,12,13], 'gains': [0,1,1,0]} to preserve the alpha band. Additionally the 'order' parameter can be given to choose the FIR filter order (e.g., 50 for an alpha bandpass at 200-250 Hz).

• verbose name: Preserve Band
• default value: None
• port type: DictPort
• value type: dict (can be None)

use_legacy

Use legacy option (DEPRECATED).

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

b

Override spectrum shaping IIR filter coefficient b. This is the numerator coefficient vector of an IIR filter that is used to shape the spectrum of the signal when calculating artifact statistics. The output signal does not go through this filter. This is an optional way to tune the sensitivity of the algorithm to each frequency component of the signal. The default filter is less sensitive at alpha and beta frequencies and more sensitive at delta (blinks) and gamma (muscle) frequencies.

• verbose name: Override Iir Coeff Vector B
• default value: None
• port type: Port
• value type: object (can be None)

a

Override spectrum shaping IIR filter coefficient a. This is the denominator coefficient vector of an IIR filter that is used to shape the spectrum of the signal when calculating artifact statistics. The output signal does not go through this filter. This is an optional way to tune the sensitivity of the algorithm to each frequency component of the signal. The default filter is less sensitive at alpha and beta frequencies and more sensitive at delta (blinks) and gamma (muscle) frequencies.

• verbose name: Override Iir Coeff Vector A
• default value: None
• port type: Port
• value type: object (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)