← neural package

BadChannelRemoval

Remove channels with abnormal data from a continuous EEG signal.

Ensures that the data contains no channels that record only noise for extended periods of time. If channels with control signals are contained in the data (e.g., trigger channels), these are usually also removed. Important: This filter assumes the the input signal has already been highpass filtered to remove drifts (e.g., using an IIR filter). There are two threshold criteria: one is a minimum correlation that a channel needs to exceed to be considered good, and the other is a maximum tolerated high-frequency noise level that a channels must not exceed to be considered good. There is also a fallback mode for the case where no channel/sensor locations are available, and some additional tunable parameters related to it. Note that the fallback does not give as good results as the default mode that uses channel locations (there is a utility node named Assign Channel Locations, which can be used to guess locations based on the channel labels). 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 what channels to keep, before any output is produced. The set of retained channels is considered "trainable state", and can be saved in model files for later reuse. The algorithm can be somewhat slow to calibrate on long data, especially if a high value for the RANSAC subset count parameter is used; the default is tuned for robustness and quality, but it's possible to change these values for faster calibration time. Version 1.2.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

diagnostic_badchannels

Diagnostic information indicating the bad channels.

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

diagnostic_noiselevel

Diagnostic information indicating the noise zscore for different channels.

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

diagnostic_corr_flagged

Diagnostic information holding a channels x time point binary mask of which channels are flagged, and at what time points, as less correlated to their neighbors than the given threshold. This measure is used to decide what channels to mark as "bad" (based on the max_broken_time parameter).

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

diagnostic_avg_corr

Diagnostic information indicating the average correlation across channels over time.

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

bad_channels

A list of the channels removed.

• verbose name: Bad Channels
• default value: None
• port type: DataPort
• value type: list (can be None)
• data direction: OUT

corr_threshold

Correlation threshold. Higher values (above 0.7) are more stringent and will remove more channels (i.e., moderately bad channels get removed). Values below 0.6 would be considered very lax (i.e., only the worst channels get removed). This threshold is based on the correlation between a channel and what one would expect the channel to be given the other channels. Note that this parameter is only used when channel locations are available.

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

noise_threshold

High-frequency noise threshold. Lower values (below 3.5) are more stringent and will remove more channels (i.e., moderately bad channels will get removed). Values above 5 would be considered very lax (i.e., only the worst channels get removed). This threshold is based on the amount of high frequency noise compared to other channels, and is measured in standard deviations.

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

window_len

Window length to compute correlations. Length of the windows, in seconds, over which correlation is computed. Ideally this is short enough to isolate periods with temporary multi-channel artifacts, like movements (which do not count towards bad channels), but not shorter (otherwise the statistic becomes too noisy and thus unreliable).

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

max_broken_time

Maximum duration or fraction of broken data to tolerate. Maximum time, either in seconds or as fraction of the calibration data, if below 1.0, during which a channel may be broken while still considered good (i.e., usable). This value should not be larger than half the duration of the calibration data.

• verbose name: Max Allowed Broken Fraction
• default value: 0.4
• port type: FloatPort
• value type: float (can be None)

subset_size

Size of random channel subsets to use. This is for use in a RANSAC estimator, and is given as a fraction of the total number of channels. Smaller subsets together with higher number of Ransac samples gives a more robust estimate, at increased computational cost during calibration.

• verbose name: Ransac Subset Size
• default value: 0.15
• port type: FloatPort
• value type: float (can be None)

num_samples

Number of random channel subsets to use. This for use in a RANSAC estimator. Higher numbers together with smaller subset sizes give a more robust estimate, at higher computational cost during calibration.

• verbose name: Ransac Subset Count
• default value: 200
• port type: IntPort
• value type: int (can be None)

protect_channels

Channels to protect from removal. This protects the channels with the given names from being removed. The syntax is as in ['Fp1','Fp2','C3','Cz'].

• verbose name: Protect Channels From Removal
• default value: []
• port type: ListPort
• value type: list (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: 20
• port type: IntPort
• value type: int (can be None)

keep_unlocalized_channels

Keep unlocalized channels. Whether to keep channels which have no location information and can therefore not be assessed using location-aware measures. Otherwise these would generally be removed unless the fallback mode is used.

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

ignore_chanlocs

Fallback that ignores channel locations. If enabled, a fallback method will be used that relies on the fallback correlation treshold and fallback quantile parameters. This method is also used if no channel locations are present.

• verbose name: Force Fallback For No Locations
• default value: False
• port type: BoolPort
• value type: bool (can be None)

min_corr

Minimum correlation threshold for fallback case. This threshold is only used if the fallback for no locations is enabled. If a channel is less correlated to any of the other channels (except for the most correlated k percent of channels, as set by the fallback ignore quantile parameter), then the channel will be marked as potentially bad in that time window.

• verbose name: Fallback Correlation Threshold
• default value: 0.5
• port type: FloatPort
• value type: float (can be None)

ignored_quantile

Max fraction of synchronous channels for fallback case. This parameter is only used if the fallback for no locations is enabled. When a channel is checked for its correlation to other channels, this is the fraction of other channels that may be synchronous with it (i.e., highly correlated) because they might be short-circuited with the channel being checked, or which may measure the same noise process (e.g., line noise) for some other reason. Increasing this value within reason can make the criterion more robust.

• verbose name: Fallback Max Synchronous Channels
• default value: 0.1
• port type: FloatPort
• value type: float (can be None)

rereferenced

Run calculations on re-referenced data. This can improve performance in environments with extreme all-channel EM noise, but will decrease robustness against single channels with extreme excursions (e.g., huge spikes).

• verbose name: Compute On Re-Referenced Data
• default value: False
• port type: BoolPort
• value type: bool (can be None)

linenoise_aware

Use line-noise aware processing. Whether the operation should be performed in a line-noise aware manner. If enabled, the correlation measure will not be affected by the presence or absence of line noise. May be turned off if line noise has already been removed.

• verbose name: Line Noise Aware Processing
• default value: True
• port type: BoolPort
• value type: bool (can be None)

coords_override

Override sensor coordinates. Allows overriding the coordinates of the channels.

• verbose name: Override Sensor Coordinates
• default value: None
• port type: FloatPort
• value type: float (can be None)

use_clean_window

Use clean time windows for calibration. Setting this to False will flag channels as bad if they are across the entire file including time windows when the data is considered bad. Set to True (default) is a more stringent test that only flags channels as bad if they are deemed so during time windows when the data is considered "good" overall (other channels are ok). Note that this is available only for offline processing (ignored on streaming data).

• verbose name: Use Clean Time Windows For Calibration
• default value: False
• 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: [-3.5, 5]
• 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.15
• 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

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)

verbose

Print progress including list of channels removed.

• verbose name: Verbose
• default value: True
• 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)