← neural package

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.

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

kept_channels

Names of channels kept after bad channel removal and before interpolation. Not available when processing pre-processed files.

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

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.

• verbose name: Kept Samples
• default value: None
• port type: DataPort
• value type: dict (can be None)
• data direction: INOUT

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.

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

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.

• verbose name: Channels To Import
• default value: all
• port type: Port
• value type: object (can be None)

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.

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

notch_frequency

Target frequency in Hz to remove using a notch filter at the beginning of the preprocessing chain.

• verbose name: Notch Frequency
• default value: 60.0
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Lowpass Frequencies
• default value: [45, 50]
• port type: ListPort
• value type: list (can be None)

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

• verbose name: Lowpass Stop Atten
• default value: 120.0
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Highpass Frequencies
• default value: [0.1, 0.5]
• port type: ListPort
• value type: list (can be None)

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.

• verbose name: Highpass Stop Atten
• default value: 120.0
• port type: FloatPort
• value type: float (can be None)

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.

• verbose name: Method Of Convolution
• default value: standard
• port type: EnumPort
• value type: str (can be None)

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.

• verbose name: Filtering Direction
• default value: forward
• port type: EnumPort
• value type: str (can be None)

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.

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

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 '[]'.

• verbose name: Rereferencing
• default value: CAR
• port type: Port
• value type: object (can be None)

sampling_rate

Target sampling rate (in Hz).

• verbose name: Desired Sampling Rate
• default value: None
• port type: FloatPort
• value type: float (can be None)

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.

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

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.

• verbose name: Bad Channel Noise Threshold
• default value: 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)

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.

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

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

• verbose name: Bad Channels List
• default value: []
• port type: ListPort
• value type: list (can be None)

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.

• verbose name: Burst Removal Cutoff
• default value: 10.0
• port type: FloatPort
• value type: float (can be None)

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

• verbose name: Use Clean Window
• default value: True
• port type: BoolPort
• value type: bool (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: 0
• port type: IntPort
• value type: int (can be None)

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

• verbose name: Protected Channels During Cleaning
• default value: []
• port type: ListPort
• value type: list (can be None)

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.

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

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

• verbose name: Max Bad Channels Allowed (Bad Time Window Removal)
• default value: 0.2
• 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)

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.

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

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.

• verbose name: Bad Window Removal Band
• default value: []
• port type: ListPort
• value type: list (can be None)

fix_unit

Runs the FixSignalUnit node to determine the signal unit from the signal data. Sets the unit to uV by default.

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

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

• verbose name: Desired Unit
• default value: uV
• port type: EnumPort
• value type: str (can be None)

scale_factor

Scaling factor. The signal is scaled by this factor. Can be used for manual unit conversion.

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

use_caching

Enable caching. This will significantly speed up re-use of the same data.

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

export_to_h5

Export preprocessed data to HDF5 format. (Files will be named and saved in the same folder as the original files.

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

export_intermediate

Types of intermediate data to export to SET format.

• verbose name: Export Intermediate
• default value: []
• port type: SubsetPort
• value type: list (can be None)

remove_unlocalized_chans

Remove unlocalized channels. Set to False to allow channels that have no positions or do not match an available montage.

• verbose name: Remove Unlocalized Chans
• default value: True
• port type: BoolPort
• value type: bool (can be None)

skip_artifact_removal

Skip artifact and bad time window removal. For debugging.

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

skip_bad_channel_removal

Skip bad channel removal. For special cases.

• verbose name: Skip Bad Channel Removal
• default value: False
• port type: BoolPort
• value type: bool (can be None)

skip_bad_window_removal

Skip bad time window removal. For special cases.

• verbose name: Skip Bad Window Removal
• default value: False
• port type: BoolPort
• value type: bool (can be None)

skip_low_pass_filter

Skip low pass filter. For debugging.

• verbose name: Skip Low Pass Filter
• default value: False
• port type: BoolPort
• value type: bool (can be None)

skip_high_pass_filter

Skip high pass filter. For debugging.

• verbose name: Skip High Pass Filter
• default value: False
• port type: BoolPort
• value type: bool (can be None)

skip_dejitter

Skip timestamp dejittering.

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

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.

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

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.

• verbose name: Lowpass Order
• default value: end
• port type: EnumPort
• value type: str (can be None)

asr_legacy

Set as True to deal with pymanopt tensorflow library conflicts with ASR.

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

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.

• verbose name: Assign Channel Locations
• default value: True
• port type: BoolPort
• value type: bool (can be None)

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

• verbose name: Interpolate To Montage
• default value: True
• port type: BoolPort
• value type: bool (can be None)

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

• verbose name: Montage
• default value: auto
• port type: ComboPort
• value type: str (can be None)

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.

• verbose name: Extra Ar Params
• default value: {}
• port type: DictPort
• value type: dict (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)