Biotuner object#

class compute_biotuner(sf, data=None, peaks_function='EMD', precision=0.1, compute_sub_ratios=False, n_harm=10, harm_function='mult', extension_method='consonant_harmonic_fit', ratios_n_harms=5, ratios_harms=False, ratios_inc=True, ratios_inc_fit=False, scale_cons_limit=0.1)[source]#

Bases: object

Class used to derive peaks information, musical tunings, rhythms and related harmonicity metrics from time series (EEG, ECG, EMG, gravitational waves, noise, …)

>>> biotuning = compute_biotuner(sf = 1000)
>>> biotuning.peaks_extraction(data)
>>> biotuning.peaks_extension()
>>> biotuning.peaks_metrics()
Parameters

  • sf (int) – Sampling frequency (in Hz)

  • data (array (numDataPoints,)) – Time series to analyze.

  • peaks_function (str, default=’EMD’) – Defines the method to use for peak extraction.

    ‘NON-HARMONIC PEAK EXTRACTIONS’
    ‘fixed’ :

    Power Spectrum Density (PSD) estimated using Welch’s method on fixed frequency bands. Peaks correspond to frequency bins with the highest power.

    ‘adapt’ :

    PSD estimated using Welch’s method on each frequency band derived from the alpha peak position. Peaks correspond to frequency bins with the highest power.

    ‘FOOOF’ :

    PSD is estimated with Welch’s method. ‘FOOOF’ is applied to remove the aperiodic component and find physiologically relevant spectral peaks.

    ‘SIGNAL DECOMPOSITION BASED PEAK EXTRACTION’
    ‘EMD’:

    Intrinsic Mode Functions (IMFs) are derived with Empirical Mode Decomposition (EMD) PSD is computed on each IMF using Welch. Peaks correspond to frequency bins with the highest power.

    ‘EEMD’ :

    Intrinsic Mode Functions (IMFs) are derived with Ensemble Empirical Mode Decomposition (EEMD). PSD is computed on each IMF using Welch. Peaks correspond to frequency bins with the highest power.

    ‘CEEMDAN’Intrinsic Mode Functions (IMFs) are derived with Complex

    Ensemble Empirical Mode Decomposition with Adaptive Noise (CEEMDAN). PSD is computed on each IMF using Welch.

    ‘EMD_FOOOF’ :

    Intrinsic Mode Functions (IMFs) are derived with Ensemble Empirical Mode Decomposition (EEMD). PSD is computed on each IMF with Welch’s method. ‘FOOOF’ is applied to remove the aperiodic component and find physiologically relevant spectral peaks.

    ‘HH1D_max’ :

    Maximum values of the 1D Hilbert-Huang transform on each IMF using EMD.

    ‘HH1D_FOOOF’ :

    Hilbert-Huang transform on each IMF with Welch’s method ‘FOOOF’ is applied to remove the aperiodic component and find physiologically relevant spectral peaks.

    ‘SSA’ :

    Singular Spectrum Analysis. The name “singular spectrum analysis” relates to the spectrum of eigenvalues in a singular value decomposition of a covariance matrix.

    ‘SECOND-ORDER STATISTICAL PEAK EXTRACTION’
    ‘cepstrum’:

    Peak frequencies of the cepstrum (inverse Fourier transform (IFT) of the logarithm of the estimated signal spectrum).

    ‘HPS (to come)’ :

    Harmonic Product Spectrum (HPS) corresponds to the product of the spectral power at each harmonic. Peaks correspond to the frequency bins with the highest value of the HPS.

    ‘Harmonic_salience (to come)’ :

    A measure of harmonic salience computed by taking the sum of the squared cosine of the angle between a harmonic and its neighbors.

    ‘CROSS-FREQUENCY COUPLING BASED PEAK EXTRACTION’
    ‘Bicoherence’ :

    Corresponds to the normalized cross-bispectrum. It is a third-order moment in the frequency domain. It is a measure of phase-amplitude coupling.

    ‘PAC’ :

    Phase-amplitude coupling. A measure of phase-amplitude coupling between low-frequency phase and high-frequency amplitude.

    ‘PEAK SELECTION BASED ON HARMONIC PROPERTIES’
    ‘EIMC’ :

    Endogenous InterModulation Components (EIMC) correspond to spectral peaks that are sums or differences of other peaks harmonics (f1+f2, f1+2f2, f1-f2, f1-2f2…). PSD is estimated with Welch’s method. All peaks are extracted.

    ‘harmonic_recurrence’ :

    PSD is estimated with Welch’s method. All peaks are extracted. Peaks for which other peaks are their harmonics are kept.

    ‘PEAKS EXTRACTION PARAMETERS’

  • precision (float, default=0.1) – Precision of the peaks (in Hz). When HH1D_max is used, bins are in log scale by default.

  • compute_sub_ratios (bool, default=False) – When set to True, include ratios < 1 in peaks_ratios attribute.

  • scale_cons_limit (float, default=0.1) – The minimal value of consonance needed for a peaks ratio to be included in the peaks_ratios_cons attribute.

    ‘EXTENDED PEAKS PARAMETERS’

  • n_harm (int, default=10) – Set the number of harmonics to compute in harmonic_fit function.

  • harm_function (str, default=’mult’) –

    • ‘mult’Computes harmonics from iterative multiplication

      (x, 2x, 3x…)

    • ‘div’: Computes harmonics from iterative division (x, x/2, x/3…).

  • extension_method (str, default=’consonant_harmonic_fit’) –

    • ‘consonant_harmonic_fit’computes the best-fit of harmonic peaks

      according to consonance intervals (eg. octaves, fifths).

    • ‘all_harmonic_fit’computes the best-fit of harmonic peaks without

      considering consonance intervals.

    ‘RATIOS EXTENSION PARAMETERS’

  • ratios_n_harms (int, default=5) – The number of harmonics used to compute extended peaks ratios.

  • ratios_harms (bool, default=False) – When set to True, harmonics (x*1, x*2, x*3…,x*n) of specified ratios will be computed.

  • ratios_inc (bool, default=True) – When set to True, exponentials (x**1, x**2, x**3,…x**n) of specified ratios will be computed.

  • ratios_inc_fit (bool, Default=False) – When set to True, a fit between exponentials (x**1, x**2, x**3,…x**n) of specified ratios will be computed.

pygame_lib = None#
peaks_extraction(data, peaks_function=None, FREQ_BANDS=None, precision=None, sf=None, min_freq=1, max_freq=60, min_harms=2, compute_sub_ratios=False, ratios_extension=False, ratios_n_harms=None, scale_cons_limit=None, octave=2, harm_limit=128, n_peaks=5, prominence=1.0, rel_height=0.7, nIMFs=5, graph=False, nperseg=None, nfft=None, noverlap=None, max_harm_freq=None, EIMC_order=3, min_IMs=2, smooth_fft=1, verbose=False, keep_first_IMF=False)[source]#

The peaks_extraction method is central to the use of the Biotuner. It uses a time series as input and extract spectral peaks based on a variety of methods. See peaks_function parameter description in __init__ function for more details.

Parameters

  • data (array (numDataPoints,)) – biosignal to analyse

  • peaks_function (str) – refer to __init__

  • FREQ_BANDS (List of lists of float) – Each list within the list of lists sets the lower and upper limit of a frequency band

  • precision (float, default=0.1 -> __init__) – Precision of the peaks (in Hz) When HH1D_max is used, bins are in log scale.

  • sf (int) – Sampling frequency (in Hertz).

  • min_freq (float, default=1) – minimum frequency value to be considered as a peak Used with ‘harmonic_recurrence’ and ‘HH1D_max’ peaks functions

  • max_freq (float, default=60) – maximum frequency value to be considered as a peak Used with ‘harmonic_recurrence’ and ‘HH1D_max’ peaks functions

  • min_harms (int, default=2) – minimum number of harmonics to consider a peak frequency using the ‘harmonic_recurrence’ function.

  • compute_sub_ratios (Boolean, default=False) – If set to True, will include peaks ratios (x/y) when x < y

  • ratios_extension (Boolean, default=False) – When set to True, peaks_ratios harmonics and increments are computed.

  • ratios_n_harms (int, default=5 -> __init__) – number of harmonics or increments to use in ratios_extension method

  • scale_cons_limit (float, default=0.1) – minimal value of consonance to be reach for a peaks ratio to be included in the peaks_ratios_cons attribute.

  • octave (float, default=2) – value of the octave

  • harm_limit (int, default=128) – Maximum harmonic position for ‘harmonic_recurrence’ method.

  • n_peaks (int, default=5) – Number of peaks when using ‘FOOOF’ and ‘cepstrum’, and ‘harmonic_recurrence’ functions. Peaks are chosen based on their amplitude.

  • prominence (float, default=1.0) – Minimum prominence of peaks.

  • rel_height (float, default=0.7) – Minimum relative height of peaks.

  • nIMFs (int, default=5) – Number of intrinsic mode functions to keep when using ‘EEMD’ or ‘EMD’ peaks function.

  • graph (boolean, default=False) – When set to True, a graph will accompanies the peak extraction method (except for ‘fixed’ and ‘adapt’).

  • nperseg (int, default=None) – Length of each segment. If None, nperseg = nfft/smooth

  • nfft (int, default=None) – Length of the FFT used, if a zero padded FFT is desired. If None, nfft = sf/(1/precision)

  • noverlap (int, default=None) – Number of points to overlap between segments. If None, noverlap = nperseg // 2.

  • max_harm_freq (int, default=None) – Maximum frequency value of the find peaks function when harmonic_recurrence or EIMC peaks extraction method is used.

  • EIMC_order (int, default=3) – Maximum order of the Intermodulation Components.

  • min_IMs (int, default=2) – Minimal number of Intermodulation Components to select the associated pair of peaks.

  • smooth_fft (int, default=1) – Number used to divide nfft to derive nperseg.

  • verbose (boolean, default=True) – When set to True, number of detected peaks will be displayed.

  • keep_first_IMF (boolean, default=False) – When set to True, the first IMF is kept.

self.peaks#

List of frequency peaks

Type

List (float)

self.amps#

List of peaks amplitude

Type

List (float)

self.peaks_ratios#

List of ratios between all pairs of peaks

Type

List (float)

self.peaks_ratios_cons#

List of consonant peaks ratios

Type

List (float)

'If ratios_extension = True'
self.peaks_ratios_harm#

List of peaks ratios and their harmonics

Type

List (float)

self.peaks_ratios_inc#

List of peaks ratios and their increments (ratios**n)

Type

List (float)

self.peaks_ratios_inc_bound#

List of peaks ratios and their increments (ratios**n) bound within one octave

Type

List (float)

self.peaks_ratios_inc_fit#

List of peaks ratios and their congruent increments (ratios**n)

Type

List (float)

peaks_extension(peaks=None, n_harm=None, method='harmonic_fit', harm_function='mult', div_mode='add', cons_limit=0.1, ratios_extension=False, harm_bounds=0.1, scale_cons_limit=None)[source]#

This method is used to extend a set of frequencies based on the harmonic congruence of specific elements (extend). It can also restrict a set of frequencies based on the consonance level of specific peak frequencies.

Parameters

  • peaks (List of float) – List of frequency peaks.

  • n_harm (int, default=10) – Set the number of harmonics to compute in harmonic_fit function

  • method (str, default=’harmonic_fit’) –

    • ‘harmonic_fit’

    • ‘consonant’

    • ‘multi_consonant’,

    • ‘consonant_harmonic_fit’

    • ‘multi_consonant_harmonic_fit’

  • harm_function (str, default=’mult’) –

    • ‘mult’ : Computes harmonics from iterative multiplication (x, 2x, 3x, …nx)

    • ‘div’ : Computes harmonics from iterative division (x, x/2, x/3, …x/n)

  • div_mode (strm default=’add’) – Defines the way the harmonics are computed when harm_function is ‘div’

    • ‘div’: x, x/2, x/3 …, x/n

    • ‘div_add’: x, (x+x/2), (x+x/3), … (x+x/n)

    • ‘div_sub’: x, (x-x/2), (x-x/3), … (x-x/n)

  • cons_limit (float) – Defines the minimal consonance level used in the method.

  • ratios_extension (Boolean, default=False) – If is True, ratios_extensions are computed accordingly to what was defined in __init__.

  • harm_bounds (float, default=0.1) – Maximal distance in Hertz between two frequencies to consider them as equivalent.

  • scale_cons_limit (float, default=None) – Minimal value of consonance to be reach for a peaks ratio to be included in the extended_peaks_ratios_cons attribute. When None, scale_cons_limit = 0.1, as defined in __init__

Returns

  • self.extended_peaks (List (float)) – List of extended peaks frequencies.

  • self.extended_amps (List (float)) – List of extended peaks amplitudes.

  • self.extended_peaks_ratios (List (float)) – List of pairwise extended peaks ratios.

  • self.extended_peaks_ratios_cons (List (float)) – List of pairwise extended peaks ratios when more consonant than scale_limit_cons parameter.

'If ratios_extension is True'
self.peaks_ratios_harm#

List of extended peaks ratios and their harmonics

Type

List (float)

self.peaks_ratios_inc#

List of extended peaks ratios and their increments (ratios**n)

Type

List (float)

self.peaks_ratios_inc_fit#

List of extended peaks ratios and their congruent increments (ratios**n).

Type

List (float)

ratios_extension(ratios, ratio_fit_bounds=0.001, ratios_n_harms=None)[source]#

This method takes a series of ratios as input and returns the harmonics (ratio*2, ratio*3, …, ratio*n) or the increments (ratio**2, ratio**3, …, ratio**n).

Parameters

  • ratios (List (float)) – List of frequency ratios.

  • ratio_fit_bounds (float, default=0.001) – Minimal distance between two ratios to consider a fit for the harmonic_fit function.

  • ratios_n_harms (int, default=None) – Number of harmonics or increments to compute. When None, the number of harmonics or increments is set to the value of the attribute ratios_n_harms.

Returns

  • ratios_harms_ (List (float)) – List of ratios harmonics.

  • ratios_inc_ (List (float)) – List of ratios increments.

  • ratios_inc_fit_ (List (float)) – List of ratios increments that fit.

compute_spectromorph(IMFs=None, sf=None, method='SpectralCentroid', window=None, overlap=1, comp_chords=False, min_notes=3, cons_limit=0.2, cons_chord_method='cons', graph=False)[source]#

This method computes spectromorphological metrics on each Intrinsic Mode Function (IMF).

Parameters

  • IMFs (array (nIMFs, numDataPoints)) – Intrinsic Mode Functions. When set to ‘None’, the IMFs are computed in the method.

  • sf (int) – Sampling frequency.

  • method (str, default=’SpectralCentroid’) –

    Spectromorphological metric to compute.

    • ‘SpectralCentroid’,

    • ‘SpectralCrestFactor’,

    • ‘SpectralDecrease’,

    • ‘SpectralFlatness’,

    • ‘SpectralFlux’,

    • ‘SpectralKurtosis’,

    • ‘SpectralMfccs’,

    • ‘SpectralPitchChroma’,

    • ‘SpectralRolloff’,

    • ‘SpectralSkewness’,

    • ‘SpectralSlope’,

    • ‘SpectralSpread’,

    • ‘SpectralTonalPowerRatio’,

    • ‘TimeAcfCoeff’,

    • ‘TimeMaxAcf’,

    • ‘TimePeakEnvelope’,

    • ‘TimeRms’,

    • ‘TimeStd’,

    • ‘TimeZeroCrossingRate’,}

  • window (int) – Window size in samples.

  • overlap (int) – Value of the overlap between successive windows.

  • comp_chords (Boolean, default=False) – When set to True, consonant spectral chords are computed.

  • min_notes (int, default=3) – Minimum number of consonant values to store a spectral chord.

  • cons_limit (float, default=0.2) – Minimal value of consonance.

  • cons_chord_method (str, default=’cons’) – Metrics to use for consonance computation.

  • graph (Boolean, default=False) – Defines if graph is plotted.

self.spectro_EMD#

Spectromorphological metric vector for each IMF.

Type

array (numDataPoints, nIMFs)

self.spectro_chords#

Each sublist corresponds to a list of consonant spectromorphological metrics.

Type

List of lists (float)

compute_peaks_metrics(n_harm=None, harm_bounds=0.5, delta_lim=20)[source]#

This function computes consonance metrics on peaks attribute.

Parameters

  • n_harm (int) – Set the number of harmonics to compute in harmonic_fit function

  • harm_bounds (float, default=0.5) – Maximal distance in Hertz between two frequencies to consider them as equivalent.

self.peaks_metrics#

Dictionary with keys corresponding to the different metrics.

  • ‘cons’

  • ‘euler’

  • ‘tenney’

  • ‘harm_fit’

  • ‘harmsim’

  • ‘n_harmonic_recurrence’,

  • ‘n_harmonic_recurrence_ratio’

  • ‘harm_pos’

  • ‘common_harm_pos’

Type

dict

compute_diss_curve(input_type='peaks', denom=1000, max_ratio=2, euler_comp=False, method='min', plot=False, n_tet_grid=12, scale_cons_limit=None)[source]#

Compute dissonance curve based on peak frequencies.

Parameters

  • input_type (str, default=’peaks’) – Defines whether peaks or extended_peaks are used.

    • ‘peaks’

    • ‘extended_peaks’

  • denom (int, default=1000) – Maximal value of the denominator when computing frequency ratios.

  • max_ratio (float, default=2) – Value of the maximal frequency ratio to use when computing the dissonance curve. When set to 2, the curve spans one octave. When set to 4, the curve spans two octaves.

  • euler_comp (Boolean, default=False) – Defines if euler consonance is computed. Can be computationally expensive when the number of local minima is high.

  • method (str, default=’min’) – Refer to dissmeasure function in scale_construction.py for more information.

    • ‘min’

    • ‘product’

  • plot (Boolean, default=False) – When set to True, dissonance curve is plotted.

  • n_tet_grid (int, default=12) – Defines which N-TET tuning is indicated, as a reference, in red in the dissonance curve plot.

  • scale_cons_limit (float, default=None) – Minimal value of consonance to be reach for a peaks ratio to be included in the self.diss_scale_cons attribute. When set to None, the value of self.scale_cons_limit is used.

self.diss_scale#

List of frequency ratios corresponding to local minima.

Type

List (float)

self.diss_scale_cons#

List of frequency ratios corresponding to consonant local minima.

Type

List (float)

self.scale_metrics#

Add 4 metrics related to the dissonance curve tuning:

  • ‘diss_euler’

  • ‘dissonance’

  • ‘diss_harm_sim’

  • ‘diss_n_steps’

Type

dict

compute_harmonic_entropy(input_type='peaks', res=0.001, spread=0.01, plot_entropy=True, plot_tenney=False, octave=2, rebound=True, sub=False, scale_cons_limit=None)[source]#

Computes the harmonic entropy from a series of spectral peaks. Harmonic entropy has been introduced by Paul Elrich [http://www.tonalsoft.com/enc/e/erlich/harmonic-entropy_with- commentary.aspx]

Parameters

  • input_type (str, default=’peaks’) – Defines whether peaks or extended_peaks are used.

    • ‘peaks’

    • ‘extended_peaks’

  • res (float, default=0.001) – Resolution of the ratio steps.

  • spread (float, default=0.01) – Spread of the normal distribution used to compute the weights.

  • plot_entropy (Boolean, default=True) – When set to True, plot the harmonic entropy curve.

  • plot_tenney (Boolean, default=False) – When set to True, plot the tenney heights (y-axis) across ratios (x-axis).

  • octave (int, default=2) – Value of the octave.

  • rebound (Boolean, default=True) – When set to True, peaks ratios are bounded within the octave.

  • sub (Boolean, default=False) – When set to True, will include ratios below the unison (1)

  • scale_cons_limit (type, default=None) – Minimal value of consonance to be reach for a peaks ratio to be included in the self.diss_scale_cons attribute. When set to None, the value of self.scale_cons_limit is used.

self.HE_scale#

List of frequency ratios corresponding to local minima.

Type

List (float)

self.HE_scale_cons#

List of frequency ratios corresponding to consonant local minima.

Type

List (float)

self.scale_metrics#

Four metrics related to the dissonance curve tuning:

  • ‘HE’

  • ‘HE_n_steps’

  • ‘HE_harm_sim’

Type

dict

euler_fokker_scale(method='peaks', octave=2)[source]#

Create a scale in the Euler-Fokker Genera. which is a musical scale in just intonation whose pitches can be expressed as products of some of the members of some multiset of generating primer numbers.

Parameters

  • method (str, default=’peaks’) – Defines which set of frequencies are used.

    • ‘peaks’

    • ‘extended_peaks’

  • octave (float, default=2) – Value of period interval.

Returns

self.euler_fokker (List (float)) – Euler-Fokker genera.

harmonic_tuning(list_harmonics, octave=2, min_ratio=1, max_ratio=2)[source]#

Generates a tuning based on a list of harmonic positions.

Parameters

  • list_harmonics (List of int) – harmonic positions to use in the scale construction

  • octave (int, default=2) – value of the period reference

  • min_ratio (float, default=1) – Value of the unison.

  • max_ratio (float, default=2) – Value of the octave.

Returns

ratios (List (float)) – Generated tuning.

harmonic_fit_tuning(n_harm=128, bounds=0.1, n_common_harms=2)[source]#

Extracts the common harmonics of spectral peaks and compute the associated harmonic tuning.

Parameters

  • n_harm (int) – Number of harmonics to consider in the harmonic fit`.

  • bounds (float, default=0.1) – Maximal distance in Hertz between two frequencies to consider them as equivalent.

  • n_common_harms (int, default=2) – minimum number of times the harmonic is found to be sent to most_common_harmonics output.

Returns

self.harmonic_fit_tuning (List (float)) – Generated tuning

pac(sf=None, method='duprelatour', n_values=10, drive_precision=0.05, max_drive_freq=6, min_drive_freq=3, sig_precision=1, max_sig_freq=50, min_sig_freq=8, low_fq_width=0.5, high_fq_width=1, plot=False)[source]#

Computes the phase-amplitude coupling and returns to pairs of frequencies that have highest coupling value.

Parameters

  • sf (int) – Sampling frequency in hertz.

  • method (str, default=’duprelatour’) –

    Choice of method for PAC calculation.

    STANDARD_PAC_METRICS:

    • ‘ozkurt’

    • ‘canolty’

    • ‘tort’

    • ‘penny’

    • ‘vanwijk’

    DAR_BASED_PAC_METRICS:

    • ‘duprelatour’

    COHERENCE_PAC_METRICS:

    • ‘jiang’

    • ‘colgin’

    BICOHERENCE_PAC_METRICS:

    • ‘sigl’

    • ‘nagashima’

    • ‘hagihira’

    • ‘bispectrum’

  • n_values (int, default=10) – Number of pairs of frequencies to return.

  • drive_precision (float, default=0.05) – Step-size between each phase signal bins.

  • max_drive_freq (float, default=6) – Maximum value of the phase signal in hertz.

  • min_drive_freq (float, default=3) – Minimum value of the phase signal in hertz.

  • sig_precision (float, default=1) – Step-size between each amplitude signal bins.

  • max_sig_freq (float, default=50) – Maximum value of the amplitude signal in hertz.

  • min_sig_freq (float, default=8) – Minimum value of the amplitude signal in hertz.

  • low_fq_width (float, default=0.5) – Bandwidth of the band-pass filter (phase signal)

  • high_fq_width (float, default=1) – Bandwidth of the band-pass filter (amplitude signal)

  • plot (Boolean, default=False) – When set to True, a plot of the comodulogram is generated.

Returns

  • self.pac_freqs (List of lists (float)) – Pairs of frequencies with highest coupling value.

  • self.pac_coupling (List (float)) – Values of coupling for each pair in self.pac_freqs

compute_peaks_ts(data, peaks_function='EMD', FREQ_BANDS=None, precision=0.5, sf=None, min_freq=1, max_freq=80, min_harms=2, harm_limit=128, n_peaks=5, prominence=1.0, rel_height=0.7, nIMFs=None, graph=False, noverlap=None, average='median', nfft=None, nperseg=None, max_harm_freq=None, EIMC_order=3, min_IMs=2, smooth_fft=1, keep_first_IMF=False)[source]#

Extract peak frequencies. This method is called by the peaks_extraction method.

Parameters

  • data (array (numDataPoints,)) – Niosignal to analyse

  • peaks_function (str) – Refer to __init__

  • FREQ_BANDS (List of lists of floats) – Each list within the list of lists sets the lower and upper limit of a frequency band

  • precision (float, default=0.5) – Precision of the peaks (in Hz) When HH1D_max is used, bins are in log scale.

  • sf (int, default=None) – Sampling frequency in hertz.

  • min_freq (float, default=1) – Minimum frequency value to be considered as a peak Used with ‘harmonic_recurrence’ and ‘HH1D_max’ peaks functions

  • max_freq (float, default=80) – Maximum frequency value to be considered as a peak Used with ‘harmonic_recurrence’ and ‘HH1D_max’ peaks functions

  • min_harms (int, default=2) – Minimum number of harmonics to be considered for peaks extraction

  • harm_limit (int, default=128) – Maximum harmonic position for ‘harmonic_recurrence’ method.

  • n_peaks (int, default=5) – Number of peaks when using ‘FOOOF’ and ‘cepstrum’, and ‘harmonic_recurrence’ functions. Peaks are chosen based on their amplitude.

  • prominence (float, default=1.0) – Minimum prominence value to be considered as a peak Used with ‘harmonic_recurrence’ and ‘HH1D_max’ peaks functions

  • rel_height (float, default=0.7) – Minimum relative height value to be considered as a peak

  • nIMFs (int, default=None) – number of intrinsic mode functions to keep when using ‘EEMD’ or ‘EMD’ peaks function.

  • graph (boolean, default=False) – When set to True, a graph will accompanies the peak extraction method (except for ‘fixed’ and ‘adapt’).

  • noverlap (int, default=None) – Number of samples overlap between each fft window. When set to None, equals sf//10.

  • average (str, default=’median’) – Method to use when averaging periodograms.

    • ‘mean’: average periodograms

    • ‘median’: median periodograms

  • max_harm_freq (int, default=None) – Maximum frequency value of the find peaks function when harmonic_recurrence or EIMC peaks extraction method is used.

  • EIMC_order (int, default=3) – Maximum order of the Intermodulation Components.

  • min_IMs (int, default=2) – Minimal number of Intermodulation Components to select the associated pair of peaks.

  • smooth_fft (int, default=1) – Number used to divide nfft to derive nperseg. When set to 1, nperseg = nfft.

  • keep_first_IMF (boolean, default=False) – When set to True, the first IMF is kept.

Returns

  • peaks (List (float)) – List of peaks frequencies.

  • amps (List (float)) – List of amplitudes associated with peaks frequencies.

self.freqs#

Vector representing the frequency bins of the Power Spectrum Density (PSD)

Type

array

self.psd#

Vector representing the PSD values for each frequency bin.

Type

array

self.IMFs#

Intrinsic mode functions resulting from decomposing the signal with Empirical Mode Decomposition.

Type

array (nIMFs, numDataPoints)

self.IF#

instantaneous frequencies for each IMF. Only when ‘HH1D_max’ is used as peaks extraction method.

Type

array (nIMFs, numDataPoints)

self.all_harmonics#

List of all harmonic positions when harmonic_recurrence method is used.

Type

List (int)

self.FREQ_BANDS#

List of frequency bands.

Type

List of lists (float)

compute_resonance(harm_thresh=30, PPC_thresh=0.6, smooth_fft=2, harmonicity_metric='harmsim', delta_lim=50)[source]#

Compute resonances between pairs of frequency peaks in the data.

Parameters

  • harm_thresh (int, default=30) – The minimum harmonic similarity between a peak pair required to be considered a resonance. Must be a positive integer.

  • PPC_thresh (float, default=0.6) – The minimum bispectral power correlation required for a peak pair to be considered a resonance. Must be a float between 0 and 1.

  • smooth_fft (int, default=2) – The number of times to smooth the data using a Hamming window before computing the FFT. Must be a positive integer. When smooth_fft=1, nperseg=nfft.

  • harmonicity_metric (str, default=’harmsim’) – The metric to use for computing the harmonic similarity between a pair of peaks. Choose between:

    • ‘harmsim’

    • ‘subharm_tension’

  • delta_lim (int, default=50) – The maximum number of subharmonic intervals to consider when using the ‘subharm_tension’ metric. Must be a positive integer.

Returns

Tuple[float, List[Tuple[float, float]], List[float], List[float]] – A tuple containing the following elements:

  • resonance: a float representing the mean weighted bicorrelation coefficient across all harmonic pairs that meet the specified criteria for harmonicity and PPC

  • resonant_freqs: a list of tuples, where each tuple contains two floats representing the frequencies of a pair of resonant harmonics that meet the specified criteria for harmonicity and PPC

  • harm_all: a list of floats representing the harmonic similarity metric between all possible harmonic pairs

  • bicor_all: a list of floats representing the bicorrelation coefficient between all possible harmonic pairs

listen_scale(scale, fund=250, length=500)[source]#

Play a scale of notes using pygame.

Parameters

  • scale (str or np.ndarray) – The scale to play. If scale is a string, it can be one of:

    • ‘peaks’: the scale is set to the biotuner object’s peaks_ratios attribute

    • ‘diss’: the scale is set to the biotuner object’s diss_scale attribute

    • ‘HE’: the scale is set to the biotuner object’s HE_scale attribute

    If scale is a numpy array, it should be an array of scale ratios.

  • fund (float, default=250) – The fundamental frequency of the scale.

  • length (float, default=500) – The length of each note in milliseconds.

Returns

None

fit_all(data, compute_diss=True, compute_HE=True, compute_peaks_extension=True)[source]#

Fit biotuning metrics to input data using various optional computations.

Parameters

  • data (array, shape (n_samples,)) – A single time series of EEG data.

  • compute_diss (bool, optional, default=True) – If True, compute the dissonance curve.

  • compute_HE (bool, optional, default=True) – If True, compute the harmonic entropy.

  • compute_peaks_extension (bool, optional, default=True) – If True, compute the peaks extension using the multi-consonant harmonic fit method.

Returns

biotuning (Biotuning object) – The fitted biotuning object containing the computed metrics.

info(metrics=False, scales=False, whatever=False)[source]#
fit_biotuner(ts, bt_dict)[source]#

Compute biotuner metrics on a single time series using a specified set of parameters.

Parameters

  • ts (array, shape (n_samples,)) – A single time series of EEG data.

  • bt_dict (dict) – A dictionary containing the parameters to compute biotuner metrics. See the compute_biotuner and tuning_to_metrics functions documentation for details on the required keys and values.

Returns

bt_dict (dict) – The modified input dictionary with the computed biotuner metrics added.