Module: spectral

Spectral estimation and transform nodes.

These nodes operate on the frequency spectrum of the given data. Some nodes will transform from a time-domain representation (packets with a time axis) to a frequency-domain or time/frequency-domain representation. Also includes some nodes that act on the frequency spectrum even though the input is in the time domain.

Coherence

Calculate the magnitude-spared spectral coherence between any channel and all others.

For multi-channel time series, this is a measure of the coupling strength or synchrony between the individual channels. To yield a low-noise and smooth estimate, the Welch method is used, which computes the coherence in multiple successive (and usually overlapping) sub-windows within the moving window and averages the results. The frequency resolution can be increased by using longer (and therefore fewer) windows, but this comes with a cost of increased noise. The most common use case for either node is to apply it to segmented data ( i.e., following the Segmentation node), which will compute the coherence for each segment of the data. Another use case is to apply it in an offline fashion on an entire recording ( which yields the average spectral coherence of that recording). It is not useful to apply this node on streaming data without any buffering or segmentation, because this would try to estimate the coherence on the very short chunks of data without any averaging across chunks, yielding bad data. There is a node that was specifically made for this task, called Moving window coherence, and this will yield much better results in this scenario. At a technical level, this node will replace the time axis of the data by a frequency axis (since time is averaged out), but it will add a dummy time axis with one entry that is annotated with the average time value of the former time axis ( this is so that that information is not lost). It will also add a second space axis with the same number of channels, since coherence is calculated between all pairs of channels. If you need to remove the dummy time axis, e.g., because some subsequent node cannot handle multiple axes in the data, you can use the Fold Into Axis node to fold it into some other axis, e.g., space. You can also flatten the two space axes into a single longer space axis, simply by setting the flat space axis parameter.

More Info...

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

  • segment_samples
    Sub-window length for averaging. This node will extract successive windows from the given data of this length, which are overlapped according to the overlap samples parameter. Longer windows will give a higher spectral resolution (but potentially less smooth and more noisy).

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

  • overlap_samples
    Number of samples of overlap between successive sub-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)

  • window
    Type of window function to apply to sub-windows. Different functions have different spectral and temporal localization characteristics. One of the simplest well-behaved smooth windows is the Hann window (the default).

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

  • detrend
    Sub-window detrending method. In the Welch method, linear trends or constant offsets can be removed from each window prior to spectral estimation.

    • verbose name: Sub-Window Detrending
    • default value: constant
    • port type: EnumPort
    • value type: str (can be None)

  • onesided
    Return one-sided spectrum. If disabled, a two-sided (meaning: symmetric about the middle) spectrum will be computed, which is redundant for real-valeud data, but required for complex-valued data (for complex data, the spectrum is always two-sided.

    • verbose name: Onesided Spectrum For Real-Valued Data
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • fft_size
    Length of the FFT used. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the sub-window length.

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

  • flat_space_axis
    Flatten the two space axes into one. If checked, only one space axis with N squared channels will be returned. If False (the default), an array with two space axes is returned.

    • verbose name: Flat Space Axis
    • 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)

ContinuousWaveletTransform

Calculate a spectrogram (periodogram) of the given data using the Continuous Wavelet Transform (CWT).

The node will compute a new data array with a typically coarser time axis than the original data, and an additional frequency axis, thus yielding an estimate how the spectral content in the data changes over time. This node is most commonly applied to segmented data, i.e., following a Segmentation node -- in this case, it will compute a time/frequency representation for each segment in the data. The node can also be used on continuous data to yield the time-frequency representation for the data, but this can only be applied to a whole recording at once (i.e., non-streaming), and it will not work on streaming continuous (unsegmented) data. The covered frequency range can be controlled (indirectly) by adjusting the scale range parameter. The output of this node is complex if a complex wavelet was used, and real-valued otherwise.

More Info...

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

  • scale_range
    Range of wavelet scales.

    • verbose name: Scale Range
    • default value: [1, 129]
    • port type: ListPort
    • value type: list (can be None)

  • wavelet
    Wavelet type to use.

    • verbose name: Wavelet
    • default value: cmor
    • port type: EnumPort
    • value type: str (can be None)

  • bandwidth_frequency
    Bandwidth Frequency(Hz). This is needed only for cmor, fbsp, and shan wavelets.

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

  • central_frequency
    Central Frequency (Hz). This is needed only for cmor, fbsp, and shan wavelets.

    • verbose name: Central Frequency
    • default value: 1.5
    • 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)

EventRelatedSpectralPerturbation

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

Uses the following nodes: SelectRange, Segmentation, Spectrogram, FrequencyNormalization, ToDecibels, Rereferencing, Mean.

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

  • spectogram_subwindow_length
    Length of the sub-windows for spectral estimation, in seconds. This node will extract successive windows from the given data of this length, which are overlapped according to the overlap samples parameter. Longer windows will give a higher-resolution spectrum, but at the same time the result will increase the smoothness (i.e., blurriness) along the time axis. The tradeoff between time resolution and frequency resolution that can be adjusted via this parameter is fundamental.

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

  • spectrogram_overlap
    Overlap between successive sub-windows, expressed as a fraction of the sub-window length. This determines by how much successive sub-windows are overlapped. Using a higher value will yield finer stepping in time without a change in temporal or frequency detail (since the time axis will be correspondingly more smooth to counter the finer stepping). If not given, defaults to half of the sub-window length. Can also be expressed in samples.

    • verbose name: Spectrogram Overlap
    • default value: 0.95
    • port type: FloatPort
    • value type: float (can be None)

  • spectogram_fft_size
    Length of the FFT used, in samples. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency or temporal detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the sub-window length.

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

  • spectogram_unit
    Unit in which the sub-window length is expressed. By default this is seconds, but samples can also be used if necessary.

    • verbose name: Unit Used For Sub-Window Length.
    • default value: seconds
    • port type: EnumPort
    • value type: str (can be None)

  • frequency_normalization_alpha
    The exponent of 1/f^alpha used in the correction. Set to None to determine the value automatically.

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

  • 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: ListPort
    • value type: list (can be None)

  • frequency_range
    Frequency range for which to plot the ERSP.

    • verbose name: Frequency Range
    • default value: 1...45
    • port type: Port
    • value type: object (can be None)

  • baseline_removal_range
    Reference time range relative to the event for removing the baseline.

    • verbose name: Baseline Removal Range
    • default value: -0.5...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 for which an ERSP plot will be generated. Leave blank or set to 'all' to generate ERSP plots for all previously-selected channels/ROIs.

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

  • output_measure
    Output measure to calculate. 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, for averaging later using the GroupedMean for example.

    • verbose name: Output Measure
    • default value: trials
    • port type: EnumPort
    • value type: str (can be None)

  • cache_spectrogram
    Enable caching for Spectrogram. This will significantly speed up re-use of the same data.

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

FastFourierTransform

Calculate the (one-dimensional) Fast Fourier Transform (FFT) of the given data along some axis.

This is the raw math operation that emits complex-valued data; for nodes that calculate the power spectrum of signals, see the WelchSpectrum and MultitaperSpectrum nodes. This node is useful for full control over the FFT operation or for highly custom use cases. You can configure the frequency resolution of the output using the fft_size parameter (see help text). The node supports all three common normalization modes, and in case of real-valued input data, the node can optionally produce a one-sized spectrum (equivalent to the RFFT operation in common numerical libraries). This node will replace the original axis of the data by a frequency axis, carrying over the axis label, if any. In contrast to the WelchSpectrum etc nodes, this node will not retain a dummy one-element time axis.

More Info...

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: AnyNumeric (can be None)
    • data direction: INOUT

  • axis
    Axis along which the FFT will be calculated. You can also enter the axis label here as in time.mylabel. If the data is not a packet, any named axis will translate to -1.

    • verbose name: Axis
    • default value: time
    • port type: ComboPort
    • value type: str (can be None)

  • n
    Length of the FFT used, in samples. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency or temporal detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the size of the data along that axis. The implementation is equivalent to either zero-padding or truncating the data to the given length before calculating the FFT.

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

  • normalization
    Normalization to apply to the FFT. Backward means that the forward FFT is unscaled and the corresponding inverse FFT is scaled by 1/n. Ortho means that both the forward and inverse FFT are scaled by 1/sqrt(n). Forward means that the forward FFT is scaled by 1/n and the corresponding inverse FFT is unscaled.

    • verbose name: Normalization
    • default value: backward
    • port type: EnumPort
    • value type: str (can be None)

  • onesided
    Return one-sided spectrum. If disabled, a two-sided (meaning: symmetric about the middle) spectrum will be computed, which is redundant for real-valued data, but required for complex-valued data (for complex data, the spectrum should always be two-sided). This is equivalent to the FFT / RFFT distinction in numerical subroutines, e.g., numpy.

    • verbose name: Return One-Sided Spectrum
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • partition_axis
    Axis along which to partition the computation. This can be used to reduce the memory requirements on large data.

    • verbose name: Partition Axis
    • default value: disabled
    • port type: ComboPort
    • value type: object (can be None)

  • num_partitions
    Number of partitions to use. The memory usage is divided by this amount. Requires that partition_axis is set to something other than disabled.

    • verbose name: Num Partitions
    • default value: 4
    • 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)

InverseFastFourierTransform

Calculate a time-domain signal from its frequency representation using the inverse Fast Fourier Transform (IFFT).

This node will replace the original (e.g., frequency) axis of the data by a time axis, carrying over the axis label, if any.

More Info...

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: AnyNumeric (can be None)
    • data direction: INOUT

  • axis
    Axis along which the IFFT will be calculated. You can also enter the axis label here as in frequency.mylabel. If the data is not a packet, any named axis will translate to -1.

    • verbose name: Axis
    • default value: frequency
    • port type: ComboPort
    • value type: str (can be None)

  • n
    Length of the output axis, in samples. Note that if this is given and differs from the size of the input, the input is either cropped or zero-padded. In the latter case, this can give unexpected results; please see the documentation of the numpy FFT algorithm for details.

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

  • normalization
    Normalization to apply to the FFT. Backward means that the forward FFT is unscaled and the corresponding inverse FFT is scaled by 1/n. Ortho means that both the forward and inverse FFT are scaled by 1/sqrt(n). Forward means that the forward FFT is scaled by 1/n and the corresponding inverse FFT is unscaled.

    • verbose name: Normalization
    • default value: backward
    • port type: EnumPort
    • value type: str (can be None)

  • onesided
    Assume one-sided spectrum. If this is set, the input must be a one-sided (and complex-valued) spectrum, and the output will be a real-valued signal. Otherwise the output will be a complex-valued signal. This is equivalent to the RFFT / IRFFT distinction in numerical subroutines, e.g., numpy.

    • verbose name: Assume One-Sided Spectrum
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • partition_axis
    Axis along which to partition the computation. This can be used to reduce the memory requirements on large data.

    • verbose name: Partition Axis
    • default value: disabled
    • port type: ComboPort
    • value type: object (can be None)

  • num_partitions
    Number of partitions to use. The memory usage is divided by this amount. Requires that partition_axis is set to something other than disabled.

    • verbose name: Num Partitions
    • default value: 4
    • 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)

LombScargleSpectrum

Calculate the power spectrum of the given data using the Lomb-Scargle method, which is intended for unevently sampled data.

More Info...

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

  • normalize
    Compute normalized periodogram.

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

  • pre_center
    Pre-center amplitudes by subtracting the mean.

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

  • n_out
    Number of data points in frequency array.

    • verbose name: Data Points
    • default value: 1000
    • port type: IntPort
    • value type: int (can be None)

  • min_freq
    Minimum frequency of frequency array in Hertz.

    • verbose name: Minimum Frequency (Hz)
    • default value: 0.01
    • port type: FloatPort
    • value type: float (can be None)

  • max_freq
    Maximum frequency of frequency array in Hertz.

    • verbose name: Maximum Frequency (Hz)
    • default value: 100
    • 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)

MultitaperSpectrum

Calculate the power spectral density (PSD) of the given data using the Multi-taper method.

This is a high-quality spectral estimator, which averages the spectrum over multiple reweighted ("tapered") windows. The spectrum can be smoothed by increasing the time-halfbandwidth product parameter, which yields a less noisy spectrum. There is also an alternative drop-in replacement for this node, called WelchSpectrum, that uses a different method that is slightly faster to compute but yields somewhat lower-quality spectra. The most common use case for either node is to apply it to segmented data (i.e., following the Segmentation node), which will compute the spectrum for each segment of the data. Another use case is to apply it in an offline fashion on an entire recording (which yields the average power spectrum of that recording). It is not useful to apply this node on streaming data without any buffering or segmentation, because this would try to estimate the spectrum on the very short chunks of data without any averaging across chunks, yielding bad data. Therefore for streaming data, this node should be preceded by the MovingWindow node (or Segmentation). At a technical level, this node will replace the time axis of the data by a frequency axis (since time is averaged out), but it will add a dummy time axis with one entry that is annotated with the average time value of the former time axis (so that that information is not lost). If you need to remove this axis later on, but want to retain that information you can use Fold Into Axis node to include that into some other axis (usually that would be space, i.e., channels). This node accepts both continuous signals and sparse events as its input.

More Info...

Version 1.2.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

  • half_bandwidth
    Time-halfbandwidth product parameter of the multi-taper method. Larger values yield smoother spectra, and typical values for segmented data are in the 2-5 range (going to as high as 20). By default, this is used to determine the number of tapers that should be averaged (as 2*time_halfbandwith-1).

    • verbose name: Time-Halfbandwith Product
    • default value: 2.5
    • port type: FloatPort
    • value type: float (can be None)

  • num_tapers
    Override number of tapers. If the value is not given, then the maximum number of tapers according to the time-halfbandwith parameter is used. If given, more tapers yield smoother spectra.

    • verbose name: Override Number Of Tapers
    • default value: None
    • port type: IntPort
    • value type: int (can be None)

  • nfft
    FFT Size. Allows for oversampling in the frequency domain for a smoother appearance.

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

  • onesided
    Return one-sided spectrum if the input data is real-valued. For complex data, the spectrum is always two-sided. One may set this to false in order to get data that is formatted the same way as for the complex case, but the extra values are redundant in this case.

    • verbose name: Onesided Spectrum For Real-Valued Data
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • average_over_time_window
    If set the computed spectrum is finally averaged over the time windows (an Instance axis introduced by the Shifted Windows node).

    • verbose name: Average Over Time Window
    • 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)

PowerSpectra

A meta-node that segments and calculates the Power Spectra on segmented data.

Collapses the time axis. Converts to decibels.

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

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

  • subwindow_length
    Sub-window length for averaging. This node will extract successive windows from the given data of this length, which are overlapped according to the overlap samples parameter. Longer windows will give a higher-resolution (but potentially less smooth and more noisy) spectrum.

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

  • subwindow_overlap
    Overlap between successive sub-windows, expressed as a fraction of the sub-window length. This determines by how much successive sub-windows are overlapped. Using a higher value will yield finer stepping in time without a change in temporal or frequency detail (since the time axis will be correspondingly more smooth to counter the finer stepping). If not given, defaults to half of the sub-window length. If the sub-window length is expressed in samples, this value can also be expressed in samples.

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

  • fft_size
    Length of the FFT used. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency or temporal detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the sub-window length.

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

  • onesided
    Return one-sided spectrum. If disabled, a two-sided (meaning: symmetric about the middle) spectrum will be computed, which is redundant for real-valued data, but required for complex-valued data (for complex data, the spectrum is always two-sided.

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

  • unit
    Unit in which the sub-window length is expressed. By default this is seconds, but samples can also be used if necessary.

    • verbose name: Unit Used For Sub-Window Length.
    • default value: seconds
    • port type: EnumPort
    • value type: str (can be None)

  • frequency_normalization_alpha
    The exponent of 1/f^alpha used in the correction. Set to None to determine the value automatically.

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

  • channel_range
    Comma separated list of channels/ROIs to be retained. Leave blank or set to 'all' to include all previously selected channels/ROIs.

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

  • frequency_range
    Frequency range for which to plot the spectra.

    • verbose name: Frequency Range
    • default value: 1...50
    • port type: Port
    • value type: object (can be None)

  • output
    Compute the mean of all trials or output the per trials data.

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

SpectralSelection

Apply a band-pass filter to a given segmented signal.

This node is specifically made for filtering data after it has already been segmented (based on the Fast Fourier Transform or FFT). Note: even though this node is in the spectral category, it does neither accept nor produce data in the frequency domain (i.e., with a frequency axis), but instead the input and output are typical segmented time series. When the task is to filter segmented data, this node is preferred over an IIR or FIR filter -- however, if one of these band-pass filters can already be applied on continuous data (i.e. before segmentation), then doing so will usually yield better results, because it is done before any sharp discontinuities at the edges of the segments are introduced. The only exception to this rule of thumb is if the goal is to apply a band-pass filter with no phase lag/distortion (e.g., to retain the exact shape and shift of an event-related potential in EEG): then this node is the only available choice in NeuroPype. Note also that filtering segmented data will give much milder edge artifacts if the data is zero-mean ( that is, has been detrended, or has already been high-pass filtered before segmentation), and/or if the signal has had a window function applied to it (this can be done by putting the Window Function node before this node). Note that the FFT Band-Pass filter node is not a very good choice on non-segmented, i.e., continuous data (neither offline nor especially online) -- in these cases, FIR or IIR filters are strongly preferred. This node will not change the shape or axes of the data. At a technical level, the node transforms the data into the frequency domain, sets spectral components outside the desired range to zero, and then back-transforms the result into the time domain. Note: if low frequencies are being removed with this filter, this will result in the signal becoming more periodic, i.e., the waveform will appear to wrap around the edges (these are the aforementioned edge artifacts).

More Info...

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

  • frequencies
    Lower and upper edges of the retained frequency band. For example, [8, 12] retains the band between 8 and 12 Hz, and discards everything else.

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

  • blocksize
    Block size to conserve memory. This is the number of instances/trials (if present) or otherwise channels (if present) that should be processed simultaneously. Using a larger number will allow you to process all your data at once, or in a few steps, which minimizes the per-step compute time overhead, but will require more memory. The default is a fair choice for memory-constrained machines. Aside from memory use, the result is unaffected by this setting.

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

  • fft_size
    Length of the FFT used, in samples. If set to None (the default), the FFT size matches the size of the data, which can be an odd size that may not be particularly efficient. If set to -1, the next higher power of two is used that can accommodate the data; this can be faster, but results will be slightly different.

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

  • legacy
    Use the legacy implementation. This should give almost identical results but is included for compatibility reasons.

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

  • stopband_gain
    Gain in the stop band, as a value between 0 and 1. This can be used to not entirely suppress content in the off-band, but instead attenuate it to a certain amount.

    • verbose name: Stopband Gain
    • default value: 0
    • 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)

Spectrogram

Calculate a spectrogram (periodogram) of the given data (that is, a time/frequency representation).

The node will compute a new data array with a typically coarser time axis than the original data, and an additional frequency axis, thus yielding an estimate how the spectral content in the data changes over time. This is done using the Short-Time Fourier Transform (STFT). This node estimates the spectrum over multiple successive (and usually overlapping) sub-windows. The parameters of this node allow to trade off time vs. frequency detail, as well as increase the step size along time and/or frequency. See also the tooltips of these parameters to see how they affect the result. This node operates on short segments of data, so in the case of streaming data the data must first be segmented into windows, i.e., using the Segmentation or Moving Window node. This node will then compute a time/frequency representation for each segment it receives. It will not work on continuous streaming data, since each packet received would contain too few samples to perform a spectrogram on. This node can also be used on "offline" (non-streaming) data, in which case the spectrogram will be computed over the entire dataset at once.

More Info...

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

  • segment_samples
    Length of the sub-windows for spectral estimation. This node will extract successive windows from the given data of this length, which are overlapped according to the overlap samples parameter. Longer windows will give a higher-resolution spectrum, but at the same time the result will increase the smoothness (i.e., blurriness) along the time axis. The tradeoff between time resolution and frequency resolution that can be adjusted via this parameter is fundamental. If unspecified, defaults to 0.5 seconds of data (or equivalent in samples) based on the sampling rate. If specified in seconds, the specified value will be converted to samples at runtime based on the sampling rate of the incoming data.

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

  • unit
    Unit in which the sub-window length is expressed.

    • verbose name: Unit Used For Sub-Window Length.
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • overlap_samples
    Overlap between successive sub-windows, expressed as a fraction of the sub-window length. This determines by how much successive sub-windows are overlapped. Using a higher value will yield finer stepping in time without a change in temporal or frequency detail (since the time axis will be correspondingly more smooth to counter the finer stepping). If unspecified, defaults to half of the sub-window length. If the sub-window length is expressed in samples, this value can also be expressed in samples.

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

  • fft_size
    Length of the FFT used, in samples. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency or temporal detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the sub-window length.

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

  • window
    Type of window function to apply to sub-windows. Different functions have different spectral and temporal localization characteristics. One of the simplest well-behaved windows is the Hann window (the default).

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

  • detrend
    Sub-window detrending method. In the Welch method, linear trends or constant offsets can be removed from each window prior to spectral estimation.

    • verbose name: Sub-Window Detrending
    • default value: off
    • port type: EnumPort
    • value type: str (can be None)

  • onesided
    Return one-sided spectrum. If disabled, a two-sided (meaning: symmetric about the middle) spectrum will be computed, which is redundant for real-valued data, but required for complex-valued data (for complex data, the spectrum is always two-sided.

    • verbose name: Onesided Spectrum For Real-Valued Data
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • scaling
    Scaling of the spectrum. In density mode, the result is divided by the frequency; this yields the power-spectral density, and is the default. However, this will incur a falloff towards higher frequencies which may be addressed separately using the frequency normalization node.

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

  • use_caching
    Enable caching. This will significantly speed up re-use of the same data. For offline data only.

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

WelchSpectrum

Calculate the power spectrum of the given data using the Welch method.

This is a reasonably high-quality spectral estimator, which averages the spectrum over multiple overlapping time windows. The resolution of the spectrum can be increased by using longer (and therefore fewer) windows, but this comes with a cost of increased noise. There is also an alternative drop-in replacement for this node, called MultitaperSpectrum that uses a different method, which can yield higher-quality spectra at a somewhat higher compute load. The most common use case for either node is to apply it to segmented data (i.e., following the Segmentation node), which will compute the spectrum for each segment of the data. Another use case is to apply it in an offline fashion on an entire recording (which yields the average power spectrum of that recording). It is not useful to apply this node on streaming data without any buffering or segmentation, because this would try to estimate the spectrum on the very short chunks of data without any averaging across chunks, yielding bad data. Therefore for streaming data, this node should be preceded by the MovingWindow node (or Segmentation). At a technical level, this node will replace the time axis of the data by a frequency axis (since time is averaged out), but it will add a dummy time axis with one entry that is annotated with the average time value of the former time axis (this is so that that information is not lost). If you need to remove this axis, e.g., because some subsequent node cannot handle multiple axes in the data, you can use the Fold Into Axis node to fold it into some other axis (usually that would be space, i.e., channels).

More Info...

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

  • axis
    Axis across which to calculate the spectrum. This axis will be removed from the data and replaced by a frequency axis.

    • verbose name: Calculate Spectrum Along Axis
    • default value: time
    • port type: ComboPort
    • value type: str (can be None)

  • segment_samples
    Sub-window length for averaging. This node will extract successive windows from the given data of this length, which are overlapped according to the overlap samples parameter. Longer windows will give a higher-resolution (but potentially less smooth and more noisy) spectrum. Can be in seconds or samples (see unit parameter). If omitted, defaults to the length of the window.

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

  • unit
    Unit in which the sub-window length is expressed.

    • verbose name: Unit Used For Sub-Window Length.
    • default value: samples
    • port type: EnumPort
    • value type: str (can be None)

  • overlap_samples
    Overlap between successive sub-windows, expressed as a fraction of the sub-window length (for values<1), or in number of samples (for values>=1). This determines by how much successive sub-windows are overlapped. Using a higher value will yield finer stepping in time without a change in temporal or frequency detail (since the time axis will be correspondingly more smooth to counter the finer stepping). Note that the unit parameter does not apply to the overlap, which is always either a fraction or in samples. If not given, defaults to half of the sub-window length.

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

  • fft_size
    Length of the FFT used, in samples. Using a higher number will yield a finer stepping along the frequency axis, without a change in frequency or temporal detail (the frequency axis will be correspondingly more smooth to counter the finer stepping). If not given, it defaults to the sub-window length.

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

  • window
    Type of window function to apply to sub-windows. Different functions have different spectral and temporal localization characteristics. One of the simplest well-behaved smooth windows is the Hann window (the default).

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

  • detrend
    Sub-window detrending method. In the Welch method, linear trends or constant offsets can be removed from each window prior to spectral estimation.

    • verbose name: Sub-Window Detrending
    • default value: constant
    • port type: EnumPort
    • value type: str (can be None)

  • onesided
    Return one-sided spectrum. If disabled, a two-sided (meaning: symmetric about the middle) spectrum will be computed, which is redundant for real-valued data, but required for complex-valued data (for complex data, the spectrum is always two-sided.

    • verbose name: Onesided Spectrum For Real-Valued Data
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • scaling
    Scaling of the spectrum. The 'density' mode yields the power spectral density (PSD), and the output has a unit of V^2/Hz (if the input signal is in V). In 'spectrum' mode, the result is the (less frequently used) power spectrum, whose unit is V^2, which does not account for the sampling frequency of the data.

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

  • average_over_time_window
    If set the computed spectrum is finally averaged over the time windows (an Instance axis introduced by the Shifted Windows node).

    • verbose name: Average Over Time Window
    • 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)