Module: neural

Methods for neural data processing.

This module contains algorithms that are specific to neural time series processing, such as EEG, MEG, ECoG, LPF, or spike trains. These nodes typically are indispensable for appropriate preprocessing of specific modalities.

AddRemoveEvoked

Remove or (re-)add average evoked activity to a given continuous signal.

This can be used to alter the signal baseline for artifact removal in the presence of evoked activity. The node should then be used in a manner where first, the evoked activity is removed, then artifact removal is applied, and then the previously subtracted evoked activity is added back in. Note that segmented data must have already been grouped into conditions by setting the TargetValue field of each instance, which can be accomplished using the AssignTargets node.

Version 0.5.0

Ports/Properties

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

  • data
    Continuous data.

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

  • segmented
    Segmented data.

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

  • operation
    Operation to perform. Remove will subtract the evoked activity captured by the segmented dataset from each trial in the data, while add will add it back in. This can be used to perform certain processing steps in the absence of evoked activity.

    • verbose name: Operation
    • default value: add
    • port type: EnumPort
    • value type: str (can be None)

  • estimator
    Estimator to use for calculating the average evoked activity.

    • verbose name: Estimator
    • default value: mean
    • port type: EnumPort
    • value type: str (can be None)

  • trim_proportion
    Proportion to trim for trim_mean estimator. Applied to both the smallest and largest values in the data.

    • verbose name: Trim Proportion
    • default value: 0.15
    • 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)

ArtifactDetection

Detect artifacts in a sliding window fashion and mark them up with NaNs.

Version 1.1.0

Ports/Properties

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

  • data
    Data to process.

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

  • std_threshold
    Detection threshold in standard deviations. Relative to the baseline window. If the signal amplitude in the detection window is greater than the amplitude in the baseline window by at least this factor, the data is considered artifactual.

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

  • baseline_window
    Baseline window length. In seconds. This window is used to robustly track the expected signal standard deviation.

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

  • detection_window
    Detection window length. This window is used to detect short-duration artifacts.

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

  • drift_window
    Window length for robustly tracking the signal drift.

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

  • lookahead
    Lookahead duration. The node will delay the output signal by this many seconds. Allows to catch sharp-onset artifacts before they are being passed to the downstream pipelines.

    • verbose name: Lookahead
    • default value: 0.075
    • 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)

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

Ports/Properties

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

  • 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 ratio of artifact to the clean eeg.

    • verbose name: Diagnostic
    • 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. The most aggressive value that can be used without losing too much EEG is 2.5. A quite conservative value would be 5.0.

    • 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, usually [-10 15].

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

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

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

  • 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 channes are flagged, and at what time points, as less correlated to their neighbors than the given threshold. This is an internal measure that is used by the node to decide what channels to mark 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, usually [-10 15].

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

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

ChannelRepair

Repair channels during periods where they record garbage data.

This is decided using a correlation threshold, which is the main tunable parameter of the filter that governs the aggressiveness. Important: This filter assumes the the input signal has already been highpass filtered to remove drifts (e.g., using an IIR filter). Also, this filter will not repair channels that are already bad throughout the calibration data -- it is meant to remove temporary glitches (e.g., sensor disconnected). You can precede this filter with a Bad Channel Removal filter to ensure that such channels have already been removed. 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. Also, the correlation statistic is robustly estimated, and there is a tradeoff between quality of this estimate and CPU load (which can be quite heavy) and which can be adjusted through two related parameters. The default setting is tuned for fast processing rather than quality. The statistics gathered on the calibration data are considered "trainable state", and can be saved in model files for later reuse. Note that for the impedance metric, no calibration is necessary if the 'prefer location-based statistics' box is checked, in which case the 'calibration data' length can be set to 0. Impedance is only available for EEG data with an impedance carrier wave present and supported on select devices only.

Version 1.3.1

Ports/Properties

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

  • 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 channels that were flagged as bad based on the metric and threshold.

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

  • diagnostic_avg_corr
    Diagnostic information (the computed per channel values of the selected quality metric, i.e ., correlation, CoV, impedance, etc.). (Note: despite the original port name which was left unchanged for backward compatibility reasons, this port will output the values corresponding to selected metric even if it is not correlation.)

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

  • prior_cov
    Prior covariance matrix.

    • verbose name: Prior Cov
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN

  • metric
    Quality metric. This is a measure of the quality of fit between a robust surrogate of a channel (computed from other channels), and the observed channel itself. Corr is the correlation, and expvar is the explained variance score. Blanket marks everything for repair (re-estimation) and is at best experimental. CoV is specific to NIRS data, and uses the coefficient of variation as the metric, while CoV@ramp is the coefficient of variation normalized by channel length (the cutoff is the equiv to 1cm, e.g. 7.5). CoV@quad is the coeffient of variation normalized to a quadratic curve (example thresholds are 1-1.5); Impedance will compute the impedance and threshold the data based on the computed impedance; it assumes that an impedance carrier wave is present in the data (only supported for certain devices).

    • verbose name: Quality Metric
    • default value: corr
    • port type: EnumPort
    • value type: str (can be None)

  • min_corr
    Quality threshold, for the metric of interest. The most aggressive (impossible to attain) quality level would be 1.0, and 0.0 corresponds to a roughly random (uncorrelated) signal. High values (above 0.7) are quite aggressive and will cause channels to be repaired even when they have only moderate artifacts. Values below 0.5 would be considered rather lax (i.e., only the worst channel artifacts get repaired). This threshold is based on the correlation between a channel and what one would expect the channel to be based on the other channels. For the impedance metric, this threshold is expressed in kOhms and is device dependant (i.e., 2000 kOhms).

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

  • soft_zone
    Soft-threshold zone around min_corr threshold. If the proxy-soft reconstruction method is used, then a sigmoid-type soft threshold is applied at min_corr +/- soft_zone, yielding a soft blend between the original channel content and reconstructed channel content.

    • verbose name: Soft Zone
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)

  • window_len
    Window length to compute correlations. The length of the time windows, in seconds, for which channel quality is computed, i.e. time granularity of the measure. Ideally this is short enough to reasonably capture periods where artifacts happen, but no shorter (otherwise the statistic becomes too noisy and thus unreliable).

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

  • processing_delay
    Acceptable processing delay. This controls the amount by which the filter delays the signal, in seconds. This can be anywhere between 0 and half of the window length. For low-latency real-time operation, this should obviously be as low as possible, but if too low, some sharp-onset artifacts can leave brief knacks in the data.

    • verbose name: Max Processing Delay
    • default value: 0.05
    • 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 can be given as number of channels or, if below 1.0, as a fraction of the total number of channels. Smaller subsets (e.g., 0.1-0.15) together with higher number of Ransac samples (e.g., 50-100) gives a more robust estimate, at increased computational cost, which can be quite substantial.

    • verbose name: Ransac Subset Size
    • default value: 0.25
    • 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 (e.g., 50-100) together with smaller subset sizes (e.g., 0.1-0.15) give a more robust estimate, at higher computational cost.

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

  • location_wise_corr
    Calculate correlation based on channel locations, instead of calibration statistics (experimental). If the amount of collected calibration data was very small, then using channel locations, if known a priori, can result in better correlation statisics, and thus better identification of artifacts. This is primarily for the case where this method is used without a preceding removal of bad channels, and with little initial calibration data.

    • verbose name: Prefer Location-Based Statistics
    • 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)

  • filter_type
    Type of filter to apply to data. Notch filter is an autoregressive moving average (ARMA) model that is best used when wanting to repair bad channels. The lowpass filter method provides better estimates when observing channel correlations for use in diagnostic analyses. These filters only apply if line noise aware is selected.

    • verbose name: Filter Type (If Linenoise Aware)
    • default value: Notch
    • port type: EnumPort
    • value type: str (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)

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

  • chunk_length
    Maximum chunk length for offline processing. Process the data in chunks of no larger than this (to avoid running out of memory).

    • verbose name: Max Offline Processing Chunk Length
    • default value: 50000
    • port type: IntPort
    • value type: int (can be None)

  • calib_precision
    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: 10
    • port type: IntPort
    • value type: int (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. This is available only during offline processing.

    • 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, usually [-10 15].

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

  • gpu_mode
    GPU mode. The -transform modes allow the cricial operation in the optimal and optimal-cached reconstruction modes to be performed efficiently on the GPU using the respective backend. The -core modes perform a broader set of core operations on the GPU. The most efficient of these for transform is currently torch.

    • verbose name: Gpu Mode
    • default value:
    • port type: EnumPort
    • value type: str (can be None)

  • calibration_backend
    Backend for initializing the RANSAC projection. This is a one-time computation, which can however be fairly time consuming for many channels. The multiprocessing, loky, and nestable backends support both the case where location_wise_corr is enabled (use locations) and disabled (use data statistics). Multiprocessing is the simplest, but loky and nestable can be used when the node is itself invoked inside a parallelized computation. The other backends currently only support the case where no locations are provided, but are potentially much faster. Of those, torch-cpu works on the CPU, and the others (tf, jax, cupy, torch) work on the GPU.

    • verbose name: Calibration Backend
    • default value: multiprocessing
    • port type: EnumPort
    • value type: str (can be None)

  • calibration_cores
    Number of cores to use for calibration. The special value -1 stands for all cores.

    • verbose name: Calibration Cores
    • default value: 4
    • port type: IntPort
    • value type: int (can be None)

  • reconstruction
    Reconstruction mode. Optimal is the optimal least-squares reconstruction given the estimated pattern of good/bad channels (can be very slow for >500 channels). Optimal-cached additionally caches the most recent k patterns, and is therefore much faster if the set of bad channels does not change very rapidly (but otherwise it'll just use more memory use without much benefit). Proxy reconstructs a channel with its robust RANSAC proxy; this is less accurate, but is very fast and has no CPU load spikes regardless of how fast bad channels are changing. Nan sets stretches of bad channels to NaN. Proxy-soft blends between the original and proxy data depending on the degree of threshold violation. In blanket mode, simply everything will be replaced by reconstructed data.

    • verbose name: Reconstruction
    • default value: optimal
    • port type: EnumPort
    • value type: str (can be None)

  • use_caching
    Use caching. Only applicable on offline data.

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

  • verbose
    Show verbose output.

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

ClassifyIndependentComponents

Classify independent components using a component classifier.

This categorizes components previously generated by an ICA node such as InfomaxICA into categories such as brain, eye, etc. This node should be used with the following workflow: 1) optional artifact removal (highpass, etc.); if a line-noise removal filter is used, it must be narrow-band (e.g., 1 Hz). 2) Common average reference. 3) ICA. 4) This node.

Version 0.2.0

Ports/Properties

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

  • data
    Data to process.

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

  • classifier
    Classifier to use. Currently, only ICLabel is supported. This appends an additional field to the space axis of the data named 'labels', which has the component classification labels in it. These labels fall into categories such as 'brain', 'muscle', etc.

    • verbose name: Classifier
    • default value: ICLabel
    • port type: EnumPort
    • value type: str (can be None)

  • ensemble_size
    Number of classifiers to use in the ensemble. This is only used if the classifier is ICLabel. The default is the maximum of 6, but a smaller number can be chosen to reduce the compute cost.

    • verbose name: Ensemble Size
    • default value: 6
    • port type: IntPort
    • value type: int (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)

CommonSpatialPatterns

Extract signal components whose variance optimally discriminates between two conditions.

This filter can be used as an adaptive preprocessing step for a multichannel signal, such as EEG, EMG, or MEG, whose variance shall subsequently be used in a classification setup (e.g., to predict some binary target variable, for instance in order to discriminate between two possible cognitive states). The resulting components will usually yield better spectral features than the raw channels, leading to better classification accuracy. This node will calibrate itself if it receives a non-streaming ( offline) chunk that has a time, space, and instance axis, and which has a target value for each instance (similarly to how machine learning nodes operate). Instances correspond to labeled trials, the space axis represents the channels which are being filtered, and time are the time points of each trial segment. Note that CSP must be preceded by a bandpass filter (e.g., FIR or IIR prior to segmentation) that restricts the signal to the frequency band of interest. CSP only works for two classes. CSP and its variants are the standard approach for spatial filtering in such settings, particularly in the brain-computer interface field. Tip: a continuous time series with markers can be segmented into multiple labeled trials / segments using the Assign Target Markers node followed by the Segmentation node. Note that the train data and the test data must have the same name in the Packet (i.e., "eeg") in order for the CSP node to match them.

More Info...

Version 1.0.1

Ports/Properties

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

  • data
    Data to process.

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

  • nof
    Number of spatial pattern pairs to compute. This determines the number of output channels (which is 2x this value) and thus the dimensionality of the feature space. Typical values are 2-4; while one can generate more features (up to the number of input channels), these will be increasingly less useful to the classifier.

    • verbose name: Number Of Pattern Pairs
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • initialize_once
    Do not recalibrate on subsequent offline chunks, even if they include target labels. If False, this node will recalibrate itself on any offline chunk that has data plus target labels.

    • verbose name: Calibrate Only Once
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • cond_field
    The name of the instance data field that contains the conditions to be discriminated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

    • verbose name: Cond Field
    • default value: TargetValue
    • port type: StringPort
    • value type: str (can be None)

  • verbose
    Produce verbose output.

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

EventRelatedPotential

A meta-node that segments and calculates the ERPs for a predefined set of event markers.

Segments the data based on previously assigned targets, if not already segmented. Has a separate data output for ERPImages (not averaged across all trials). Uses the following nodes: SelectRange, nn.FIRFilter, nn.ShiftTimestamps, nn.Segmentation, nn.Rereferencing, nn.Mean.

More Info...

Version 1.0.2

Ports/Properties

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

  • data
    Data to process.

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

  • erp_data
    ERP data.

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

  • erpimage_data
    ERPimage data.

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

  • time_bounds
    Time range in seconds relative to the event, within which data will be selected to represent the individual trials. Express in this format: -1.5, 2 (will select from 1.5 seconds before the event to 2 seconds after).

    • verbose name: Time Bounds
    • default value: [-0.2, 0.6]
    • port type: Port
    • value type: object (can be None)

  • baseline_removal_range
    Time range (in seconds) representing the baseline to be removed from the data.

    • verbose name: Baseline Removal Range
    • default value: -0.2...0
    • port type: Port
    • value type: object (can be None)

  • skip_baseline_removal
    Skip baseline removal (performed later.)

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

  • max_gap_length
    Maximum length of time-stamp gaps that are allowed in segments. If a gap between successive samples is larger than this duration in seconds, then the affected segment is not extracted. Optional. Note that if your time stamps are jittered, this will generate a lot of false positives unless you use a very generous cutoff. You can use the DejitterTimestamps node early during your processing to fix that.

    • verbose name: Max Gap Length
    • default value: 0.2
    • port type: FloatPort
    • value type: float (can be None)

  • channel_range
    Comma separated list of channels/ROIs to be included in the ERP plot and/or for which ERPimages will be created. Leave blank or set to 'all' to plot all previously-select channels/ROIs.

    • verbose name: Channel Range
    • default value: :
    • port type: Port
    • value type: object (can be None)

  • lowpass_cutoff
    Low-pass filter transition band (optional). If given, the data will be low-pass filtered if continuous.

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

  • output_measure
    Output measure to calculate. nn.Mean will be the usual average ERP, while median and trim_mean result in estimates that are more robust to outliers. For moderate artifact content, trim_mean is preferable, and median should only be used for extremely contaminated data. The trials mode will return the raw trials instead of taking the mean, and should be used when statistics will be computed later in the pipeline.

    • verbose name: Output Measure
    • default value: mean
    • port type: EnumPort
    • value type: str (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)

FilterBankCommonSpatialPattern

Extract signal components across multiple bands whose variance optimally discriminates between two conditions.

FBCSP generalizes the basic CSP method to multiple bands (yielding number of bands times number of pattern pairs times 2 channels), and like CSP it can be used as an adaptive preprocessing step for a multichannel signal, such as EEG, EMG, or MEG, whose variance shall subsequently be used in a classification setup (e.g., to predict some binary target variable, for instance in order to discriminate between two possible cognitive states). The resulting components will usually yield better spectral features than the raw channels, leading to better classification accuracy. This node will calibrate itself if it receives a non-streaming (offline) chunk that has a time, space, and instance axis, and which has a target value for each instance (similarly to how machine learning nodes operate). Instances correspond to labeled trials, the space axis represents the channels which are being filtered, and time are the time points of each trial segment. FBCSP should be preceded at least by a highpass filter (e.g., FIR or IIR prior to segmentation). FBCSP only works for two classes. FBCSP is a state-of-the-art spatio-spectral filtering method and is on par with the alternative Spectrally Weighted Common Spatial Patterns (Spec-CSP) method. The main differences are that FBCSP uses predefined bands, while Spec-CSP optimizes the bands on the fly, which can work better, but can also fall short if the optimization ran into a bad local optimum. Since the method can be used with a number of standard frequency bands, it can be used in cases where the correct frequency band is not known, and as such it can be useful in settings where there is little established a priori knowledge on those bands, for instance EEG collected in non-traditional tasks. Since FBCSP will generate a relatively large number of features compared to CSP (by default on the order of 30), many of which are going to be uninformative, it is advisable to use a sparse classifier, such as sparse logistic regression on the resulting features. Tip: a continuous time series with markers can be segmented into multiple labeled trials / segments using the Assign Target Markers node followed by the Segmentation node.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • nof
    Number of pattern pairs to compute per band. This determines the number of output channels for the band ( which is 2x this value) and thus the dimensionality of the feature space. Typical values are 2-4; while one can generate more features ( up to the number of input channels), these will be increasingly less useful to the classifier.

    • verbose name: Number Of Pattern Pairs Per Band
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • bands
    Frequency bands of interest. This is a list of pairs of [low, high] entries, each of which defines another frequency band of interest. Example syntax: [[10,15],[7,30],[15,25]].

    • verbose name: Frequency Bands
    • default value: [[0.5, 3], [4, 7], [8, 12], [13, 30], [31, 42]]
    • port type: ListPort
    • value type: list (can be None)

  • shrinkage
    Shrinkage coefficient for covariance matrix estimation.

    • verbose name: Shrinkage
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)

  • min_fft_size
    Minimum size of the FFT used in spectrum calculation. The chosen value is the greater of this and the next power of 2 greater than the length of the signal.

    • verbose name: Min Fft Size
    • default value: 256
    • port type: IntPort
    • value type: int (can be None)

  • window_func
    Type of window function to use. The data can optionally be windowed using this function, which is especially useful when multiple small overlapped windows are used.

    • verbose name: Window Function
    • default value: hann
    • port type: EnumPort
    • value type: str (can be None)

  • window_param
    Window parameter. Needed to determine the shape of the window if using kaiser, gaussian, slepian, or chebwin.

    • verbose name: Window Parameter
    • default value: None
    • port type: ListPort
    • value type: list (can be None)

  • window_length
    Length of overlapped windows in case of Welch spectral estimation. Using a smaller value (e.g., 1/4-1/8th of the chunk length) yields a smoother spectrum. The default is 1/2 of the chunk length.

    • verbose name: Window Length
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • window_unit
    Unit in which the window length is given.

    • verbose name: Window Length Unit
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • overlap_length
    Amount of overlap of successive windows in Welch method. The default is half of the window length.

    • verbose name: Overlap Length
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • overlap_unit
    Unit in which the overlap window length is given.

    • verbose name: Overlap Window Length Unit
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • initialize_once
    Do not recalibrate on subsequent offline chunks, even if they include target labels. If False, this node will recalibrate itself on any offline chunk that has data plus target labels.

    • verbose name: Calibrate Only Once
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • cond_field
    The name of the instance data field that contains the conditions to be discriminated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

    • verbose name: Cond Field
    • default value: TargetValue
    • port type: StringPort
    • value type: str (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)

FilterBankSourcePowerComodulation

Extract signal components across multiple bands whose variance optimally correlates with some target variable.

FBSPoC generalizes the basic SPoC method to multiple bands (yielding number of bands times number of pattern pairs times 2 channels), and like SPoC it can be used as an adaptive preprocessing step for a multichannel signal, such as EEG, EMG, or MEG, whose variance shall subsequently be used in a regression setup (e.g., to predict some continuous target variable, for instance some cognitive states). The resulting components will usually yield better spectral features than the raw channels, leading to better prediction performance. This node will calibrate itself if it receives a non-streaming (offline) chunk that has a time, space, and instance axis, and which has a target value for each instance (similarly to how machine learning nodes operate). Instances correspond to labeled trials, the space axis represents the channels which are being filtered, and time are the time points of each trial segment. FBSPoC should be preceded at least by a highpass filter (e.g., FIR or IIR prior to segmentation). FBSPoC can be used in all settings where FBCSP would be used, and with the same benefits over SPoC as FBCSP has over CSP. The difference vs. FBCSP is that FBSPoC can predict continuous target variables. Since FBSPoC will generate a relatively large number of features compared to SPoC (by default on the order of 30), many of which are going to be uninformative, it is advisable to use a sparse regression method, such as LASSO regression on the resulting features. Tip: a continuous time series with markers can be segmented into multiple labeled trials / segments using the Assign Target Markers node followed by the Segmentation node.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • nof
    Number of pattern pairs to compute per band. This determines the number of output channels for the band ( which is 2x this value) and thus the dimensionality of the feature space. Typical values are 2-4; while one can generate more features ( up to the number of input channels), these will be increasingly less useful to the classifier.

    • verbose name: Number Of Pattern Pairs Per Band
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • cov_lambda
    Covariance regularization parameter. This parameter (between 0 and 1) controls the amount of shrinkage regularization applied to the covariance matrix estimates. Usually, only a small amount is necessary to prevent degenerate solutions, e.g., when channels are linearly dependent.

    • verbose name: Covariance Regularization Parameter
    • default value: 0.001
    • port type: FloatPort
    • value type: float (can be None)

  • bands
    Frequency bands of interest. This is a list of pairs of [low, high] entries, each of which defines another frequency band of interest. Example syntax: [[10,15],[7,30],[15,25]].

    • verbose name: Frequency Bands
    • default value: [[0.5, 3], [4, 7], [8, 12], [13, 30], [31, 42]]
    • port type: ListPort
    • value type: list (can be None)

  • min_fft_size
    Minimum size of the FFT used in spectrum calculation. The chosen value is the greater of this and the next power of 2 greater than the length of the signal.

    • verbose name: Min Fft Size
    • default value: 256
    • port type: IntPort
    • value type: int (can be None)

  • window_func
    Type of window function to use. The data can optionally be windowed using this function, which is especially useful when multiple small overlapped windows are used.

    • verbose name: Window Function
    • default value: hann
    • port type: EnumPort
    • value type: str (can be None)

  • window_param
    Window parameter. Needed to determine the shape of the window if using kaiser, gaussian, slepian, or chebwin.

    • verbose name: Window Parameter
    • default value: None
    • port type: ListPort
    • value type: list (can be None)

  • window_length
    Length of overlapped windows in case of Welch spectral estimation, in samples. Using a smaller value (e.g., 1/4-1/8th of the chunk length) yields a smoother spectrum. The default is 1/2 of the chunk length.

    • verbose name: Window Length
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • overlap_samples
    Number of samples of overlap between successive windows. This determines by how much successive sub-windows are overlapped. If not given, defaults to half of the sub-window length. Can also be given as a value between 0 and 1, which is then taken as a fraction of the sub-window length (e.g., 0.8).

    • verbose name: Overlap Between Sub-Windows
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)

  • initialize_once
    Do not recalibrate on subsequent offline chunks, even if they include target labels. If False, this node will recalibrate itself on any offline chunk that has data plus target labels.

    • verbose name: Calibrate Only Once
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • block_size
    If the size of the input matrix is too big, we choose perform some of the operation on smaller blocks rather on all trails using full vectorization.

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

  • dont_reset_model
    Do not reset the model when the preceding graph is changed. Normally, when certain parameters of preceding nodes are being changed, the model will be reset. If this is enabled, the model will persist, but there is a chance that the model is incompatible when input data format to this node has changed.

    • verbose name: Do Not Reset Model
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • robust_flag
    If the flag is set the covariance calculation is done robustly.

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

  • target_field
    The name of the instance data field that contains the target variable to be correlated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

    • verbose name: Target Field
    • default value: TargetValue
    • port type: StringPort
    • value type: str (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)

FixSignalUnit

Infer and then correct the unit of an electrophysiological signal (e.g

., EEG). This node works for signals where we expect the data to be in a known characteristic value range, which is customizable (for example, bwetween +/- 10 uV and +/- 100 uV in the case of EEG). To allow for more specificity and robustness against various kinds of artifacts (such as drifts or high-frequency noise), this node also allows selecting a characteristic frequency band in which the signal shall lie in the expected range. Also, for robustness against bad/non-representative channels (e.g., channels with unusually low or high signal amplitude), a fraction of bad channels is by default excluded. Using this information, the node can then estimate the most likely unit of the incoming data. This is often necessary because many file formats and vendors don't do a particularly good job at documenting and/or consistently setting the signal range that their data is measured in. This node can be used very early in the pipeline (basically right after import and/or real-time input). In case that the unit of the signal is rather ambiguous, the node will emit a warning and assume the more likely unit. It is possible to set this node to skip a stream where the unit is already specified in the stream's meta_unit property, though the default setting is to recompute the unit and override the setting in the stream's meta_unit property. The node requires calibration data, the length of which can be configured. The node works both offline and online, and in the online case, the node will collect the required amount of data first before outputting anything.

Version 0.9.4

Ports/Properties

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

  • data
    Data to process.

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

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

  • characteristic_range
    Characteristic amplitude range of the signal of interest in a given frequency range. The defaults are well suited for EEG data but are likely far from optimal for other signal modalities.

    • verbose name: Characteristic Range
    • default value: [10, 100]
    • port type: ListPort
    • value type: list (can be None)

  • characteristic_range_unit
    Unit of the given characteristic range.

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

  • characteristic_frequencies
    Frequency range within which the characteristic signal lies. The default is well suited for EEG, but is likely far from optimal for other signal modalities.

    • verbose name: Characteristic Frequencies
    • default value: [8, 13]
    • port type: ListPort
    • value type: list (can be None)

  • max_bad_channels_fraction
    Max fraction of bad channels. If the signal is known to be clean, this could be lowered, but it should not matter much.

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

  • calib_seconds
    Amount of data, in seconds, to gather for calibration. When this filter is run online and has not yet been calibrated, then it will first buffer this many seconds of data in order to infer the unit before any output is produced.

    • verbose name: Gather This Much Calibration Data
    • default value: 25
    • 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)

  • off_band_slack
    Width of the transition region around the characteristic frequency band in Hz. Signal content in the frequencies within the neighboring regions flanking the characteristic band will also count toawrds the signal amplitude. The running time is inversely proportional to this number (i.e., 2x sharper falloffs around the characteristic band require 2x the compute time.). Note that, if the minimum frequency is below this, this parameter is ignored.

    • verbose name: Off Band Slack
    • default value: 2.0
    • port type: FloatPort
    • value type: float (can be None)

  • off_band_suppression
    Off-band suppression in dB. Larger values will be able to attenuate larger artifacts in the signal outside the characteristic band.

    • verbose name: Off Band Suppression
    • default value: 50
    • port type: FloatPort
    • value type: float (can be None)

  • force_override
    Force recalculation of the unit even if it is already specified in the meta_unit property of the signal stream.

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

  • use_caching
    Enable caching. This will use the results from the last time the same file was processed rather than recompute the unit.

    • verbose name: Use Caching
    • default value: False
    • 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)

ImpedanceChannelRejection

Remove bad channels based on their impedance.

This node is meant to be used on data recorded from hardware with built-in impedance measurement capabilities. Specifically, the data is assumed to have an embedded square wave that is aligned with the sampling time points of the system, and the amplitude of that square wave can be used to infer the impedance (i.e., electrical resistance) of the EEG/EXG sensor. As of this writing, only Cognionics hardware is known to be compatible with this node. 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.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • threshold
    Impedance threshold (Mohms). Channels with impedance higher than this will be rejected.

    • verbose name: Impedance Threshold
    • default value: 2
    • port type: IntPort
    • value type: int (can be None)

  • period
    Embedded impedance signal period (samples). This is the period, in samples, of the impedance signal that is embedded in the data by the sensor.

    • verbose name: Impedance Signal Period
    • default value: 4
    • port type: IntPort
    • value type: int (can be None)

  • unit_conversion
    Factor for converting signal units to volts. This is usually taken care of by the data acquisition system.

    • verbose name: Unit Conversion Factor
    • default value: 1e-06
    • port type: FloatPort
    • value type: float (can be None)

  • calib_seconds
    Amount of data, in seconds, to gather for calibration. When this filter is run online and has not yet been calibrated, then it will first buffer this many seconds of data in order to compute its measures before any output is produced.

    • verbose name: Gather This Much Calibration Data
    • default value: 15
    • port type: IntPort
    • value type: int (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)

InterpolateMissingChannels

Interpolate missing channels in the given data.

Given a list of desired channel labels, this node will attempt to produce an output signal that has all channels in that list, and will interpolate channels that are not present in the data if needed. This node can use spherical-spline or least-squares interpolation.

More Info...

Version 1.5.1

Ports/Properties

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

  • data
    Data to process.

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

  • ref_data
    Reference data. Can be provided as an alternative to the desired_channels.

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

  • prior_cov
    Prior covariance matrix.

    • verbose name: Prior Cov
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN

  • desired_channels
    Desired channels. This node will attempt to ensure that the given channels are present in the output data and interpolate them if necessary. Ignored if ref_data provided.

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

  • montage_type
    Choose the montage to use from among a list of common options. If set to auto, the best-matching montage will be used.

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

  • montage
    Optionally a montage file (.l ocs format) to use. This may be a montage file that ships with Neuropype (available in resources/montages), in which case only the filename is needed, or the full path to a montage located elsewhere. If specified, this will take precedence over the montage type field.

    • verbose name: Montage File
    • default value:
    • port type: StringPort
    • value type: str (can be None)

  • additive_noise_scale
    Scale of additive noise. Optional scale factor for Gaussian noise that can be added to each interpolated channel to prevent rank deficiency. Scale is relative to the overall data's standard deviation (assuming that channels are zero mean).

    • verbose name: Additive Noise Scale
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)

  • mode
    Interpolation mode. The spherical-spline mode will interpolate the channel based on its scalp location using spherical spline interpolation. The other two modes, which require that the prior_cov input is provided, will interpolate the channel using a statistical criterion based on a priori between-channel covariance. The lstsq method uses a least-squares solution, and the pinv method uses the pseudoinverse. The former is in theory more accurate but may leave exact zero channels in the data with greater likelihood than the pinv method.

    • verbose name: Mode
    • default value: spherical-spline
    • port type: EnumPort
    • value type: str (can be None)

  • backend
    Compute backend to use. The cupy and torch backends can be as much as 10x faster on large problems if the system has a CUDA-capable GPU installed. For CPU-only systems, the torch-cpu mode can still yield a substantial speed boost over numpy. Keep means to use whatever was used to create the incoming data.

    • verbose name: Backend
    • default value: keep
    • port type: EnumPort
    • value type: str (can be None)

  • precision
    Numeric precision to use. Can be reduced to save memory (e.g. if running on GPU). Only needed for the largest of problems, and only used by the geometric and huber centroids.

    • verbose name: Precision
    • default value: keep
    • port type: EnumPort
    • value type: str (can be None)

  • min_ev
    Minimum eigenvalue threshold. If left undefined, this will be set according to the precision. If negative, then the absolute value of negative eigenvalues will be used.

    • verbose name: Min Ev
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)

  • randseed
    Random seed to use for interpolation.

    • verbose name: Randseed
    • default value: 12345
    • port type: IntPort
    • value type: int (can be None)

  • verbose
    Show verbose output.

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

PhaseAmplitudeCoupling

Calculates the degree of dependence of the amplitude signal on the phase of the phase signal.

For example, high-frequency or spiking rate activity can be entrained to the trough of a low frequency (e.g., alpha) oscillation. The phases stream and the amplitudes stream must have identical instance and time axes. If they share at least some common items in the space axis, then PAC will be calculated within-channel only for channels that are shared between both inputs.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • phases_stream_name
    Name of the stream that provides the phases.

    • verbose name: Phases Stream Name
    • default value:
    • port type: StringPort
    • value type: str (can be None)

  • amplitudes_stream_name
    Name of the stream that provides the (non-zero) amplitudes.

    • verbose name: Amplitudes Stream Name
    • default value:
    • port type: StringPort
    • value type: str (can be None)

  • pac_metric
    Type of metric to use to calculate phase amplitue coupling value. MI is the Modulation Index, MVL is the Mean Vector Length, and HR is the Height Ratio.

    • verbose name: Metric
    • default value: MI
    • port type: EnumPort
    • value type: str (can be None)

  • n_bins
    Number of bins to divide phases (-pi to +pi).

    • verbose name: N Bins
    • default value: 10
    • port type: IntPort
    • value type: int (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)

PowerBandRatio

Calculates a ratio of precomputed spectral power bands.

The power bands should be present along the feature axis. Allows a weight to be specified for each band, as well as bias constants which are added to the numerator and/or denomenator. Currently only supports numerator and denomenator expressions with one or two operands. The result is only one element along the feature axis, containing the given ratio.

Version 1.0.1

Ports/Properties

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

  • data
    Data to process.

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

  • alpha_weight
    Weight factor for the alpha power band.

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

  • beta_weight
    Weight factor for the beta power band.

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

  • beta1_weight
    Weight factor for the beta power band.

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

  • beta2_weight
    Weight factor for the beta power band.

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

  • delta_weight
    Weight factor for the delta power band.

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

  • gamma_weight
    Weight factor for the gamma power band.

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

  • theta_weight
    Weight factor for the theta power band.

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

  • numerator_bias
    Constant value added to the numerator.

    • verbose name: Numerator Bias
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)

  • denomenator_bias
    Constant value added to the denominator.

    • verbose name: Denominator Bias
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)

  • numerator
    Formula used to calculate the numerator. Currently supports four operators: + - / * and no parentheses.

    • verbose name: Numerator
    • default value:
    • port type: StringPort
    • value type: str (can be None)

  • denomenator
    Formula used to calculate the numerator. Currently supports four operators: + - / * and no parentheses.

    • verbose name: Denomenator
    • default value:
    • port type: StringPort
    • value type: str (can be None)

  • ratio_name
    The name to be given to the ratio in the Feature axis.

    • verbose name: Ratio Name
    • default value: ratio
    • port type: StringPort
    • value type: str (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)

PowerBands

Computes the standard power bands for various units (dB, PSD, relative PSD, sqrt(PSD), with configurable frequency ranges.

Note that frequency ranges are not inclusive, meaning that [1, 4] will include frequencies up to but not including 4.0. Replaces the Frequency axis with a Feature axis with the values of each band and the name of that band. This node does not computer power spectral density. So it expects the incoming packet contains a Frequency axis with PSD, and should be preceded by a node that computes PSD (Spectrogram, Power Spectrum, etc.). This node only groups and averages the specified frequencies to create bands, and optionally converts to DB (if 'dB' selected) and performs 1/f normalization (if 'relativePSD' selected) or sqrt (if 'sqrtPSD' selected).

Version 1.4.0

Ports/Properties

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

  • data
    Data to process.

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

  • unit
    Select unit to be used for computing the band ratios. (RelativePSD is computed by dividing by the sum of all frequencies.)

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

  • correct_for_falloff
    Correct for 1/f frequency fall-off (perform a 1/f^alpha normalization), with an exponent of 1.

    • verbose name: Correct For Falloff
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • average_across_channels
    Average the bands across all channels Set to False to output band values for each channel.

    • verbose name: Average Across Channels
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • delta
    Lower and upper frequencies for the delta band.

    • verbose name: Delta
    • default value: [1, 3]
    • port type: ListPort
    • value type: list (can be None)

  • theta
    Lower and upper frequencies for the theta band.

    • verbose name: Theta
    • default value: [4, 7]
    • port type: ListPort
    • value type: list (can be None)

  • alpha
    Lower and upper frequencies for the alpha band.

    • verbose name: Alpha
    • default value: [8, 15]
    • port type: ListPort
    • value type: list (can be None)

  • beta
    Lower and upper frequencies for the beta band.

    • verbose name: Beta
    • default value: [16, 31]
    • port type: ListPort
    • value type: list (can be None)

  • gamma
    Lower and upper frequencies for the gamma band.

    • verbose name: Gamma
    • default value: [32, 40]
    • port type: ListPort
    • value type: list (can be None)

  • custom_bands
    User defined frequency bands. You can define as many as you like, with custom names and frequency ranges. Specify as a python dictionary, in the following format: {'theta2': [6,7], 'beta3': [25,31]}. If this parameter is specified, only these bands will be computed and the values specified in the standard band ports (delta, theta, etc.) will be ignored.

    • verbose name: Custom Bands
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • mean_trim
    An optional trim (using a winsorized mean) to be applied to each listed band when calculating the mean, where 0.1 will trim the top and bottom 10% of values. Expressed in the following format: {'beta': 0.1, 'alpha': 0.1} which will apply a 0.1 trim to both beta and alpha.

    • verbose name: Mean Trim
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • keep_numeric_band_in_names
    Keep the bandwidth in the new feature axis names. This will yield feature axis names similar to e.g. alpha2 (10.0-15.0 Hz)

    • verbose name: Keep Numeric Band In Names
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • verbose
    Print verbose output.

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

PreprocessEEG

A meta-node that 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 and not recommended for use in machine-learning use cases. Performs the following operations in order: SelectRange, AssignChannelLocations, FixSignalUnit, Resample, DejitterTimestamps, Scaling, RemoveUnlocalizedChannels, ExtractChannels, Rereferencing, FIRFilter (highpass), BadChannelRemoval, ArtifactRemoval, InterpolateMissingChannels, Rereferencing, RemoveBadTimeWindows, FIRFilter (lowpass), ShiftTimestamps, with optional exports at each stage.

Version 1.3.2

Ports/Properties

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

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

  • 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_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)

  • 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. The most aggressive value that can be used without losing too much EEG is 3. A quite conservative value would be 10.0.

    • 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. Use values between [-10 15].

    • 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: False
    • 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)

  • 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 processed 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 results to export.

    • 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_dejitter
    Skip timestamp dejittering.

    • verbose name: Skip Dejitter
    • default value: False
    • 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_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)

  • montage
    Choose the montage to use from among a list of common options. If set to auto, the best-matching montage will be used.

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

RejectIndependentComponents

Automatically reject independent components that have previously been classified into artifact types.

This requires that the data has been decomposed into ICs and that the ICs have been classified into artifact types. This node should be used with the following workflow: 1) optional artifact removal (highpass, etc.). 2) Common average reference. 3) ICA (e.g., InfomaxICA). 4) ClassifyIndependentComponents. 5) This node.

Version 0.3.0

Ports/Properties

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

  • data
    Data to process.

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

  • rejected_list
    List of rejected component numbers.

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

  • thresholds
    Confidence thresholds for each artifact class. This is a dictionary mapping class names to threshold values (with 1.0 being 100% confidence). Classes that are not listed will not be rejected.

    • verbose name: Thresholds
    • default value: {'muscle': 0.8, 'eye': 0.8, 'cardiac': 0.8, 'line noise': 0.8}
    • port type: DictPort
    • value type: dict (can be None)

  • backproject
    Back-project to channel space. If enabled, the retained components will be back-projected to channel space.

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

  • verbose
    Enable verbose output.

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

RemoveBadTimeWindows

This function cuts segments from the data which contain high/low-amplitude artifacts.

Specifically, any windows with more than a certain fraction of "bad" channels are removed, where a channel is bad in a given window if its amplitude in the window is above or below a given upper/lower threshold (in standard deviations from a robust estimate of the EEG amplitude distribution for the channel). This node only operates on non-streaming data.

Version 1.1.0

Ports/Properties

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

  • 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 time windows with clean data.

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

  • kept_samples
    dict with chunk names for keys and time-axis selector as values. This output is useful to slice another parallel chunk to keep it the same size, even though its channels should not be used to determine bad time windows.

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

  • zscore_thresholds
    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. Use values between [-10 15].

    • 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.3 (very lax cleaning of only coarse artifacts).

    • verbose name: Maximum Fraction Of Bad Channels
    • default value: 0.2
    • 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
    • default value: 0.5
    • port type: FloatPort
    • value type: float (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, in expense of being slower.

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

  • max_dropout_fraction
    Maximum fraction of windows with signal dropouts. This is the maximum fraction of time windows that may have arbitrarily low amplitude (e.g., due to the sensors being unplugged). This parameter is used in generalized Gaussian distribution fitting.

    • verbose name: Maximum Fraction Of Dropout Windows
    • default value: 0.1
    • port type: FloatPort
    • value type: float (can be None)

  • min_clean_fraction
    Minimum fraction of clean windows. This is the minimum fraction of time windows that need to contain uncontaminated EEG.This parameter is used in generalized Gaussian distribution fitting.

    • verbose name: Minimum Fraction Of Clean Windows
    • default value: 0.25
    • port type: FloatPort
    • value type: float (can be None)

  • truncate_quantile
    Truncated Gaussian quantile. Upper and lower quantile range of the truncated Gaussian distribution that shall be fit to the EEG contents. This parameter is used in generalized Gaussian distribution fitting.

    • verbose name: Truncated Gaussian Quantile
    • default value: [0.022, 0.6]
    • port type: ListPort
    • value type: list (can be None)

  • step_sizes
    Grid search stepping. Step size of the grid search. the first value is the stepping of the lower bound (which essentially steps over any dropout samples), and the second value is the stepping over possible scales (i.e., clean-data quantiles). This parameter is used in generalized Gaussian distribution fitting.

    • verbose name: Grid Search Step Size
    • default value: [0.01, 0.01]
    • port type: ListPort
    • value type: list (can be None)

  • shape_range
    Shape parameter range. Search Range for the clean EEG distribution's shape parameter beta. This parameter is used in generalized Gaussian distribution fitting.

    • verbose name: Range For Shape Parameter
    • default value: [1.7, 1.8499999999999999, 1.9999999999999998, 2.1499999999999995, 2.3, 2.4499999999999993, 2.5999999999999996, 2.749999999999999, 2.8999999999999995, 3.049999999999999, 3.1999999999999993, 3.3499999999999988, 3.499999999999999]
    • port type: ListPort
    • value type: list (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)

RemoveOutlierTrials

Removes trials (instances) that have abnormally large signal values.

This node supports offline data. The node requires that the given data has an instance axis, which indexes multiple "trials", or "observations". The node calculates a measure of outlyingness for each such trial using a measure of choice, and removes trials whose measure is above a certain settable threshold (in robust standard deviations) from the data distribution.

Version 1.1.0

Ports/Properties

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

  • data
    Data to process.

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

  • transformation
    Optional data transformation to apply before calculating the measure. The temporal-difference operation calculates successive differences along time.

    • verbose name: Transformation
    • default value: raw
    • port type: EnumPort
    • value type: str (can be None)

  • measure
    Measure to use. The trial norm is the root mean square (RMS) value of the whole trial, while the max-channel norm is the maximum RMS value across all channels (requires a space axis to be present).

    • verbose name: Measure
    • default value: trial-norm
    • port type: EnumPort
    • value type: str (can be None)

  • threshold
    Removal threshold in standard deviations.

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

  • verbose
    Verbose output.

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

SourcePowerComodulation

Extract signal components whose variance is is maximally correlated to a target variable of interest.

This filter can be used as an adaptive preprocessing step for a multichannel signal, such as EEG, EMG, or MEG, whose variance shall subsequently be used in a regression setup (e.g., to predict some continuous target variable, for instance some cognitive state). This node will calibrate itself if it receives a non-streaming (offline) chunk that has a time, space, and instance axis, and which has a target value for each instance (similarly to how machine learning nodes operate). Note that SPoC should be preceded by a bandpass filter (e.g., FIR or IIR) that restricts the signal to the frequency band of interest. This method can also be thought of as the canonical generalization of CSP from binary classification to regression. Tip: a continuous time series with markers can be segmented into multiple labeled trials / segments using the Assign Target Markers node followed by the Segmentation node.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • nof
    Number of spatial pattern pairs to compute. This determines the number of output channels (which is 2x this value) and thus the dimensionality of the feature space. Typical values are 2-4; while one can generate more features (up to the number of input channels), these will be increasingly less useful to the classifier.

    • verbose name: Number Of Pattern Pairs
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • cov_lambda
    Covariance regularization parameter. This parameter (between 0 and 1) controls the amount of shrinkage regularization applied to the covariance matrix estimates. Usually, only a small amount is necessary to prevent degenerate solutions, e.g., when channels are linearly dependent.

    • verbose name: Covariance Regularization Parameter
    • default value: 0.001
    • port type: FloatPort
    • value type: float (can be None)

  • initialize_once
    Do not recalibrate on subsequent offline chunks, even if they include target labels. If False, this node will recalibrate itself on any offline chunk that has data plus target labels.

    • verbose name: Calibrate Only Once
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • target_field
    The name of the instance data field that contains the target variable to be correlated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

    • verbose name: Target Field
    • default value: TargetValue
    • port type: StringPort
    • value type: str (can be None)

  • verbose
    Produce verbose output.

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

SpatioSpectralDecomposition

Extract components that are most representative of a given "peak" signal.

This node has two alternative modes depending on the input ports used. First, one can provide unfiltered data into the data port. In this case, this node will separate the input signal to a "peak" signal and a "noise" signal using FIR filters designed based on the node's other parameters. For example, the default settings will find components that maximally emphasize the 8-15 Hz band while suppressing activity in the 4-7 Hz and 16-20 Hz bands. Second, one can provide pre-filtered signals directly to the peak_data port and the noise_data port. In that case, it is a good idea to make sure that the two bandpass filters that feed into this node have approximately (or exactly) the same filter order, which could be ensured by setting the order in those filters. The resulting components will usually have a better signal-to-noise ratio than the raw channels for the given frequency band or "peak" signal of interest. This filter is meant to operate on continuous data, i.e., it should not be preceded by a Segmentation node. Also, this filter can adapt itself online, i.e., without the need to buffer calibration data. However, keep in mind that initially the filter will not be perfectly adjusted, and the exact sources that it picks up may change over time, especially at the beginning. If you are using machine learning among the downstream nodes, these could be negatively impacted by this.

Version 1.1.0

Ports/Properties

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

  • data
    Unfiltered data (will be filtered in node).

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

  • peak_data
    Data already filtered to the peak freq band.

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

  • noise_data
    Data already filtered to the noise freq bands.

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

  • out_data
    Output data.

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

  • peak_frequency_bounds
    Lower and upper frequency bounds for the peak data. The upper frequency band value is non inclusive.

    • verbose name: Peak Frequency Bounds
    • default value: [8, 15]
    • port type: ListPort
    • value type: list (can be None)

  • peak_noise_gap
    Gap, in Hz, between the peak frequencies and the noise 'side lobes'.

    • verbose name: Peak Noise Gap
    • default value: 1.0
    • port type: FloatPort
    • value type: float (can be None)

  • noise_length
    Size of the noise 'side lobes', in Hz.

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

  • filter_order
    Filter used used for the FIRFilter when extracting peak and noise data from the data packet.

    • verbose name: Filter Order
    • default value: 500
    • port type: IntPort
    • value type: int (can be None)

  • nof
    Number of spatial filters to learn. This determines the number of output channels. The first few filters are the most useful, so only a small number of filters is usually necessary.

    • verbose name: Number Of Filters To Learn
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • streaming_update
    Perform streaming (online) updates. If enabled, the filter will update itself in an online fashion; otherwise it requires a non-streaming calibration recording at first.

    • verbose name: Perform Streaming Updates
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • half_time
    Time constant of adaptive filter, in seconds. Data that lies this many seconds in the past will be weighted half as much as the most recent data when designing the filter, and data twice as old will be weighted by 1/4, etc. Can also be thought of as the half-time of an exponentially weighted filter.

    • verbose name: Adaptive Filter Time Constant
    • default value: 120
    • port type: FloatPort
    • value type: float (can be None)

  • shrinkage
    Shrinkage regularization parameter. This parameter (between 0 and 1) controls the amount of shrinkage regularization applied to the filter estimates. Usually, only a small amount is necessary to prevent degenerate solutions, e.g., when channels are linearly dependent.

    • verbose name: Shrinkage Regularization
    • default value: 0.01
    • port type: FloatPort
    • value type: float (can be None)

  • model_format
    Format of the model of this node. The packet format is a packet with all relevant matrices as separate streams. The legacy format is a dictionary of 3 dictionaries (filters, peak_cov, noise_cov) of matrices, one per stream.

    • verbose name: Model Format
    • default value: packet
    • port type: EnumPort
    • value type: str (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)

SpectrallyWeightedCommonSpatialPattern

Extract spatio-spectral signal components whose variance optimally discriminates between two conditions.

Spec-CSP generalizes the basic CSP method to include spectral filters, and like CSP it can be used as an adaptive preprocessing step for a multichannel signal, such as EEG, EMG, or MEG, whose variance shall subsequently be used in a classification setup (e.g., to predict some binary target variable, for instance in order to discriminate between two possible cognitive states). The resulting components will usually yield better spectral features than the raw channels, leading to better classification accuracy. This node will calibrate itself if it receives a non-streaming (offline) chunk that has a time, space, and instance axis, and which has a target value for each instance (similarly to how machine learning nodes operate). Instances correspond to labeled trials, the space axis represents the channels which are being filtered, and time are the time points of each trial segment. Spec-CSP should be preceded at least by a highpass or bandpass filter (e.g., FIR or IIR prior to segmentation). Spec-CSP only works for two classes. Spec-CSP is a state-of-the-art spatio-spectral filtering method, and has been shown to be on par with alternative methods such as CSSP and CSSSP. Another spectral alternative is Filter-Bank Common Spatial Patterns (FBCSP). Since the method learns a good spectral filter by itself, it can be used in cases where the relevant frequency band is not known, and as such it can be useful in settings where there is little established a priori knowledge on those bands, for instance EEG collected in non-traditional tasks. Tip: a continuous time series with markers can be segmented into multiple labeled trials / segments using the Assign Target Markers node followed by the Segmentation node.

Version 1.0.0

Ports/Properties

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

  • data
    Data to process.

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

  • cond_field
    The name of the instance data field that contains the conditions to be discriminated. This parameter will be ignored if the packet has previously been processed by a DescribeStatisticalDesign node.

    • verbose name: Cond Field
    • default value: TargetValue
    • port type: StringPort
    • value type: str (can be None)

  • nof
    Number of spatio-spectral pattern pairs to compute. This determines the number of output channels (which is 2x this value) and thus the dimensionality of the feature space. Typical values are 2-4; while one can generate more features (up to the number of input channels), these will be increasingly less useful to the classifier.

    • verbose name: Number Of Pattern Pairs
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • shrinkage
    Shrinkage coefficient for covariance matrix estimation.

    • verbose name: Shrinkage
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)

  • prior_freq_range
    A priori choice of relevant frequency band. The method will find optimal spectral weightings within that band.

    • verbose name: Frequency Band Limits
    • default value: [7, 30]
    • port type: ListPort
    • value type: list (can be None)

  • reg_param_p
    Regularization parameter p. Can be tuned in the range -1..+1 if desired, but the default value is a good choice.

    • verbose name: Regularization Parameter P
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)

  • reg_param_q
    Regularization parameter q. Can be tuned in the range 0..4 if desired, but the default value is a good choice.

    • verbose name: Regularization Parameter Q
    • default value: 1
    • port type: FloatPort
    • value type: float (can be None)

  • iterations
    Number of iterations for spatio-spectral filter optimization. Should not be lower than 3, but higher values have not been shown to be effective.

    • verbose name: Iterations
    • default value: 3
    • port type: IntPort
    • value type: int (can be None)

  • spectrum_method
    Method for calculating the spectral weighting. The Welch and Multitaper methods, respectively, allow for controlling the smoothness of the spectrum, which can yield better-behaved spectral filters.

    • verbose name: Spectrum Method
    • default value: Periodogram
    • port type: EnumPort
    • value type: str (can be None)

  • min_fft_size
    Minimum size of the FFT used in spectrum calculation. The chosen value is the greater of this and the next power of 2 greater than the length of the signal.

    • verbose name: Min Fft Size
    • default value: 256
    • port type: IntPort
    • value type: int (can be None)

  • multitaper_time_halfbandwidth_product
    Spectral smoothing parameter for multi-taper. Technically this is the time-halfbandwidth product, and typical values lie in the range of 2.5 to 5 (in increments of 0.5)

    • verbose name: Multitaper Spectral Smoothing
    • default value: 2.5
    • port type: FloatPort
    • value type: float (can be None)

  • multitaper_num_tapers
    Number of tapers in multi-taper method. The default is 2 times the time-halfbandwidth product minus 1.

    • verbose name: Multitaper Num Tapers
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • welch_window_length
    Length of overlapped windows in case of Welch spectral estimation, can be either in samples or seconds. Using a smaller value (e.g., 1/4-1/8th of the chunk length) yields a smoother spectrum. The default is 1/2 of the chunk length.

    • verbose name: Welch Window Length
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • welch_window_unit
    Unit in which the window length is given.

    • verbose name: Welch Window Length Unit
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • welch_overlap_length
    Amount of overlap of successive windows in Welch method, it can be either in samples, seconds or even percentage of the window length. The default is half of the window length.

    • verbose name: Welch Overlap Length
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • epsilon
    Small value to prevent division by zero. This is only needed on challenging data.

    • verbose name: Epsilon
    • default value: 1e-15
    • port type: FloatPort
    • value type: float (can be None)

  • welch_overlap_unit
    Unit in which the overlap window length is given.

    • verbose name: Overlap Window Length Unit
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • initialize_once
    Do not recalibrate on subsequent offline chunks, even if they include target labels. If False, this node will recalibrate itself on any offline chunk that has data plus target labels.

    • verbose name: Calibrate Only Once
    • 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)