Harmonic connectivity#

class harmonic_connectivity(sf=None, data=None, peaks_function='EMD', precision=0.1, n_harm=10, harm_function='mult', min_freq=2, max_freq=80, n_peaks=5)[source]#

Bases: object

Class used to compute harmonicity metrics between pairs of sensors.

sf#

Initializing arguments for peak extraction

compute_harm_connectivity(metric='harmsim', delta_lim=20, save=False, savename='_', graph=True, FREQ_BANDS=None)[source]#

Computes the harmonic connectivity matrix between electrodes.

Parameters

  • metric (str, optional) – The metric to use for computing harmonic connectivity. Default is ‘harmsim’. Possible values are:

    • ‘harmsim’: computes the harmonic similarity between each pair of peaks from the two electrodes.

    It calculates the ratio between each pair of peaks and computes the mean harmonic similarity.

    • ‘euler’: computes the Euler’s totient function on the concatenated peaks of the two electrodes.

    It provides a measure of the number of positive integers that are relatively prime to the concatenated peaks.

    • ‘harm_fit’: computes the number of common harmonics between each pair of peaks from the two electrodes.

    It evaluates the harmonic fit between each peak pair and counts the number of common harmonics.

    • ‘subharm_tension’: computes the tension between subharmonics of two electrodes.

    It evaluates the tension between subharmonics of the two electrodes by comparing the subharmonics and their ratios.

    • ‘RRCi’: computes the Rhythmic Ratio Coupling with Imaginary Component (RRCi) metric between each pair of

    peaks from the two electrodes, using a bandwidth of 2 Hz and a max_denom of 16. This metric calculates the imaginary part of the complex phase differences between two filtered signals, accounting for volume conduction. A higher absolute value of the imaginary part indicates stronger phase coupling while being less sensitive to volume conduction.

    • ‘wPLI_crossfreq’: computes the weighted Phase Lag Index (wPLI) for cross-frequency coupling between each pair

    of peaks from the two electrodes. The wPLI measures the phase synchronization between two signals, with a value close to 0 indicating no synchronization and a value close to 1 indicating perfect synchronization.

    • ‘wPLI_multiband’: computes the weighted Phase Lag Index (wPLI) for multiple frequency bands between the two electrodes.

    It calculates wPLI for each frequency band and returns an array of wPLI values for the defined frequency bands.

    • ‘MI’: computes the Mutual Information (MI) between the instantaneous phases of each pair of peaks from the two electrodes.

    MI is a measure of the dependence between the two signals, with a higher value indicating a stronger relationship.

    • ‘MI_spectral’: computes the spectral Mutual Information (MI) between the two electrodes for each pair of peaks.

    It evaluates the MI for the concatenated peaks and returns the average MI value for the pairs of peaks.

  • delta_lim (int, optional) – The delta limit for the subharmonic tension metric. Default is 20.

  • save (bool, optional) – Whether to save the connectivity matrix. Default is False.

  • savename (str, optional) – The name to use when saving the connectivity matrix. Default is ‘_’.

  • graph (bool, optional) – Whether to display a heatmap of the connectivity matrix. Default is True.

Returns

conn_matrix (numpy.ndarray) – The harmonic connectivity matrix between electrodes.

compute_time_resolved_harm_connectivity(sf, nIMFs, metric='harmsim', delta_lim=50)[source]#

Computes the time-resolved harmonic connectivity matrix between electrodes.

Parameters

  • data (numpy.ndarray) – Input data with shape (num_electrodes, numDataPoints)

  • sf (int) – Sampling frequency

  • nIMFs (int) – Number of intrinsic mode functions (IMFs) to consider.

  • metric (str, optional) – The metric to use for computing harmonic connectivity. Default is ‘harmsim’.

  • delta_lim (int, optional) – The delta limit for the subharmonic tension metric. Default is 20.

Returns

connectivity_matrices (numpy.ndarray) – Time-resolved harmonic connectivity matrices with shape (IMFs, numDataPoints, electrodes, electrodes).

transitional_connectivity(data=None, sf=None, mode='win_overlap', overlap=10, delta_lim=20, graph=False, n_trans_harm=3)[source]#

Compute the transitional connectivity between electrodes using transitional harmony and temporal correlation with False Discovery Rate (FDR) correction.

Parameters

  • data (numpy.ndarray) – Multichannel EEG data with shape (n_electrodes, n_timepoints).

  • sf (float) – Sampling frequency of the EEG data in Hz.

  • mode (str, optional, default=’win_overlap’) – The mode to compute the transitional harmony. Default is ‘win_overlap’.

  • overlap (int, optional, default=10) – The percentage of overlap between consecutive windows when computing the transitional harmony. Default is 10.

  • delta_lim (int, optional, default=20) – The maximum allowed frequency change (delta frequency) between two consecutive peaks in Hz. Default is 20.

  • graph (bool, optional, default=False) – If True, it will plot the graph of the transitional harmony. Default is False.

  • n_trans_harm (int, optional, default=3) – Number of transitional harmonics to compute. Default is 3.

Returns

  • conn_mat (numpy.ndarray) – Connectivity matrix of shape (n_electrodes, n_electrodes) representing the transitional connectivity between electrodes.

  • pval_mat (numpy.ndarray) – P-value matrix of shape (n_electrodes, n_electrodes) with FDR-corrected p-values for the computed connectivity values.

Notes

This function computes the transitional connectivity between electrodes by first calculating the transitional harmony for each electrode and then computing the temporal correlation between the transitional harmonies with FDR correction for multiple comparisons.

plot_conn_matrix(conn_matrix=None, node_names=None)[source]#
compute_harmonic_spectrum_connectivity(sf=None, data=None, precision=0.5, fmin=None, fmax=None, noverlap=1, power_law_remove=False, n_peaks=5, metric='harmsim', n_harms=10, delta_lim=0.1, min_notes=2, plot=False, smoothness=1, smoothness_harm=1, phase_mode=None, save_fig=False, savename='harmonic_spectrum_connectivity.png')[source]#
get_harm_spectrum_metric_matrix(metric)[source]#
wPLI_crossfreq(signal1, signal2, peak1, peak2, sf)[source]#

Computes the weighted phase lag index (wPLI) between two signals in specified frequency bands, centered around provided peak frequencies.

Parameters

  • signal1 (ndarray) – First signal in time series.

  • signal2 (ndarray) – Second signal in time series.

  • peak1 (float) – Center of the frequency band for the first signal.

  • peak2 (float) – Center of the frequency band for the second signal.

  • sf (float) – Sampling frequency.

Returns

wPLI (float) – Weighted phase lag index between two signals in specified frequency bands.

Examples

>>> signal1 = np.random.normal(0, 1, 5000)
>>> signal2 = np.random.normal(0, 1, 5000)
>>> peak1 = 10.0
>>> peak2 = 20.0
>>> sf = 100.0
>>> wPLI = wPLI_crossfreq(signal1, signal2, peak1, peak2, sf)
wPLI_multiband(signal1, signal2, freq_bands, sf)[source]#

Computes the weighted phase lag index (wPLI) between two signals for multiple frequency bands.

Parameters

  • signal1 (ndarray) – First signal in time series.

  • signal2 (ndarray) – Second signal in time series.

  • freq_bands (list of tuple) – List of frequency bands. Each band is represented as a tuple (lowcut, highcut).

  • sf (float) – Sampling frequency.

Returns

wPLI_values (list of float) – List of wPLI values for each frequency band.

Examples

>>> signal1 = np.random.normal(0, 1, 5000)
>>> signal2 = np.random.normal(0, 1, 5000)
>>> freq_bands = [(8, 12), (13, 30), (30, 70)]
>>> sf = 100.0
>>> wPLI_values = wPLI_multiband(signal1, signal2, freq_bands, sf)
compute_mutual_information(phase1, phase2, num_bins=10)[source]#
MI_spectral(signal1, signal2, sf, min_freq, max_freq, precision, peak_pairs, wavelet='cmor')[source]#
cross_frequency_rrci(signal1, signal2, sfreq, freq_peak1, freq_peak2, bandwidth=1, max_denom=50)[source]#

Computes the Rhythmic Ratio Coupling Index (RRCI) between two signals for cross-frequency.

The function first calculates the rhythmic ratio between two peak frequencies. It then filters the two input signals around a frequency band centered on their respective peak frequencies. Finally, it calculates the rhythmic ratio coupling index (RRCI) for these filtered signals. The RRCI is a measure of how much the rhythms of the two signals, in terms of their phase information, are coupled across different frequencies. In other words, it provides a measure of phase-to-phase coupling across these frequencies.

Parameters

  • signal1 (ndarray) – First signal in time series.

  • signal2 (ndarray) – Second signal in time series.

  • sfreq (float) – Sampling frequency.

  • freq_peak1 (float) – Peak frequency for the first signal.

  • freq_peak2 (float) – Peak frequency for the second signal.

  • bandwidth (float, default=1) – Frequency bandwidth for filtering the signals.

  • max_denom (int, default=50) – The maximum denominator for the rhythmic ratio.

Returns

rrci (float) – Rhythmic Ratio Coupling Index between the two signals.

Examples

>>> signal1 = np.random.normal(0, 1, 5000)
>>> signal2 = np.random.normal(0, 1, 5000)
>>> sfreq = 100.0
>>> rrci = cross_frequency_rrci(signal1, signal2, sfreq, 10, 20, 2, 4)
compute_rhythmic_ratio(freq1, freq2, max_denom)[source]#
rhythmic_ratio_coupling_imaginary(signal1, signal2, rhythmic_ratio, sfreq, freq_band1, freq_band2)[source]#

Computes the Imaginary part of Rhythmic Ratio Coupling between two signals.

Parameters

  • signal1 (ndarray) – First signal in time series.

  • signal2 (ndarray) – Second signal in time series.

  • rhythmic_ratio (tuple) – Rhythmic ratio (numerator, denominator).

  • sfreq (float) – Sampling frequency.

  • freq_band1 (tuple) – Frequency band for the first signal (lowcut, highcut).

  • freq_band2 (tuple) – Frequency band for the second signal (lowcut, highcut).

Returns

imaginary_part (float) – Imaginary part of the Rhythmic Ratio Coupling.

HilbertHuang1D_nopeaks(data, sf, graph=False, nIMFs=5, min_freq=1, max_freq=45, precision=0.5, bin_spread='log', smooth_sigma=None)[source]#

The Hilbert-Huang transform provides a description of how the energy or power within a signal is distributed across frequency. The distributions are based on the instantaneous frequency and amplitude of a signal.

Parameters

  • data (array (numDataPoints,)) – Single time series.

  • sf (int) – Sampling frequency.

  • graph (bool, default=False) – Defines if a graph is generated.

  • nIMFs (int, default=5) – Number of intrinsic mode functions (IMFs) to keep when Empirical Mode Decomposition (EMD) is computed.

  • min_freq (float, default=1) – Minimum frequency to consider.

  • max_freq (float, default=80) – Maximum frequency to consider.

  • precision (float, default=0.1) – Value in Hertz corresponding to the minimal step between two frequency bins.

  • bin_spread (str, default=’log’) –

    • ‘linear’

    • ‘log’

  • smooth_sigma (float, default=None) – Sigma value for gaussian smoothing.

Returns

  • IF (array (numDataPoints,nIMFs)) – instantaneous frequencies associated with each IMF.

  • IP (array (numDataPoints,nIMFs)) – instantaneous power associated with each IMF.

  • IA (array (numDataPoints,nIMFs)) – instantaneous amplitude associated with each IMF.

  • spec (array (nIMFs, nbins)) – Power associated with all bins for each IMF

  • bins (array (nIMFs, nbins)) – Frequency bins for each IMF

EMD_time_resolved_harmonicity(time_series1, time_series2, sf, nIMFs=5, method='harmsim')[source]#

Computes the harmonicity between the instantaneous frequencies (IF) for each point in time between all pairs of corresponding intrinsic mode functions (IMFs).

Parameters

  • time_series1 (array (numDataPoints,)) – First time series.

  • time_series2 (array (numDataPoints,)) – Second time series.

  • sf (int) – Sampling frequency.

  • nIMFs (int, default=5) – Number of intrinsic mode functions (IMFs) to consider.

Returns

harmonicity (array (numDataPoints, nIMFs)) – Harmonicity values for each pair of corresponding IMFs.

temporal_correlation_fdr(data)[source]#

Compute the temporal correlation for each pair of electrodes and output a connectivity matrix and a matrix of FDR-corrected p-values.

Args: data (array): An array of shape (electrodes, samples) containing the electrode recordings.

Returns: connectivity_matrix (array): A connectivity matrix of shape (electrodes, electrodes) with the temporal correlation for each pair of electrodes. fdr_corrected_pvals (array): A matrix of FDR-corrected p-values of shape (electrodes, electrodes).

compute_cross_spectrum_harmonicity(signal1, signal2, precision_hz, fmin=None, fmax=None, noverlap=1, fs=44100, power_law_remove=False, n_peaks=5, metric='harmsim', n_harms=10, delta_lim=0.1, min_notes=2, plot=False, smoothness=1, smoothness_harm=1, phase_mode=None, save_fig=False, save_name='harmonic_spectrum_connectivity.png')[source]#