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:	xneo.AnalogSignal or pq.Quantity or np.ndarray First time series data of the pair between which coherence is computed. yneo.AnalogSignal or pq.Quantity or np.ndarray Second time series data of the pair between which coherence is computed. The shapes and the sampling frequencies of x and y must be identical. When x and y are not neo.AnalogSignal, sampling frequency should be specified through the keyword argument fs. Otherwise, the default value is used (fs = 1.0). num_segint, 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: 8. len_segint, optional Length of segments. This parameter is ignored if freq_res is given. If None, it is determined from other parameters. Default: None. freq_respq.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. If None, it is determined from other parameters. Default: None. overlapfloat, optional Overlap between segments represented as a float number between 0 (no overlap) and 1 (complete overlap). Default: 0.5 (half-overlapped). fspq.Quantity or float, optional Specifies the sampling frequency of the input time series. When the input time series are given as neo.AnalogSignal, the sampling frequency is taken from their attribute and this parameter is ignored. Default: 1.0. windowstr or tuple or np.ndarray, optional Desired window to use. See Notes [1]. Default: ‘hanning’. nfftint, optional Length of the FFT used. See Notes [1]. Default: None. detrendstr or function or False, optional Specifies how to detrend each segment. See Notes [1]. Default: ‘constant’. scaling{‘density’, ‘spectrum’}, optional If ‘density’, computes the power spectral density where Pxx has units of V2/Hz. If ‘spectrum’, computes the power spectrum where Pxx has units of V2, if signal is measured in V and fs is measured in Hz. See Notes [1]. Default: ‘density’. axisint, optional Axis along which the periodogram is computed. See Notes [1]. Default: last axis (-1).
Returns:	freqspq.Quantity or np.ndarray Frequencies associated with the estimates of coherency and phase lag. freqs is always a vector irrespective of the shape of the input data. If x and y are neo.AnalogSignal or pq.Quantity, a pq.Quantity array is returned. Otherwise, a np.ndarray containing frequency in Hz is returned. coherencynp.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 the frequency is indexed depending on the type of the input. If the input is neo.AnalogSignal, the first axis indexes frequency. Otherwise, frequency is indexed by the last axis. phase_lagpq.Quantity or np.ndarray Estimate of phase lag in radian between the input time series. For each frequency, phase lag takes a value between $-\pi$ and $\pi$ , with positive values meaning phase precession of x ahead of y, and vice versa. If x and y are neo.AnalogSignal or pq.Quantity, a pq.Quantity array is returned. Otherwise, a np.ndarray containing phase lag in radian is returned. The axis for frequency index is determined in the same way as for coherency.
Raises:	ValueError If overlap is not in the interval [0, 1). If freq_res is not positive. If freq_res is too high for the given data size. If freq_res is None and len_seg is not a positive number. If freq_res is None and len_seg is greater than the length of data on axis. If both freq_res and len_seg are None and num_seg is not a positive number. If both freq_res and len_seg are None and num_seg is greater than the length of data on axis.

See also

spectral._welch

Notes

The parameters window, nfft, detrend, scaling, and axis are directly passed to the helper function _welch. See the respective descriptions in the docstring of _welch for usage.
When only num_seg is given, parameter nperseg for _welch function is determined according to the expression

x.shape[axis] / (num_seg - overlap * (num_seg - 1))

converted to integer.

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 neo.AnalogSignal using Welch’s method.

The PSD is obtained through the following steps:

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 the parameters num_seg, len_seg or freq_res. By default, the data is cut into 8 segments;
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 (see Notes [2]);
Compute the periodogram of each segment;
Average the obtained periodograms to yield PSD estimate.

Parameters:	signalneo.AnalogSignal or pq.Quantity or np.ndarray Time series data, of which PSD is estimated. When signal is pq.Quantity or np.ndarray, sampling frequency should be given through the keyword argument fs. Otherwise, the default value is used (fs = 1.0). num_segint, 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: 8. len_segint, optional Length of segments. This parameter is ignored if freq_res is given. If None, it will be determined from other parameters. Default: None. freq_respq.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. If None, it will be determined from other parameters. Default: None. overlapfloat, optional Overlap between segments represented as a float number between 0 (no overlap) and 1 (complete overlap). Default: 0.5 (half-overlapped). fspq.Quantity or float, optional Specifies the sampling frequency of the input time series. When the input is given as a neo.AnalogSignal, the sampling frequency is taken from its attribute and this parameter is ignored. Default: 1.0. windowstr or tuple or np.ndarray, optional Desired window to use. See Notes [2]. Default: ‘hanning’. nfftint, optional Length of the FFT used. See Notes [2]. Default: None. detrendstr or function or False, optional Specifies how to detrend each segment. See Notes [2]. Default: ‘constant’. return_onesidedbool, optional If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. See Notes [2]. Default: True. scaling{‘density’, ‘spectrum’}, optional If ‘density’, computes the power spectral density where Pxx has units of V2/Hz. If ‘spectrum’, computes the power spectrum where Pxx has units of V2, if signal is measured in V and fs is measured in Hz. See Notes [2]. Default: ‘density’. axisint, optional Axis along which the periodogram is computed. See Notes [2]. Default: last axis (-1).
Returns:	freqspq.Quantity or np.ndarray Frequencies associated with the power estimates in psd. freqs is always a vector irrespective of the shape of the input data in signal. If signal is neo.AnalogSignal or pq.Quantity, a pq.Quantity array is returned. Otherwise, a np.ndarray containing frequency in Hz is returned. psdpq.Quantity or np.ndarray PSD estimates of the time series in signal. If signal is neo.AnalogSignal, a pq.Quantity array is returned. Otherwise, the return is a np.ndarray.
Raises:	ValueError If overlap is not in the interval [0, 1). If freq_res is not positive. If freq_res is too high for the given data size. If freq_res is None and len_seg is not a positive number. If freq_res is None and len_seg is greater than the length of data on axis. If both freq_res and len_seg are None and num_seg is not a positive number. If both freq_res and len_seg are None and num_seg is greater than the length of data on axis.

Spectral analysis¶

Elephant

Navigation

Related Topics