Frequency-domain analysis tools

Functions:

ARparameters(x[, P])

Estimation of the parameters of an Auto-regressive process

ARpsd(a[, worN, fs, sigma])

Power spectral density from AR parameters

countSumPeaks(x[, fs, nperseg, noverlap, ...])

"

effectiveFrequency(x, T)

Calculate the effective frequency of a phase serie.

findPeaks(Pxx[, tolPercentile, tolF, Nmax, ...])

Find the peaks in the spectrum Pxx that accomplish: 1.

findPeaksScipy(Pxx[, tolPercentile, tolF, ...])

Find the peaks in the spectrum Pxx that accomplish: 1.

peak_freqs(x[, fs, nperseg, noverlap, ...])

The peak of the Welch's periodogram.

peaksSpectrum(f, Pxx[, Npeaks, deltaf, useScipy])

Find Npeaks in the spectrum Npeaks

spectralComplexity(Pxx[, communities])

Calculates the spectral complexity from the spectrum Pxx.

spectralEntropy(Pxx[, independet_row])

Calculates the spectral entropy from the spectrum Pxx.

spectralEntropy2D(Cxx)

Calculates the spectral/correlation entropy of a coherence/correlation matrix

spectrogram(X[, fs, nperseg, noverlap])

Welch spectrogram usign the welch periodograms

waveletMorlet(x[, fs, f_start, f_end, ...])

Wavelet scalogram usign the Morlet mother wavelet
analysis.frequency.ARparameters(x, P=2)

Estimation of the parameters of an Auto-regressive process

Parameters

  • x (1D float array) – time serie.

  • P (int, optional) – Number of AR parameters (number of poles, then it is strictly related to peaks). The default is 2.

Returns

a – Parameters of the AR process. These are the coeficients from the denominator of a discrete time impulse response 1/[1 a1 a2 a3]

Return type

float array

analysis.frequency.ARpsd(a, worN=1000, fs=100, sigma=0.001)

Power spectral density from AR parameters

Parameters

  • a (1D float array) – AR parameters [a1, a2, a3, …, ap].

  • worN (int, optional) – Number of frequency bins. The default is 1000.

  • fs (int, optional) – sampling frequency, used only to scale. The default is 100.

  • sigma (float, optional) – standard deviation of the noise in the AR process. The default is 1e-3.

Returns

  • psd (float 1D array)

  • Power spectral density of large worN

analysis.frequency.countSumPeaks(x, fs=1000, nperseg=4096, noverlap=2048, applySin=True, minProminence=0.5, maxProminence=1000, distance=0.5)

” The peaks of the sum of the all nodes Welch’s periodograms.

Parameters

  • x (1D float) – data NxT.

  • fs (int) – sampling frequency (samples/second)

  • nperseg (int, optional) – time window in number of samples. The default is 4096 samples.

  • noverlap (int, optional) – overlap time in number of samples. The default is 2048 samples.

  • applySin (boolean) – Apply or not the sin() function before calculate the spectrum. The default is True.

  • minProminence (float) – minimum value of ratio between the peak and its neighborhood

  • maxProminence (float) – maximum value of ratio between the peak and its neighborhood

  • distance (float) – minimum value in Hz between peaks

Returns

  • f (1D float array) – list of frequencies.

  • sumPxx (1D float array) – Sum of the periodograms.

  • npeaks (int) – Number of found peaks

  • peaks_arrayt (2D float array) – frequencies and amplitudes of the found peaks

analysis.frequency.effectiveFrequency(x, T)

Calculate the effective frequency of a phase serie. It is defined as (final_phase - initial_phase)/(2(pi)T)

Parameters

  • x (2D array) – Nodes x time samples.

  • T (float) – Total time (seconds).

Returns

Effective frequency (Hz).

Return type

1D float array

analysis.frequency.findPeaks(Pxx, tolPercentile=1, tolF=10, Nmax=10, power_quotient=2)

Find the peaks in the spectrum Pxx that accomplish: 1. Derivative value less that tolPercentile**(diff(**Pxx)) 2. At least separated tolF bins. 3. Amplitude value higher than max(Pxx)/power_quotient

Parameters

  • Pxx (float 1D array) – Spectrum.

  • tolPercentile (int, optional) – Percentil of low diff values where search for peaks. The default is 1%.

  • tolF (int, optional) – Number of frequency bins that should be at least between peaks. The default is 10 bins.

  • Nmax (int, optional) – Maximum number of frequency peaks to find. The default is 10.

  • power_quotient (float, optional) – Inverse scaling of the maximum power that a peak must achieve to be considered as a ‘good’ one. The default is 2.

Returns

peak_indexes – Array of position indexes of the peaks in Pxx.

Return type

int 1D array

analysis.frequency.findPeaksScipy(Pxx, tolPercentile=1, tolF=10, power_quotient=0.2)

Find the peaks in the spectrum Pxx that accomplish: 1. Prominence of peaks larger than the tolPercentile of the diff(Pxx). 2. At least separated tolF bins. 3. Amplitude value higher than power_quotient

Parameters

  • Pxx (float 1D array) – Spectrum.

  • tolPercentile (int, optional) – Prominence of the peaks. The default is 1.

  • tolF (int, optional) – Number of frequency bins that should be at least between peaks. The default is 10 bins.

  • power_quotient (float, optional) – Threshold of power between neighborhood peaks. The default is 0.2.

Returns

peak_indexes – Array of position indexes of the peaks in Pxx.

Return type

int 1D array

analysis.frequency.peak_freqs(x, fs=1000, nperseg=4096, noverlap=2048, applySin=True, includeDC=False)

The peak of the Welch’s periodogram.

Parameters

  • x (1D float) – data NxT.

  • fs (int) – sampling frequency (samples/second)

  • nperseg (int, optional) – time window in number of samples. The default is 4096 samples.

  • noverlap (int, optional) – overlap time in number of samples. The default is 2048 samples.

  • applySin (boolean) – Apply or not the sin() function before calculate the spectrum. The default is True.

  • includeDC (boolean, default=False) – include or not the DC component to find the peak frequency

Returns

  • f (1D float array) – list of frequencies.

  • Pxx (2D float array) – Spectrograms: Nodes x frequency

  • pfreqs (1D float array) – frequency peak for each node.

analysis.frequency.peaksSpectrum(f, Pxx, Npeaks=10, deltaf=5, useScipy=True)

Find Npeaks in the spectrum Npeaks

Parameters

  • f (1D float array) – frequencies list (Hz).

  • Pxx (1D or 2D float array) – N x Spectrum.

  • Npeaks (int, optional) – Number of peaks. Default is 10.

  • deltaf (int, optional) – Frequency range for tolerance between peaks. The default is 5 Hz.

  • useScipy (boolean, optional) – Set to use scipy method, or use the own peaks-search method

Returns

  • pindex (1D int array) – Indexes of the peak frequencies in the frequencies list, f.

  • pfreqs (1D float array) – Frequency peaks.

analysis.frequency.spectralComplexity(Pxx, communities=None)

Calculates the spectral complexity from the spectrum Pxx. It uses the spectral entropy as entropies to calculate the information complexity Pxx could also be an array of spectrums.

Parameters

  • Pxx (float 1D (2D) array) – Spectrum or spectrums’ array N x frequency bins

  • communities (dict) – Dictionary with the nodes grouped by communities.

Returns

C – Spectral complexity

Return type

float (1D array)

analysis.frequency.spectralEntropy(Pxx, independet_row=True)

Calculates the spectral entropy from the spectrum Pxx. Pxx could also be an array of spectrums.

Parameters

  • Pxx (float 1D (2D) array) – Spectrum or spectrums’ array N x frequency bins

  • independent_row (boolean) – Normalize independently the spectrum for each row/node

Returns

H – Spectral entropy

Return type

float (1D array)

analysis.frequency.spectralEntropy2D(Cxx)

Calculates the spectral/correlation entropy of a coherence/correlation matrix

Parameters

Cxx (float 2D array) – Coherence or correlation matrix frequency bins x frequency bins

Returns

H – Spectral/correlation entropy

Return type

float

analysis.frequency.spectrogram(X, fs=1000, nperseg=4096, noverlap=2048)

Welch spectrogram usign the welch periodograms

Parameters

  • X (1D or 2D float array) – timeseries data. If 2D: N x T

  • fs (int) – sampling frequency

  • nperseg (int, optional) – time window in number of samples. The default is 4096.

  • noverlap (int, optional) – overlap time in number of samples. The default is 2048.

Returns

  • t (1D float array) – center of the time window.

  • f (1D float array) – frequencies list.

  • Sxx (2D or 3D float array: N x len(f) x len(t)) – Spectrogram with spectral power density units (x^2/Hz).

analysis.frequency.waveletMorlet(x, fs=1000, f_start=0.5, f_end=200, numberFreq=500, omega0=15, correctF=False)

Wavelet scalogram usign the Morlet mother wavelet

Parameters

  • x (1D float array) – timeserie data.

  • fs (fs, optional) – sampling frequency. The default is 1000 Hz.

  • f_start (float, optional) – Starting frequency of analysis (larger wavelet scale). This is the most affected scale by the cone of influence. The default is 0.5 Hz.

  • f_end (float, optional) – End frequency of analyisis. The default is 200 Hz.

  • numberFreq (int, optional) – Number of scales (frequency bins). The default is 500.

  • omega0 (float, optional) – Central wavelet frequency. Modifies the bandwidth of the scalogram. The default is 15 Hz.

  • correctF (boolean, optional) – If True, the result is normalized by 1/scale(frequency). Necessary to identify peaks if the spectrum has 1/f trend. The default is False.

Returns

  • freqs (1D float array) – Equivalent frequencies (Hz)

  • scales (1D float array) – Wavelet scales

  • coefs (2D float array: freqs x len(x)) – Scalogram coefficients (a. u.) Wavelet transform is calculated for each time point.