Spectral analysis

Identification of spectral properties in analog signals (e.g., the power spectrum).

elephant.spectral.welch_cohere(x, y, num_seg=8, len_seg=None, freq_res=None, overlap=0.5, fs=1.0, window='hanning', nfft=None, detrend='constant', scaling='density', axis=-1)[source]

Estimates coherence between a given pair of analog signals. The estimation is performed with Welch’s method: the given pair of data are cut into short segments, cross-spectra are calculated for each pair of segments, and the cross-spectra are averaged and normalized by respective auto_spectra. By default the data are cut into 8 segments with 50% overlap between neighboring segments. These numbers can be changed through respective parameters.

Parameters:
x, y: Neo AnalogSignal or Quantity array or Numpy ndarray

A pair of time series data, between which coherence is computed. The shapes and the sampling frequencies of x and y must be identical. When x and y are not of AnalogSignal, sampling frequency should be specified through the keyword argument fs, otherwise the default value (fs=1.0) is used.

num_seg: int, optional

Number of segments. The length of segments is adjusted so that overlapping segments cover the entire stretch of the given data. This parameter is ignored if len_seg or freq_res is given. Default is 8.

len_seg: int, optional

Length of segments. This parameter is ignored if freq_res is given. Default is None (determined from other parameters).

freq_res: Quantity or float, optional

Desired frequency resolution of the obtained coherence estimate in terms of the interval between adjacent frequency bins. When given as a float, it is taken as frequency in Hz. Default is None (determined from other parameters).

overlap: float, optional

Overlap between segments represented as a float number between 0 (no overlap) and 1 (complete overlap). Default is 0.5 (half-overlapped).

fs: Quantity array or float, optional

Specifies the sampling frequency of the input time series. When the input time series are given as AnalogSignal, the sampling frequency is taken from their attribute and this parameter is ignored. Default is 1.0.

window, nfft, detrend, scaling, axis: optional

These arguments are directly passed on to a helper function elephant.spectral._welch(). See the respective descriptions in the docstring of elephant.spectral._welch() for usage.

Returns:
freqs: Quantity array or Numpy ndarray

Frequencies associated with the estimates of coherency and phase lag. freqs is always a 1-dimensional array irrespective of the shape of the input data. Quantity array is returned if x and y are of AnalogSignal or Quantity array. Otherwise Numpy ndarray containing frequency in Hz is returned.

coherency: Numpy ndarray

Estimate of coherency between the input time series. For each frequency coherency takes a value between 0 and 1, with 0 or 1 representing no or perfect coherence, respectively. When the input arrays x and y are multi-dimensional, coherency is of the same shape as the inputs and frequency is indexed along either the first or the last axis depending on the type of the input: when the input is AnalogSignal, the first axis indexes frequency, otherwise the last axis does.

phase_lag: Quantity array or Numpy ndarray

Estimate of phase lag in radian between the input time series. For each frequency phase lag takes a value between -PI and PI, positive values meaning phase precession of x ahead of y and vice versa. Quantity array is returned if x and y are of AnalogSignal or Quantity array. Otherwise Numpy ndarray containing phase lag in radian is returned. The axis for frequency index is determined in the same way as for coherency.

elephant.spectral.welch_psd(signal, num_seg=8, len_seg=None, freq_res=None, overlap=0.5, fs=1.0, window='hanning', nfft=None, detrend='constant', return_onesided=True, scaling='density', axis=-1)[source]

Estimates power spectrum density (PSD) of a given AnalogSignal using Welch’s method, which works in the following steps:

  1. cut the given data into several overlapping segments. The degree of
    overlap can be specified by parameter overlap (default is 0.5, i.e. segments are overlapped by the half of their length). The number and the length of the segments are determined according to parameter num_seg, len_seg or freq_res. By default, the data is cut into 8 segments.
  2. apply a window function to each segment. Hanning window is used by
    default. This can be changed by giving a window function or an array as parameter window (for details, see the docstring of scipy.signal.welch())
  3. compute the periodogram of each segment
  4. average the obtained periodograms to yield PSD estimate

These steps are implemented in scipy.signal, and this function is a wrapper which provides a proper set of parameters to scipy.signal.welch(). Some parameters for scipy.signal.welch(), such as nfft, detrend, window, return_onesided and scaling, also works for this function.

Parameters:
signal: Neo AnalogSignal or Quantity array or Numpy ndarray

Time series data, of which PSD is estimated. When a Quantity array or Numpy ndarray is given, sampling frequency should be given through the keyword argument fs, otherwise the default value (fs=1.0) is used.

num_seg: int, optional

Number of segments. The length of segments is adjusted so that overlapping segments cover the entire stretch of the given data. This parameter is ignored if len_seg or freq_res is given. Default is 8.

len_seg: int, optional

Length of segments. This parameter is ignored if freq_res is given. Default is None (determined from other parameters).

freq_res: Quantity or float, optional

Desired frequency resolution of the obtained PSD estimate in terms of the interval between adjacent frequency bins. When given as a float, it is taken as frequency in Hz. Default is None (determined from other parameters).

overlap: float, optional

Overlap between segments represented as a float number between 0 (no overlap) and 1 (complete overlap). Default is 0.5 (half-overlapped).

fs: Quantity array or float, optional

Specifies the sampling frequency of the input time series. When the input is given as an AnalogSignal, the sampling frequency is taken from its attribute and this parameter is ignored. Default is 1.0.

window, nfft, detrend, return_onesided, scaling, axis: optional

These arguments are directly passed on to scipy.signal.welch(). See the respective descriptions in the docstring of scipy.signal.welch() for usage.

Returns:
freqs: Quantity array or Numpy ndarray

Frequencies associated with the power estimates in psd. freqs is always a 1-dimensional array irrespective of the shape of the input data. Quantity array is returned if signal is AnalogSignal or Quantity array. Otherwise Numpy ndarray containing frequency in Hz is returned.

psd: Quantity array or Numpy ndarray

PSD estimates of the time series in signal. Quantity array is returned if data is AnalogSignal or Quantity array. Otherwise Numpy ndarray is returned.