Skip to content

← spectral package

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. A common use case for either node is to apply it to segmented (epoched) data, following the Segmentation node, which will compute the spectrum for each segment of the data. Another use case is to apply it to an entire recording, which yields the average power spectrum of that recording. It is not useful to apply this node on streaming raw EEG 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 inaccurate results. When using with streaming EEG data, this node should be preceded by MovingWindow, Segmentation or similar node that performs buffering. This node replaces the time axis of the data by a frequency axis (since time is averaged out). It adds a dummy time axis with a single element that is annotated with the average time value of the former time axis (so that information is not lost). So if the incoming data is space x time (the usual case), the outgoing data will be space x frequency x time. That time axis can be removed using StripSingletonAxis, SqueezeAxes, or if you want to retain the time value, use FoldIntoAxis to fold it into the elements of another axis (usually the space axis, i.e., channels). More Info... Version 1.3.2

Ports/Properties

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)

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)