Transitional Harmony

Transitional Harmony#

class transitional_harmony(sf=None, data=None, peaks_function='EMD', precision=0.1, n_harm=10, max_harm_freq=150, harm_function='mult', min_freq=2, max_freq=80, n_peaks=5, n_trans_harm=10, mode='win_overlap', overlap=10, FREQ_BANDS=None)[source]#

Bases: object

Class used to compute subharmonic progressions in successive windows of time.

Parameters:

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

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

  • peaks_function (str, default=’EMD’) – See compute_biotuner class for details.

  • precision (float, default=0.1) – Precision of the peaks (in Hz) When HH1D_max is used, bins are in log scale. Also used to divide the time series in successive windows. ChunkSizes = (1/precision)*sf

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

  • max_harm_freq (int, default=150) – Set the maximum frequency to consider in harmonic_fit function and peaks_extraction function

  • harm_function (str, default=’mult’) – Computes harmonics from iterative multiplication (x, 2x, 3x, …nx) or division (x, x/2, x/3, …x/n). choice:

    • ‘mult’ : iterative multiplication

    • ‘div’ : iterative division

  • min_freq (int, default=2) – Minimum frequency to consider (in Hz)

  • max_freq (int, default=80) – Maximum frequency to consider (in Hz)

  • n_peaks (int, default=5) – Number of peaks to extract in the peaks_extraction function.

  • mode (str, default=’win_overlap’) – The method used to chunk the time series. choice:

    • ‘win_overlap’ : divide the time series in successive windows

    • ‘IF’ : uses the instantaneous frequency using Hilbert-Huang transform

  • overlap (int, default=10) – The overlap between successive windows, in number of samples.

  • FREQ_BANDS (list of list of int) – The frequency bands used in the ‘fixed’ peaks_function.

compute_trans_harmony(mode='win_overlap', overlap=10, delta_lim=20, graph=False, save=False, savename='_', n_elements=2, keep_first_IMF=False)[source]#

Computes the transitional subharmonic tension between successive windows of a time series.

Parameters:

  • mode (str, default=’win_overlap) – The method used to chunk the time series. choice:

    • ‘win_overlap’ : divide the time series in successive windows

    • ‘IF’ : uses the instantaneous frequency using Hilbert-Huang transform

  • overlap (int, default=10) – The overlap between successive windows, in percentage of the window size.

  • delta_lim (int, default=20) – The maximum time difference allowed between the closest common subharmonic in two consecutive windows, in milliseconds.

  • graph (bool, default=False) – Whether to plot the transitional subharmonic tension as a function of time.

  • save (bool, default=False) – Whether to save the plot as a PNG file.

  • savename (str, default=’_’) – The filename of the saved plot, without the extension.

  • keep_first_IMF (bool, default=False) – Whether to keep the first IMF in the EMD decomposition.

  • n_elements (int, default=2) – TODO

Returns:

  • trans_subharm (list of float) – The list of transitional subharmonic tension values for each pair of windows.

  • time_vec_final (list of float) – The corresponding list of time values.

  • subharm_melody (list of tuple of int) – The list of pairs of indices of the closest common subharmonic in each pair of windows.

Notes

This method chunks the time series using the specified mode and overlap parameters, and for each pair of consecutive windows, it extracts the subharmonic of spectral peaks. It then computes the closest common subharmonics between the two sets of peaks, and determines the transitional subharmonic tension. The resulting values are stored in the trans_subharm and time_vec_final lists, and optionally plotted and saved.

compare_deltas(deltas, save=False, savename='_')[source]#

Compares the transitional subharmonic tension for multiple maximum delta limits.

Parameters:

  • deltas (list of int) – The list of maximum time differences allowed between the closest common subharmonic in consecutive windows, in milliseconds.

  • save (bool, default=False) – Whether to save the plot as a PNG file.

  • savename (str, default=’_’) – The filename of the saved plot, without the extension.

Returns:

fig (matplotlib.figure.Figure) – The figure showing the plotted data.

Notes

This method computes the transitional subharmonic tension for each maximum delta limit in the deltas list, using the compute_trans_harmony method. It then plots the resulting values as a function of time, using a different color for each delta value, and optionally saves the plot.