Harmonic spectrum#

compute_phase_matrix(signal, precision_hz, fs, noverlap, smoothness)[source]#

Compute the phase matrix of a signal using the Short-Time Fourier Transform (STFT).

Parameters

  • signal (ndarray) – Input signal.

  • precision_hz (float) – Frequency precision.

  • fs (int) – The sampling frequency of the signal.

  • noverlap (int) – The number of points of overlap between blocks.

  • smoothness (float) – A parameter for smoothing the signal.

Returns

ndarray – The phase matrix of the signal.

compute_dyad_similarities_and_phase_coupling_matrix(freqs, phase_matrix, metric='harmsim', n_harms=5, delta_lim=150, min_notes=2)[source]#

Compute dyad similarities and the phase coupling matrix of frequencies. The phase coupling metric is the Phase Locking Value.

Parameters

  • freqs (ndarray) – Array of frequencies.

  • phase_matrix (ndarray) – The phase matrix of the signal.

  • metric (str, optional) – The metric to compute dyad similarity. Default is ‘harmsim’.

  • n_harms (int, optional) – The number of harmonics. Default is 5.

  • delta_lim (int, optional) – The delta limit. Default is 150.

  • min_notes (int, optional) – The minimum number of notes. Default is 2.

Returns

tuple of ndarrays – The harmonicity and the phase coupling matrix.

compute_harmonicity_values_and_phase_coupling_values(freqs, dyad_similarities, phase_coupling_matrix, psd_clean, psd_mode=None, harm_phase_norm=True)[source]#

Compute harmonicity values and phase coupling values for each frequency.

Parameters

  • freqs (ndarray) – Array of frequencies.

  • dyad_similarities (ndarray) – Dyad similarities matrix.

  • phase_coupling_matrix (ndarray) – The phase coupling matrix.

  • psd_clean (ndarray) – The cleaned Power Spectral Density (PSD).

  • phase_matrix (ndarray) – The phase matrix of the signal.

  • harm_phase_norm (bool, default=True) – If True, normalize the harmonicity and phase coupling values by dividing by the total power.

Returns

tuple of ndarrays – The harmonicity values and the phase coupling values.

compute_resonance_values(harmonicity_values, phase_coupling_values)[source]#

Compute resonance values from harmonicity and phase coupling values.

Parameters

  • harmonicity_values (ndarray) – Harmonicity values for each frequency.

  • phase_coupling_values (ndarray) – Phase coupling values for each frequency.

Returns

ndarray – Resonance values for each frequency.

find_spectral_peaks(values, freqs, n_peaks, prominence_threshold=0.5)[source]#

Identify the prominent spectral peaks in a frequency spectrum.

This function uses the peak prominence to select the most notable peaks, and returns their frequencies and indices. Prominence is a measure of how much a peak stands out due to its intrinsic height and its location relative to other peaks.

Parameters

  • values (array_like) – 1-D array of values for the frequency spectrum.

  • freqs (array_like) – 1-D array of frequencies corresponding to the values in ‘values’.

  • n_peaks (int) – The number of top prominent peaks to return.

  • prominence_threshold (float, default=0.5) – The minimum prominence a peak must have to be considered notable. Peaks with a prominence less than this value will be ignored.

Returns

  • peak_frequencies (ndarray) – Frequencies of the ‘n_peaks’ most prominent peaks.

  • prominent_peaks (ndarray) – Indices in ‘values’ and ‘freqs’ of the ‘n_peaks’ most prominent peaks.

See also

scipy.signal.find_peaks, scipy.signal.peak_prominences

Examples

>>> values = np.array([0, 1, 0, 2, 0, 3, 0, 2, 0, 1, 0])
>>> freqs = np.array([10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110])
>>> find_spectral_peaks(values, freqs, n_peaks=3)
(array([60, 40, 80]), array([5, 3, 7]))
harmonic_entropy(freqs, harmonicity_values, phase_coupling_values, resonance_values)[source]#

Compute spectral features and Higuchi Fractal Dimension of Harmonicity, Phase Coupling, and Resonance spectra.

This function calculates several spectral properties: flatness, entropy, spread, and Higuchi Fractal Dimension for three input spectra: Harmonicity, Phase Coupling, and Resonance. Results are returned as a pandas DataFrame.

Parameters

  • freqs (array_like) – 1-D array of frequencies common for all the spectra.

  • harmonicity_values (array_like) – 1-D array of spectral values for the Harmonicity spectrum.

  • phase_coupling_values (array_like) – 1-D array of spectral values for the Phase Coupling spectrum.

  • resonance_values (array_like) – 1-D array of spectral values for the Resonance spectrum.

Returns

harmonic_complexity (DataFrame) – A pandas DataFrame with spectral flatness, entropy, spread, and Higuchi Fractal Dimension for each of the Harmonicity, Phase Coupling, and Resonance spectra.

See also

scipy.stats.mstats.gmean

Used to compute spectral flatness.

scipy.stats.entropy

Used to compute spectral entropy.

scipy.integrate.simps

Used to compute spectral spread.

nolds.hfd

Used to compute Higuchi Fractal Dimension

compute_global_harmonicity(signal, precision_hz, fmin=1, fmax=30, noverlap=1, fs=1000, power_law_remove=False, n_peaks=5, metric='harmsim', n_harms=10, delta_lim=20, min_notes=2, plot=False, smoothness=1, smoothness_harm=1, save=False, savename='', phase_mode=None, harm_phase_norm=True)[source]#

Compute global harmonicity, phase coupling, and resonance characteristics of a signal.

This function computes the Power Spectral Density (PSD) of the signal, applies power law removal if required, calculates the phase matrix, computes dyad similarities and phase couplings, calculates harmonicity, phase coupling and resonance values, identifies spectral peaks, and returns a dataframe summarizing these metrics.

Parameters

  • signal (array_like) – 1-D input signal.

  • precision_hz (float) – Frequency precision for computing spectra.

  • fmin (float, default=1) – Minimum frequency to consider in the spectral analysis.

  • fmax (float, default=30) – Maximum frequency to consider in the spectral analysis.

  • noverlap (int, default=1) – Number of points of overlap between segments for PSD computation.

  • fs (int, default=1000) – Sampling frequency.

  • power_law_remove (bool, default=False) – If True, applies power law removal to the PSD.

  • n_peaks (int, default=5) – Number of spectral peaks to identify.

  • metric (str, default=’harmsim’) – Method for computing dyad similarity. Options are:

    ‘harmsim’ : Harmonic similarity ‘subharm_tension’ : Subharmonic tension

  • n_harms (int, default=10) – Number of harmonics to consider in dyad similarity computation.

  • delta_lim (float, default=0.1) – Limit in ms used when metric is ‘subharm_tension’.

  • min_notes (int, default=2) – Minimum number of notes for dyad similarity computation.

  • plot (bool, default=False) – If True, plots the resulting spectra.

  • smoothness (int, default=1) – Smoothing factor applied to the PSD before computing spectra.

  • smoothness_harm (int, default=1) – Smoothing factor applied to harmonicity values.

  • save (bool, default=False) – If True, saves the plot as a .png file.

  • savename (str, default=’’) – Name for the saved plot file.

  • phase_mode (str, default=None) – Method for weighting phase coupling computation. Options are ‘weighted’ and ‘None’.

  • harm_phase_norm (bool, default=True) – If True, normalize the harmonicity and phase coupling values by dividing by the total power.

Returns

df (DataFrame) – A DataFrame containing computed harmonicity, phase coupling, and resonance values, spectral flatness, entropy, Higushi Fractal Dimension, and spectral spread for each of the three spectra (harmonicity, phase coupling, resonance). Also includes average values and maximum values for these metrics, peak frequencies for each spectrum, and ‘harmsim’ values for peak frequencies.

harmonic_spectrum_plot_trial_corr(df_all, df_all_rnd, label1='Brain Signals', label2='Random Signals')[source]#
harmonic_spectrum_plot_freq_corr(df1, df2, mean_phase_coupling=False, label1='Brain Signals', label2='Random Signals', fmin=2, fmax=30, xlim=None)[source]#
harmonic_spectrum_plot_avg_corr(df1, df2, label1='Brain Signals', label2='Random Signals')[source]#