Biotuner utilities

compute_peak_ratios(peaks, rebound=True, octave=2, sub=False)

This function calculates all the ratios

(with the possibility to bound them between 1 and 2) derived from input peaks.

Parameters:

• peaks (List (float)) – Peaks represent local maximum in a spectrum

• rebound (boolean) – Defaults to True. False will output unbounded ratios

• octave (int) – Arbitrary wanted number of octaves. Defaults to 2.

• sub (boolean) – Defaults to False. True will include ratios below the unison (1)

Returns:

ratios_final (List) – List of frequency ratios.

scale2frac(scale, maxdenom=1000)

Transforms a scale provided as a list of floats into a list of fractions.

Parameters:

• scale (List) – List of floats, typically between 1 and 2, representing scale steps.

• maxdenom (int) – Maximum denominator of the output fractions.

Returns:

• scale_frac (List) – List of fractions representing scale steps.

• num (array) – Numerators of all fractions.

• den (array) – Denominators of all fractions.

ratio2frac(ratio, maxdenom=1000)

Trasform a ratio expressed as a float in to a fraction.

Parameters:

• ratio (float) – Frequency ratio, typically between 1 and 2.

• maxdenom (type) – Maximum denominator of the output fractions.

Returns:

frac (List) – List of 2 int (numerator and denominator).

frac2scale(scale)

Transforms a scale expressed in fractions

into a set of float ratios.

Parameters:

scale (List) – List of fractions.

Returns:

scale_ratio (List) – Original scale expressed in float ratios.

chords_to_ratios(chords, harm_limit=2, spread=True)

Transforms series of frequencies expressed in float

into series of integer ratios.

Parameters:

• chords (List of lists) – Each sublist corresponds to a series of frequencies expressed in float.

• harm_limit (int) – Defaults to 2 Maximum harmonic of the lower note below which the higher note should fall.

• spread (Boolean) – Defaults to True. When set to True, the harm_limit is applied to the previous note. When set to False, the harm_limit is applied to the first note. When harm_limit == 2, setting the spread to False will contain the chords within the span of one octave.

Returns:

• chords_ratios (List of lists) – List of chords expressed as integer ratios.

• chords_ratios_bounded (List of lists) – List of chords expressed as integer ratios and bounded between 1 and 2.

NTET_steps(octave, step, NTET)

This function computes the ratio associated with a specific step

of a N-TET scale.

Parameters:

• octave (int) – value of the octave

• step (int) – value of the step

• NTET (int) – number of steps in the N-TET scale

Returns:

answer (float) – Step value.

NTET_ratios(n_steps, max_ratio, octave=2)

Generate a series of ratios dividing the octave in N equal steps.

Parameters:

• n_steps (int) – Number of steps dividing the octave.

• max_ratio (type) – Description of parameter max_ratio.

• octave (float) – Defaults to 2. Value of the octave (period).

Returns:

steps_out (List) – List of steps in decimal numbers.

scale_from_pairs(pairs)

Transforms each pairs of frequencies to ratios.

Parameters:

pairs (List of lists) – Each sublist is a pair of frequencies.

Returns:

scale (List) – Scale steps.

ratios_harmonics(ratios, n_harms=1)

Computes the harmonics of ratios in the form of r*n when

r is the ratio expressed as a float and n is the integer representing the harmonic position.

Parameters:

• ratios (List) – List of ratios expressed as float.

• n_harms (int) – Number of harmonics to compute.

Returns:

ratios_harms (List) – List of original ratios and their harmonics.

ratios_increments(ratios, n_inc=1)

Computes the harmonics of ratios in the form of r**n when

r is the ratio expressed as a float and n is the integer representing the increment (e.g. stacking ratios).

Parameters:

• ratios (type) – Description of parameter ratios.

• n_inc (type) – Description of parameter n_inc.

Returns:

ratios_harms (List) – List of original ratios and their harmonics.

ratios2cents(ratios)

Converts a list of frequency ratios to cents.

Parameters:

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

Returns:

cents (List (float)) – List of corresponding cents

ratio_to_name(ratio)

This function returns the name of a ratio in the form of a fraction

Parameters:

ratio (float) – Frequency ratio

Returns:

name (str) – Name of the ratio

flatten(t)

Flattens a list of lists.

Parameters:

t (List of lists)

Returns:

List – Flattened list.

findsubsets(S, m)

Find all subsets of m elements in a list.

Parameters:

• S (List) – List to find subsets in.

• m (int) – Number of elements in each subset.

Returns:

List of lists – Each sublist represents a subset of the original list.

pairs_most_frequent(pairs, n)

Finds the most frequent values in a list of lists of pairs of numbers.

Parameters:

• pairs (List of lists) – Each sublist should be a pair of values.

• n (int) – Number of most frequent pairs to keep.

Returns:

List of lists – First sublist corresponds to most frequent first values. Second sublist corresponds to most frequent second values.

rebound(x, low=1, high=2, octave=2)

Rescale a value within given range.

Parameters:

• x (float) – Value to rebound.

• low (int) – Lower bound. Defaults to 1.

• high (int) – Higher bound. Defaults to 2.

• octave (int) – Value of an octave.

Returns:

x (float) – Input value rescaled between low and high values.

rebound_list(x_list, low=1, high=2, octave=2)

Rescale a list within given range.

Parameters:

• x (list) – List to rebound.

• low (int) – Lower bound. Defaults to 1.

• high (int) – Higher bound. Defaults to 2.

• octave (int) – Value of an octave.

Returns:

x (list) – Rescaled list between low and high values.

sum_list(list)

Compute the sum of a list.

Parameters:

list (list) – List of values to sum.

Returns:

sum (float) – Sum of the list.

compareLists(list1, list2, bounds)

Find elements that are closest than bounds value from

two lists.

Parameters:

• list1 (list) – First list.

• list2 (list) – Second list.

• bounds (float) – Maximum value between two elements to assume equivalence.

Returns:

• matching (array) – Elements that match between the two list (average value of the two close elements).

• positions (list) – All indexes of the selected elements combined in one list.

• matching_pos (array (n_matching, 3)) – For each matching, a list of the value and the positions in list1 and list2.

Print3Smallest(arr)

top_n_indexes(arr, n)

Find the index pairs of maximum values in a 2d array.

Parameters:

• arr (ndarray(i, j)) – 2d array.

• n (int) – Number of index pairs to return.

Returns:

indexes (List of tuples) – Each tuple contains the 2 indexes associated with higest values of the input array.

getPairs(peaks)

Extract all possible pairs of elements from a list.

Parameters:

peaks (List) – List of values.

Returns:

out (List of lists) – Each sublist corresponds to a pair of value.

nth_root(num, root)

This function computes the nth root of a number.

Parameters:

• num (int) – value of the octave

• root (int) – number of steps in the N-TET scale

Returns:

answer (float) – nth root.

gcd(*numbers)

Return the greatest common divisor of the given integers The result will have the same sign as the last number given (so that when the last number is divided by the result, the result comes out positive).

Parameters:

*numbers (List) – List of numbers.

Returns:

a (float) – Greated common divisor of the input numbers.

reduced_form(*numbers)

Return a tuple of numbers which is the reduced form of the input,

which is a list of integers. Ex: [4, 8, 12, 80] -> [1, 2, 3, 20]

Parameters:

*numbers (list (float)) – List of numbers to reduce.

Returns:

reduce (list (int)) – Reduced form of the input.

lcm(*numbers)

Return the least common multiple of the given integers.

Parameters:

*numbers (list (float)) – List of numbers.

Returns:

lcm_ (int) – Least common multiple of the input numbers.

prime_factors(n)

Return a list of the prime factors of the integer n.

Don’t use this for big numbers; it’s a dumb brute-force method.

Parameters:

n (int) – Integer to factorize.

Returns:

factors (list) – List of prime factors of n.

prime_factor(n)

Find the prime number in a list of n numbers.

Parameters:

n (type) – Description of parameter n.

Returns:

type – Description of returned object.

contFrac(x, k)

Compute the continuous fraction of a value x for k steps.

Parameters:

• x (float) – Value to decompose.

• k (int) – Number of steps to go through.

Returns:

cf (list) – List of denominators (1/cf[0] + 1/cf[1] … +1/cf[k]).

compute_IMs(f1, f2, n)

InterModulation components: sum or subtraction of any non-zero integer multiple of the input frequencies.

Parameters:

• f1 (float) – Frequency 1.

• f2 (float) – Frequency 2.

• n (int) – Order of the intermodulation component.

Returns:

• IMs (List) – List of all intermodulation components.

• order (List) – Order associated with IMs.

Examples

>>> f1 = 3
>>> f2 = 12
>>> n = 2
>>> IMs, order = compute_IMs(f1, f2, n)
>>> IMs, order
([9, 15, 21, 27, 6, 18, 30],
[(1, 1), (1, 1), (1, 2), (1, 2), (2, 1), (2, 1), (2, 2)])

phaseScrambleTS(ts)

Returns a TS: original TS power is preserved; TS phase is shuffled.

Parameters:

ts (1d array (numDataPoints, )) – Oriinal time series.

Returns:

tsr (array (numDataPoints)) – Phase scrabled time series.

AAFT_surrogates(original_data)

Return surrogates using the amplitude adjusted Fourier transform

method.

Parameters:

original_data (2D array (data, index)) – The original time series.

Returns:

rescaled_data (2D array (surrogate, index))

correlated_noise_surrogates(original_data)

Return Fourier surrogates.

Generate surrogates by Fourier transforming the original_data time series (assumed to be real valued), randomizing the phases and then applying an inverse Fourier transform. Correlated noise surrogates share their power spectrum and autocorrelation function with the original_data time series.

Parameters:

original_data (2D array (data, index)) – The original time series.

Returns:

• surrogates (2D array (surrogate, index)) – Surrogates of the original time series.

• .. note:: – The amplitudes are not adjusted here, i.e., the individual amplitude distributions are not conserved!

UnivariateSurrogatesTFT(data_f, MaxIter=1, fc=5)

Compute Truncated Fourier Transform of the input data.

from: narayanps/NolinearTimeSeriesAnalysis master/SurrogateModule.py

Parameters:

• data_f (array) – Original signal.

• MaxIter (int) – Defaults to 1. Maximum number of iterations.

• fc (int) – Defaults to 5. Description of parameter fc.

Returns:

xsur (array) – Surrogate of the original signal.

computeFeatureCl_new(afAudioData, cFeatureName, f_s, window=4000, overlap=1)

Calculate spectromorphological metrics on time series.

Parameters:

• afAudioData (array (numDataPoints, )) – Input signal.

• cFeatureName (str) –

  {‘SpectralCentroid’, ‘SpectralCrestFactor’, ‘SpectralDecrease’,

  ‘SpectralFlatness’, ‘SpectralFlux’, ‘SpectralKurtosis’, ‘SpectralMfccs’, ‘SpectralPitchChroma’, ‘SpectralRolloff’, ‘SpectralSkewness’, ‘SpectralSlope’, ‘SpectralSpread’, ‘SpectralTonalPowerRatio’, ‘TimeAcfCoeff’, ‘TimeMaxAcf’, ‘TimePeakEnvelope’, ‘TimeRms’, ‘TimeStd’, ‘TimeZeroCrossingRate’}

• f_s (int) – Sampling frequency.

• window (int) – Length of the moving window in samples.

• overlap (int) – Overlap between each moving window in samples.

Returns:

• v (array) – Vector of the spectromorphological metric.

• t (array) – Timestamps.

EMD_to_spectromorph(IMFs, sf, method='SpectralCentroid', window=None, overlap=1, in_cut=None, out_cut=None)

Calculate spectromorphological metrics on intrinsic mode functions

derived using Empirical Mode Decomposition.

Parameters:

• IMFs (array (nIMFs, numDataPoints)) – Input data.

• sf (int) – Sampling frequency of the original signal.

• method (str) – Defaults to ‘SpectralCentroid’. {‘SpectralCentroid’, ‘SpectralCrestFactor’, ‘SpectralDecrease’,

  ‘SpectralFlatness’, ‘SpectralFlux’, ‘SpectralKurtosis’, ‘SpectralMfccs’, ‘SpectralPitchChroma’, ‘SpectralRolloff’, ‘SpectralSkewness’, ‘SpectralSlope’, ‘SpectralSpread’, ‘SpectralTonalPowerRatio’, ‘TimeAcfCoeff’, ‘TimeMaxAcf’, ‘TimePeakEnvelope’, ‘TimeRms’, ‘TimeStd’, ‘TimeZeroCrossingRate’}

• window (int) – Length of the moving window in samples.

• overlap (int) – Overlap between each moving window in samples.

• in_cut (int) – Number of samples to remove at the beginning.

• out_cut (type) – Number of samples to remove at the end.

Returns:

spectro_IMF ((nIMFs, numSpectroPoints)) – Spectromorphological metric for each IMF.

generate_signal(sf, time_end, freqs, amps, show=False, theta=0, color='blue')

Generate a composite signal consisting of multiple sine waves.

Parameters:

• sf (int) – Sampling frequency.

• time_end (float) – Duration of the signal in seconds.

• freqs (List) – List of frequencies.

• amps (List) – List of amplitudes.

• show (bool) – Defaults to False. If True, plot the signal.

• theta (int) – Defaults to 0. Phase of the sine wave.

• color (str) – Defaults to ‘blue’. Color of the plot.

Returns:

sine_tot (array (numDataPoints,)) – Composite signal.

smooth(x, window_len=11, window='hanning')

smooth the data using a window with requested size.

This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) in both ends so that transient parts are minimized in the begining and end part of the output signal.

Parameters:

• x (array) – The input signal.

• window_len (int) – The dimension of the smoothing window; should be an odd integer.

• window (str) – Type of window. {‘flat’, ‘hanning’, ‘hamming’, ‘bartlett’, ‘blackman’} flat window will produce a moving average smoothing.

Returns:

• y (array) – The smoothed signal.

• .. note:: – length(output) != length(input), to correct this: return y[(window_len/2-1):-(window_len/2)] instead of just y.

butter_bandpass(lowcut, highcut, fs, order=5)

butter_bandpass_filter(data, lowcut, highcut, fs, order=5)

major_triad(hz)

make_chord(hz, length=1)

play_chord(chord)

Play a chord using pygame, ensuring proper format for the chord array.

Parameters:

chord (ndarray) – Array representing the chord. Expected to have dtype int16 or float32.

listen_chords(chords, mult=1, duration=1)

listen_scale(scale, fund, duration=1)

frequency_to_note(frequency)

create_midi(chords, durations, velocities=None, subdivision=1, microtonal=True, filename='example')

Creates a MIDI file from a given set of chords and durations. The microtonal parameter allows for pitch bends to be included and relies on multiple notes being played simultaneously on different channels.

Parameters:

chordslist

List of chords, where each chord is a list of frequencies.

velocitieslist

List of list of velocities for each note in each chord.

durationslist

List of durations (in beats) for each chord.

subdivisionint

Number of subdivisions per beat (default: 1).

microtonalbool

Indicates whether to include microtonal pitch bends (default: True).

filenamestr

Name of the output MIDI file (default: ‘example’).

returns:

mid (MidiFile) – The MIDI file.

create_SCL(scale, name)

Create a Scala scale file. The Scala file can be used to tune various things, most germane being Yoshimi. However, keep in mind that the Scala file does not include a base note or frequency, so for tuning purposes those data will need to be captured or input in some other way.

Parameters:

scalelist

The scale (list of frequency ratios)

namestr

The name of the scale

Returns:

outputstr

A Scala file as a string

scale_interval_names(scale, reduce=False)

Gives the name of intervals in a scale based on PyTuning dictionary.

Parameters:

• scale (list) – List of scale steps either in float or fraction form.

• reduce (boolean) – Defaults to False. When set to True, output only the steps that match a key in the dictionary.

Returns:

interval_names (list of lists) – Each sublist contains the scale step and the corresponding interval names.

distinct_intervals(scale)

Find the distinct intervals in a scale, including inversions

Parameters:

scale (list) – List of scale steps either in float or fraction form.

Returns:

intervals (list) – List of distinct intervals.

Notes

The scale should be specified as a list of numerical values. Note that the convention adopted in this code is that scale[0] is a unison and scale[-1] is the formal octave (often 2).

calculate_pvalues(df, method='pearson')

Calculate the correlation between each column of a DataFrame.

Parameters:

• df (DataFrame) – DataFrame of values to compute correlation on.

• method (str) – Defaults to pearson. {‘pearson’, ‘spearman’}

Returns:

type – Description of returned object.

peaks_to_amps(peaks, freqs, amps, sf)

Find the amplitudes of spectral peaks.

Parameters:

• peaks (list) – Spectral peaks in Hertz.

• freqs (list) – All centers of frequency bins.

• amps (list) – All amplitudes associated with frequency bins.

• sf (int) – Sampling frequency.

Returns:

amps_out (list) – Amplitudes of spectral peaks.

alpha2bands(a)

Derive frequency bands for M/EEG analysis based on the alpha peak.

Boundaries of adjacent frequency bands are derived based on the golden ratio, which optimizes the uncoupling of phases between frequencies. (see: Klimesch, 2018)

Parameters:

a (float) – Alpha peak in Hertz.

Returns:

FREQ_BANDS (List of lists) – Each sublist contains the boundaries of each frequency band.

chunk_ts(data, sf, overlap=10, precision=1)

Divide a time series into overlapping chunks and provide the indexes.

Parameters:

• data (ndarray(1d)) – Time series.

• sf (int) – Sampling frequency.

• overlap (int) – Defaults to 10. Proportion of overlap in percentage.

• precision (float) – Defaults to 1. Precision in Hertz. The precision here determines the length of data required to extract the spectral information at that precise frequency.

Returns:

type – Description of returned object.

string_to_list(string)

safe_max(lst)

safe_mean(lst)

compute_frequency_and_psd(signal, precision_hz, smoothness, fs, noverlap, fmin=None, fmax=None)

Compute the frequencies and power spectral density (PSD) of a signal using Welch method.

Parameters:

• signal (ndarray) – Input signal.

• precision_hz (float) – Precision in Hz for the frequencies.

• smoothness (float) – Smoothing factor for the PSD.

• fs (float) – Sampling frequency of the signal.

• noverlap (int) – Number of points to overlap between segments.

• fmin (float, optional) – Minimum frequency to compute.

• fmax (float, optional) – Maximum frequency to compute.

Returns:

• freqs (ndarray) – Frequencies for which the PSD is computed.

• psd (ndarray) – Power spectral density of the signal.

power_law(x, a, b)

Define a power law function.

Parameters:

• x (ndarray) – Independent variable.

• a (float) – Scaling factor.

• b (float) – Power.

Returns:

ndarray – Values after applying power law function.

apply_power_law_remove(freqs, psd, power_law_remove)

Apply or not a power law to remove it from PSD.

Parameters:

• freqs (ndarray) – Frequencies for which the PSD is computed.

• psd (ndarray) – Power spectral density of the signal.

• power_law_remove (bool) – If True, apply the power law. Otherwise, return the input PSD.

Returns:

ndarray – PSD after potential power law removal.

functools_reduce(a)

biotuner_utils

alias of <module ‘biotuner.biotuner_utils’ from ‘C:\Users\Antoine\github\biotuner\biotuner\biotuner_utils.py’>