← diagnostics package

DetectReferenceChannels

Automated detection of EEG channel(s) being used as a reference.

This node is for offline use only and is intended to detect if recorded EEG channels are being used as a reference. Note in many cases such as linked ears or mastoid references those channels' data are not saved to the recording itself or they are easily excluded from analyses since they are not scalp EEG channels and this node wouldn't apply. However, if a scalp EEG channel (e.g. Cz) is used as a reference and the data is being saved in the recording, this node will help to identify it and the reference channel(s) EEG data could be retained and used in downstream analyses if accounted for (e.g. excluding them from removal/cleaning during pre-processing and applying common average re-reference). This node outputs a mask packet of True/False values per each space axis element (channels) and optionally a list of the detected reference channels. This node works by first requiring the mean absolute amplitude to be <1 uV. It then looks for channels that are flatlined (based on absolute and relative jitter thresholds) and/or marked as dropout as determined by the Bad Channel Removal node and its correlation and noise thresholds. For the most accurate dropout detection it is recommended to use all scalp EEG channels with their locations. If fewer than 2 channels are used for input then dropout detection is not possible and only flatline criteria will be enforced. Version 0.9.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

ref_channels_list

A list of the channels detected as reference.

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

percent_time

Percentage of total recording time the reference channels must meet criteria of being detected as flat or dropout.

• verbose name: Percent Time
• default value: 90
• port type: FloatPort
• value type: float (can be None)

absolute_threshold

Absolute amplitude threshold. This requires the mean (across time) absolute amplitude (assumed uV) to be less than this threshold in order for a channel to be checked as a reference. EEG reference channels should theoretically be near 0 as they are used as a baseline subtraction. This requirement is used to differentiate between potential reference channels vs bad (e.g. disconnected) channels that may also appear to be flatline as those channels typically are flat but with some DC offset voltage.

• verbose name: Absolute Amplitude Threshold
• default value: 1
• port type: FloatPort
• value type: float (can be None)

criteria_type

Criteria type for detecting reference channels. 'either' means a channel is marked as a reference if it meets either the flatline or dropout criteria. 'both' means a channel must meet both criteria to be marked as a reference.

• verbose name: Criteria Type
• default value: either
• port type: EnumPort
• value type: str (can be None)

corr_threshold

Correlation threshold. Higher values (above 0.7) are more stringent and will mark dropout for more channels (i.e., moderately bad channels get dropout). 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.7
• 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 dropout more channels (i.e., moderately bad channels will get marked as dropout). Values above 5 would be considered very lax. 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)

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)

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)

max_jitter_rel

Allowed relative jitter. This is relative to the absolute signal value. If a channel has lower jitter than this in a time window, it is considered a flatline.

• verbose name: Max Relative Jitter
• default value: 1e-05
• port type: FloatPort
• value type: float (can be None)

max_jitter_abs

Allowed absolute jitter. If a channel has lower jitter than this in a time window, it is considered a flatline.

• verbose name: Max Absolute Jitter
• default value: 1e-05
• port type: FloatPort
• value type: float (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)