Biotuner utilities

sample_rate = 44100

My utility functions.

This module contains a collection of utility functions for working with lists, numbers, and strings.

These functions are useful for manipulating proportions:

• compute_peak_ratios(peaks, rebound=True, octave=2, sub=False): Flatten a nested list into a single list.

• unique(lists): Remove duplicates from a list while preserving order.

• split(lists, n): Split a list into n roughly equal parts.

These functions perform various mathematical operations:

• add(x, y): Add two numbers together.

• multiply(x, y): Multiply two numbers together.

• divide(x, y): Divide one number by another.

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

type – Description of returned object.

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)

_summary_

Parameters

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

Returns

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

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 lists) – Each sublist 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.

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: https://github.com/narayanps/NolinearTimeSeriesAnalysis/blob/ 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')

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.

input:

x: the input signal window_len: dimension of the smoothing window; should be an odd integer window: type of window

{‘flat’, ‘hanning’, ‘hamming’, ‘bartlett’, ‘blackman’} flat window will produce a moving average smoothing.

output:

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)

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

listen_scale(scale, fund, duration=1)

frequency_to_note(frequency)

create_midi(chords, durations, microtonal=True, filename='example')

Creates a MIDI file from a given set of chords and durations. Args:

chords (list): List of chords, where each chord is a list of frequencies. durations (list): List of durations (in beats) for each chord. microtonal (bool): Indicates whether to include microtonal pitch bends (default: True). filename (str): Name of the output MIDI file (default: ‘example’).

Returns:

mid (MidiFile): The created MIDI file object.

create_SCL(scale, fname)

Save a scale to .scl file.

Parameters

• scale (list) – List of scale steps.

• fname (str) – Name of the saved file.

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.

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 ‘/home/franc/git/biotuner/biotuner/biotuner_utils.py’>