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

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

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

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

MultitaperSpectrum

Calculate the power spectrum 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 Power Spectrum (Welch), 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. There is a node that was specifically made for this task, called Moving window Multitaper spectrum, 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). 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). This node accepts both continuous signals and sparse events as its input.

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
  • 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 final spectrum is averaged over time-window. The time-window axis is an axis introduced by shifted windows node. In case of calculating the spectrum of a time series on offline mode we do not want to add the result over the time-window axis. However, if we are calculating the spectrum of an epoched data and we average over time-window specially if we want to later plot or further analyze the data

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

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

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

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

    • verbose name: Sub-Window Length
    • default value: None
    • port type: FloatPort
    • value type: float (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 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: 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)
  • 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: object (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: object (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: object (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: object (can be None)
  • use_caching
    Enable caching. This will significantly speed up re-use of the same data.

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

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 Power Spectrum (Multitaper), 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. There is a node that was specifically made for this task, called Moving window Welch spectrum, 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). 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.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
  • 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: EnumPort
    • value type: object (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: object (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 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: 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: object (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: object (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 V2/Hz (if the input signal is in V). In 'spectrum' mode, the result is the (less frequently used) power spectrum, whose unit is V2, which does not account for the sampling frequency of the data.

    • verbose name: Spectral Scaling Mode
    • default value: density
    • port type: EnumPort
    • value type: object (can be None)
  • average_over_time_window
    If set the final spectrum is averaged over time-window. The time-window axis is an axis introduced by shifted windows node. In case of calculating the spectrum of a time series on offline mode we do not want to add the result over the time-window axis. However, if we are calculating the spectrum of an epoched data and we average over time-window specially if we want to later plot or further analyze the data

    • verbose name: Average Over Time Window
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)