PreprocessEEG¶
Performs a standard EEG preprocessing chain including high/low pass filtering, artifact and bad channel removal, referencing, etc.
For processing offline (not streaming) data only. This so-called "meta node" calls a number of other nodes, in order: SelectRange, AssignChannelLocations, FixSignalUnit, Resample, DejitterTimestamps, Scaling, RemoveUnlocalizedChannels, ExtractChannels, Rereferencing (zero-median time), FIRFilter (highpass), BadChannelRemoval, ArtifactRemoval, InterpolateMissingChannels, Rereferencing (channels), RemoveBadTimeWindows, FIRFilter (lowpass), ShiftTimestamps. Preprocessed data can be exported. Version 1.5.0
Ports/Properties¶
data¶
Data to process.
kept_channels¶
Names of channels kept after bad channel removal and before interpolation. Not available when processing pre-processed files.
kept_samples¶
dict with chunk names for keys and time-axis indices as values. This output is useful to slice another parallel chunk to keep it the same size, even though it was not preprocessed.
skip_preprocessing¶
Skip all preprocessing, filtering or cleaning of the data. Check this box if the data is already preprocessed and ready for analysis. This node will still however select the channel subset specified here (if any) as well as assign channel locations.
channels_to_import¶
List of channels to retain. Can be a list of channel names or indices, or a string. If the latter, regular Python list and range syntax is supported, as well as comma-separated or space-separated lists of channel names or indices lists. The special keyword "all" stands for all channels.
use_notch_filter¶
Use a notch filter to remove line noise. If true, this will be applied at the beginning of the preprocessing chain before bad channel and artifact removal.
notch_frequency¶
Target frequency in Hz to remove using a notch filter at the beginning of the preprocessing chain.
lowpass_frequencies¶
High noise frequencies to be filtered out with a lowpass filter. You can either give the cutoff frequency as a single value, or two frequencies (separated by a comma), to specify the rolloff curve.
lowpass_stop_atten¶
Minimum attenuation in stopband for the lowpass filter. This is the minimum acceptable attenuation, in dB, in the stopband, which is ideally infinitely suppressed, but in practice 30-80 dB are often enough unless there is enormous drift (e.g., with some dry headsets).
highpass_frequencies¶
Low noise frequencies to be filtered out with a highpass filter. You can either give the cutoff frequency as a single value, or two frequencies (separated by a comma), to specify the rolloff curve.
highpass_stop_atten¶
Minimum attenuation in stopband for the highpass filter. This is the minimum acceptable attenuation, in dB, in the stopband, which is ideally infinitely suppressed, but in practice 30-80 dB are enough, depending on the amplitudes of the signals to attenuate.
convolution_method¶
FIRFilter coefficients can be convolved with the input signal using multiple methods. The standard method performs time-domain convolution. For long signals (>214 samples) using filters with a modest number of coefficients (>24), it can be faster to do the convolution in the frequency domain using the overlap-add method.
direction¶
Filtering direction for highpass filter only. This describes how information is propagated during the filter process. Forward means that an event (e.g., a spike) will result in a ripple that follows the event. Forward-backward means that the ripple will propagate in both directions, and will be symmetric around the event, but this results in effects preceding their causes, which can be problematic when performing causality analysis and is not replicable in real time. Gap-aware filtering additionally respects data boundaries (e.g., where bad time windows have been cut out) and does not propagate information across them.
reference_channels¶
Reference channel(s). A list of channel names that were used as the EEG reference during recording. These channel(s) will be excluded from artifact detection/removal and subsequent (optional) interpolation of bad channels. These channel(s) will be inserted back in after cleaning but before optional re-referencing, bad time window removal, and lowpass filtering are applied. This list is only necessary in cases that the reference channel(s) are valid scalp EEG channels (e.g. Cz) to ensure they won't be identified as 'bad' and potentially interpolated. If reference was non-EEG channels such as linked ears or mastoids these channels would automatically be excluded from analyses if 'remove unlocalized chans' is True and this parameter should be left empty.
rereferencing¶
Rereferencing. For common average referencing, enter: CAR. To reference to certain channels, a list of channel labels can be given (as a Python list, or in an ad-hoc comma-separated or space-separated list of channel labels). To skip rereferencing, use '[]'.
sampling_rate¶
Target sampling rate (in Hz).
bad_channel_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.
bad_channel_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.
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.
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.
bad_channel_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.
bad_channels_list¶
If skip bad channel removal is True, this is a list of channel names to mark as bad in place of using the Bad Channel Removal node. The Bad Channel Removal node parameters above will be ignored and this list of channels will be the final channels that get removed from the input data before the downstream processes happen (e.g. artifact removal, re-referencing, interpolation, low-pass filter, etc.).
burst_removal_cutoff¶
Threshold for burst-type 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.
use_clean_window¶
Use clean time windows to calibrate artifact removal thresholds. This applies to all artifact removal steps that involve such a calibration, including bad-channel removal and burst-artifact removal. 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).
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.
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.
protected_channels_during_cleaning¶
Channels to protect from removal during Bad Channel Removal and Artifact Removal. For example, ExG channels that are not in the headmodel and therefore would be removed, but are kept in the data to be used during cleaning Bad Channel and Artifact Removal. These channels are removed after Artifact Removal and before Bad Time Window Removal (and therefore not included in the output data).
clean_signal_range¶
Minimum and maximum of clean signal range, in multiples of standard deviation. 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.
max_bad_channels¶
Maximum fraction of bad channels allowed. 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.30 (very lax cleaning of only coarse artifacts).
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.
window_len¶
Length of sliding window. 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.
bad_window_removal_band¶
Frequency band (as a two- element list), to restrict to when performing Bad Time Window Removal. (A bandpass filter is used only for computing the bad time windows, and is not applied to the data passed on.
fix_unit¶
Runs the FixSignalUnit node to determine the signal unit from the signal data. Sets the unit to uV by default.
desired_unit¶
Desired unit of the signal. If set to keep, then the signal is not altered (but the inferred unit will be stored in the annotation).
scale_factor¶
Scaling factor. The signal is scaled by this factor. Can be used for manual unit conversion.
use_caching¶
Enable caching. This will significantly speed up re-use of the same data.
export_to_h5¶
Export preprocessed data to HDF5 format. (Files will be named and saved in the same folder as the original files.
export_intermediate¶
Types of intermediate data to export to SET format.
remove_unlocalized_chans¶
Remove unlocalized channels. Set to False to allow channels that have no positions or do not match an available montage.
skip_artifact_removal¶
Skip artifact and bad time window removal. For debugging.
skip_bad_channel_removal¶
Skip bad channel removal. For special cases.
skip_bad_window_removal¶
Skip bad time window removal. For special cases.
skip_low_pass_filter¶
Skip low pass filter. For debugging.
skip_high_pass_filter¶
Skip high pass filter. For debugging.
skip_dejitter¶
Skip timestamp dejittering.
skip_interpolate¶
Skip interpolation of missing channels. Channel interpolation results in a less-than-full rank matrix of data. This can be a problem for some signal processing algorithms (e.g. ICA) so it may be desirable to skip interpolation. However, skipping interpolation will likely result in different channel sets for different data chunks. For this reason, interpolation should only be skipped when multi-chunk data will be aggregated in source space and not in sensor space.
lowpass_order¶
Step order to lowpass filter (if not skipped). Default 'end' applies filter at the very last step of the chain, option 'before artifact removal' applies after bad channel removal but before artifact removal, and 'beginning' applies at the start of the chain immediately after highpass filter (before both bad channel removal and artifact removal). It is recommended to only use this option in cases you may encounter high levels of line noise and would discard too much data without first lowpass filtering before the cleaning steps.
asr_legacy¶
Set as True to deal with pymanopt tensorflow library conflicts with ASR.
assign_channel_locations¶
If True, assign channel locations automatically or with specified montage below. If False, this assumes input data already has channel locations (e.g. digitized) in the space axis.
interpolate_to_montage¶
If True and interpolating missing channels, this will interpolate channels into the positions of a standard or specified montage. If False, this will interpolate channels to their internal coordinate positions (this assumes the input data already has digitized electrode positions).
montage¶
Choose the montage to use from among a list of common options. If set to auto, the best-matching montage will be used. This will be ignored if 'assign channel locations' is set to False in which case the input data already has channel locations set in the space axis (e.g. digitized individually).
extra_ar_params¶
A dictionary of params to be passed to Artifact Removal. The keys represent parameters of the Artifact Removal node while the values represent the values to assign to those parameters.
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.