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.

ArtifactDetection

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

Version 1.0.0

Ports/Properties

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

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

Ports/Properties

  • 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)
  • 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)
  • calib_seconds
    Minimum amount of data 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: 45
    • port type: IntPort
    • value type: int (can be None)
  • init_on
    Time range to initialize on. If two numbers are given, either in seconds, or as fractions of the calibration data (if both below 1), then the filter will be initialized only on that subset of the calibration data. Another use case is to select an initial baseline period in a longer recording, in order to avoid having to re-run the (fairly expensive) filter in each fold of a cross-validation.

    • verbose name: Initialize On This Time Range
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • emit_calib_data
    Emit calibration-data chunk. If disabled, this filter will 'eat' the calibration data. Since this chunk is quite long, it can be good 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
    Memory reduction factor during calibration. Data statistics will be estimated in blocks of this many samples and then robustly averaged (make this smaller if you are running out of memory).

    • verbose name: Memory Reduction Factor
    • default value: 10
    • port type: IntPort
    • value type: int (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)
  • 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)
  • use_legacy
    Use legacy option (DEPRECATED)

    • verbose name: Use Legacy
    • 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: [-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)

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

Ports/Properties

  • 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)
  • 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 indicating the channels that are less correlated based on given threshold.

    • 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 can be given as number of channels or, if below 1.0, 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 initialize on. If two numbers are given, either in seconds, or as fractions of the calibration data (if both below 1), then the filter will be initialized only on that subset of the calibration data. Another use case is to select an initial baseline period in a longer recording, in order to avoid having to re-run the (fairly expensive) filter in each fold of a cross-validation.

    • verbose name: Initialize On This Time Range
    • default value: []
    • port type: ListPort
    • value type: list (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)
  • calib_seconds
    Minimum amount of data 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: 20
    • 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)

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.

Version 1.0.1

Ports/Properties

  • 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)
  • 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 have bad data.

    • verbose name: Diagnostic
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • diagnostic_avg_corr
    Diagnostic information indicating the level of channel correlation.

    • verbose name: Diagnostic Avg Corr
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • min_corr
    Correlation threshold. Higher values (above 0.7) are more 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.

    • verbose name: Correlation Threshold
    • default value: 0.7
    • 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: 20
    • 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: Select Filter Type
    • default value: Notch
    • port type: EnumPort
    • value type: object (can be None)
  • calib_seconds
    Minimum amount of data 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: 20
    • port type: IntPort
    • value type: int (can be None)
  • init_on
    Time range to initialize on. If two numbers are given, either in seconds, or as fractions of the calibration data (if both below 1), then the filter will be initialized only on that subset of the calibration data. Another use case is to select an initial baseline period in a longer recording, in order to avoid having to re-run the (fairly expensive) filter in each fold of a cross-validation.

    • verbose name: Initialize On This Time Range
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • emit_calib_data
    Emit calibration-data chunk. If disabled, this filter will 'eat' the calibration data. Since this chunk is quite long, it can be good 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
    Memory reduction factor during calibration. Data statistics will be estimated in blocks of this many samples and then robustly averaged (make this smaller if you are running out of memory).

    • verbose name: Memory Reduction Factor
    • 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)

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.

More Info...

Version 1.0.0

Ports/Properties

  • 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)
  • 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 BakeDesignMatrix node.

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

  • 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)
  • 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: object (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: object (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: object (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 BakeDesignMatrix node.

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

  • 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)
  • 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: object (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 teh 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 BakeDesignMatrix node.

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

Ports/Properties

  • 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)
  • 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: object (can be None)
  • characteristic_range
    Characteristic amplitude range of the signal of interest in a given frequency range.

    • 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: object (can be None)
  • characteristic_frequencies
    Frequency range within which the characteristic signal lies.

    • 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
    Minimum amount of data 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 calibration-data chunk. If disabled, this filter will 'eat' the calibration data. Since this chunk is quite long, it can be good 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)

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. The method used is spherical spline interpolation.

More Info...

Version 0.9.0

Ports/Properties

  • 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)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • 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.

    • verbose name: Desired Channels
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • montage
    Optionally the montage file to use. If not given, the best-matching one will be searched (see node description for more information).

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

PowerBandRatio

Calculates a ratio of precomputed spectral power bands which 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.0

Ports/Properties

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

    • verbose name: Denomenator 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)

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. This node expects a frequency axis, and is therefore typically preceded with a Spectrogram node.

Version 1.0.1

Ports/Properties

  • 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)
  • 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: object (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)
  • 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)
  • 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)
  • 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)

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

Ports/Properties

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

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

Ports/Properties

  • 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)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • 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: object (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)

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

  • 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)
  • 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 BakeDesignMatrix node.

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

SpatioSpectralDecomposition

Extract components that are most representative of a given frequency band.

This method requires two input signals, one is the data bandpass filtered to a particular frequency band of interest, and the other is the same data but bandpass filtered to "noise" frequencies that flank the band of interest. For instance, one may want to find components that maximally emphasize the 8-15Hz band while suppressing activity in the 4-7Hz band and the 16-20Hz band. The resulting components will usually have a better signal-to-noise ratio than the raw channels for the given frequency band 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. This node extracts the peak and noise bands based on the node parameters. However, if necessary, instead of connecting to the node's data port, you can also filter the peak and noise data upstream and feed them into the peak_data and noise_data ports. 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.

Version 1.1.0

Ports/Properties

  • 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)
  • 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 'sidelobs'.

    • verbose name: Peak Noise Gap
    • default value: 1.0
    • port type: FloatPort
    • value type: float (can be None)
  • noise_length
    Size of the noise 'sidelobs', 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 enbaled, 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)

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

  • 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)
  • 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 BakeDesignMatrix 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: object (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: object (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)
  • 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: object (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)