Private functions

find_delay.find_delay._filter_frequencies(array, frequency, filter_below=None, filter_over=None, verbosity=1)

Applies a low-pass, high-pass or band-pass filter to the data in the attribute samples.

Added in version 1.0.

Changed in version 1.1: Turned into a “private” function by adding a leading underscore.

Parameters:
  • array (list or np.ndarray) – An array of samples.

  • frequency (int or float) – The sampling frequency of the array, in Hz.

  • filter_below (float or None, optional) – The value below which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a high-pass filter will be applied to the samples; if filter_over is also provided, a band-pass filter will be applied to the samples.

  • filter_over (float or None, optional) – The value over which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a low-pass filter will be applied to the samples; if filter_below is also provided, a band-pass filter will be applied to the samples.

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

The array with filtered values.

Return type:

np.array

find_delay.find_delay._get_number_of_windows(array_length_or_array, window_size, overlap_ratio=0, add_incomplete_window=True)

Given an array, calculates how many windows from the defined window_size can be created, with or without overlap.

Added in version 1.0.

Changed in version 1.1: Turned into a “private” function by adding a leading underscore.

Changed in version 1.3: Function temporarily removed as it was unused at the time.

Changed in version 2.1: Function reinstated.

Parameters:
  • array_length_or_array (list(int or float) or np.array(int or float) or int) – An array of numerical values, or its length.

  • window_size (int) – The number of array elements in each window.

  • overlap_ratio (float) – The ratio, between 0 and 1, of array elements overlapping between each window and the next.

  • add_incomplete_window (bool) – If set on True, the last window will be included even if its size is smaller than window_size. Otherwise, it will be ignored.

Returns:

The number of windows than can be created from the array.

Return type:

int

find_delay.find_delay._get_envelope(array, frequency, window_size=1000000.0, overlap_ratio=0.5, filter_below=None, filter_over=None, verbosity=1)

Calculates the envelope of an array, and returns it. The function can also optionally perform a band-pass filtering, if the corresponding parameters are provided.

Added in version 1.0.

Changed in version 1.1: Turned into a “private” function by adding a leading underscore.

Changed in version 2.0: Sets the number of windows to 1 if the parameter number_of_windows is lower than 1 (deprecated by version 2.1).

Changed in version 2.1: The function now takes a window_size parameter instead of a number_of_windows.

Changed in version 2.4: Corrected the progression percentage display.

Parameters:
  • array (list or np.ndarray) – An array of samples.

  • frequency (int or float) – The sampling frequency of the array, in Hz.

  • window_size (int or None, optional) –

    The size of the windows (in samples) in which to cut the array to calculate the envelope. Cutting large arrays into windows allows to speed up the computation. If this parameter is set on None, the window size will be set on the number of samples. A good value for this parameter is generally 1 million. If this parameter is set on 0, on None or on a number of samples bigger than the amount of elements in the array, the window size is set on the length of the samples.

    Added in version 2.1.

  • overlap_ratio (float or None, optional) – The ratio of samples overlapping between each window. If this parameter is not None, each window will overlap with the previous (and, logically, the next) for an amount of samples equal to the number of samples in a window times the overlap ratio. Then, only the central values of each window will be preserved and concatenated; this allows to discard any “edge” effect due to the windowing. If the parameter is set on None or 0, the windows will not overlap.

  • filter_below (int, float or None, optional) – If not None nor 0, this value will be provided as the lowest frequency of the band-pass filter.

  • filter_over (int, float or None, optional) – If not None nor 0, this value will be provided as the highest frequency of the band-pass filter.

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

The envelope of the original array.

Return type:

np.array

find_delay.find_delay._resample_window(array, original_timestamps, resampled_timestamps, index_start_original, index_end_original, index_start_resampled, index_end_resampled, method='cubic', verbosity=1)

Performs and returns the resampling on a subarray of samples.

Added in version 1.0.

Changed in version 1.1: Turned into a “private” function by adding a leading underscore.

Parameters:
  • array (list or np.ndarray) – An array of samples.

  • original_timestamps (list or np.ndarray) – An array containing the timestamps for each sample of the original array.

  • resampled_timestamps (list or np.ndarray) – An array containing the timestamps for each desired sample in the resampled array.

  • index_start_original (int) – The index in the array where the window starts.

  • index_end_original (int) – The index in the array where the window ends.

  • index_start_resampled (int) – The index in the resampled array where the window starts.

  • index_end_resampled (int) – The index in the resampled array where the window ends.

  • method (str, optional) –

    This parameter allows for various values:

    • "linear" performs a linear numpy.interp interpolation. This method, though simple, may not be very precise for upsampling naturalistic stimuli.

    • "cubic" performs a cubic interpolation via scipy.interpolate.CubicSpline. This method, while smoother than the linear interpolation, may lead to unwanted oscillations nearby strong variations in the data.

    • "pchip" performs a monotonic cubic spline interpolation (Piecewise Cubic Hermite Interpolating Polynomial) via scipy.interpolate.PchipInterpolator.

    • "akima" performs another type of monotonic cubic spline interpolation, using scipy.interpolate.Akima1DInterpolator.

    • "take" keeps one out of n samples from the original array. While being the fastest computation, it will be prone to imprecision if the downsampling factor is not an integer divider of the original frequency.

    • "interp1d_XXX" uses the function scipy.interpolate.interp1d. The XXX part of the parameter can be replaced by "linear", "nearest", "nearest-up", "zero", “slinear”, ``"quadratic", "cubic", "previous", and "next" (see the documentation of this function for specifics).

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

The envelope of the original array.

Return type:

np.array

find_delay.find_delay._resample(array, original_frequency, resampling_frequency, window_size=10000000.0, overlap_ratio=0.5, method='cubic', verbosity=1)

Resamples an array to the resampling_frequency parameter. It first creates a new set of timestamps at the desired frequency, and then interpolates the original data to the new timestamps.

Added in version 1.0.

Changed in version 1.1: Turned into a “private” function by adding a leading underscore.

Changed in version 2.0: Sets the number of windows to 1 if the parameter number_of_windows is lower than 1 (deprecated).

Changed in version 2.1: The function now takes a window_size parameter instead of a number_of_windows.

Changed in version 2.4: Corrected the progression percentage display.

Parameters:
  • array (list or np.ndarray) – An array of samples.

  • original_frequency (int or float) – The sampling frequency of the array, in Hz.

  • resampling_frequency (int or float) – The frequency at which you want to resample the array, in Hz. A frequency of 4 will return samples at 0.25 s intervals.

  • window_size (int or None, optional) –

    The size of the windows (in samples) in which to cut the array before resampling. Cutting large arrays into windows allows to speed up the computation. If this parameter is set on None, the window size will be set on the number of samples. A good value for this parameter is generally 10 million. If this parameter is set on 0, on None or on a number of samples bigger than the amount of elements in the array, the window size is set on the length of the samples.

    Added in version 2.1.

  • overlap_ratio (float or None, optional) – The ratio of samples overlapping between each window. If this parameter is not None, each window will overlap with the previous (and, logically, the next) for an amount of samples equal to the number of samples in a window times the overlap ratio. Then, only the central values of each window will be preserved and concatenated; this allows to discard any “edge” effect due to the windowing. If the parameter is set on None or 0, the windows will not overlap.

  • method (str, optional) –

    This parameter allows for various values:

    • "linear" performs a linear numpy.interp interpolation. This method, though simple, may not be very precise for upsampling naturalistic stimuli.

    • "cubic" performs a cubic interpolation via scipy.interpolate.CubicSpline. This method, while smoother than the linear interpolation, may lead to unwanted oscillations nearby strong variations in the data.

    • "pchip" performs a monotonic cubic spline interpolation (Piecewise Cubic Hermite Interpolating Polynomial) via scipy.interpolate.PchipInterpolator.

    • "akima" performs another type of monotonic cubic spline interpolation, using scipy.interpolate.Akima1DInterpolator.

    • "take" keeps one out of n samples from the original array. While being the fastest computation, it will be prone to imprecision if the downsampling factor is not an integer divider of the original frequency.

    • "interp1d_XXX" uses the function scipy.interpolate.interp1d. The XXX part of the parameter can be replaced by "linear", "nearest", "nearest-up", "zero", “slinear”, ``"quadratic", "cubic", "previous", and "next" (see the documentation of this function for specifics).

  • verbosity (int, optional) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

The resampled array.

Return type:

array

Warning

This function allows both the upsampling and the downsampling of arrays. However, during any of these operations, the algorithm only estimates the real values of the samples. You should then consider the upsampling (and the downsampling, to a lesser extent) with care.

find_delay.find_delay._convert_to_mono(audio_data, mono_channel, verbosity=1)

Converts an audio array to mono.

Added in version 2.9.

Parameters:
  • audio_data (np.array (1D or 2D)) – The parameter data resulting from reading a WAV file with scipy.io.wavfile.read.

  • mono_channel (int or str, optional) – Defines the method to use to convert multiple-channel WAV files to mono, if one of the parameters array1 or array2 is a path pointing to a WAV file. By default, this parameter value is 0: the channel with index 0 in the WAV file is used as the array, while all the other channels are discarded. This value can be any of the channels indices (using 1 will preserve the channel with index 1, etc.). This parameter can also take the value "average": in that case, a new channel is created by averaging the values of all the channels of the WAV file. Note that this parameter applies to both arrays: in the case where you need to select different channels for each WAV file, open the files before calling the function and pass the samples and frequencies as parameters.

  • verbosity (int) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.

Returns:

A 1D numpy array containing the audio converted to mono.

Return type:

np.array

find_delay.find_delay._create_figure(array_1, array_2, freq_array_1, freq_array_2, name_array_1, name_array_2, envelope_1, envelope_2, y1, y2, compute_envelope, window_size_env, overlap_ratio_env, filter_below, filter_over, resampling_rate, window_size_res, overlap_ratio_res, cross_correlation, threshold, number_of_plots, return_delay_format, return_value, max_correlation_value, index_max_correlation_value, plot_figure, path_figure, name_figure, plot_intermediate_steps, x_format_figure, verbosity)

Creates and/or saves a figure given the parameters of the find_delay function.

Added in version 1.1.

Changed in version 1.2: Added transparency in the graph overlay.

Changed in version 2.0: Modified subplot titles to reflect changes of separated number of windows between both arrays. Corrected the figure saving to a file and prevented overwriting the same figure using find_delays.

Changed in version 2.2: Arrays with different amplitudes now appear scaled on the aligned arrays graph. Added a second y-axis to the aligned arrays graph.

Changed in version 2.3: Corrected the figure saving to a file. If plot_intermediate_steps is False, the two graphs “cross-correlation” and “aligned arrays” are now on top of each other instead of side-by-side.

Changed in version 2.4: Added the new parameter x_format_figure, allowing to have HH:MM:SS times on the x-axis. Modified the scaling of the aligned arrays figure to be more accurate.

Parameters:
  • array_1 (np.array) – The first array involved in the cross-correlation.

  • array_2 (np.array) – The second array involved in the cross-correlation, being allegedly an excerpt from the first.

  • freq_array_1 (int or float) – The sampling rate of array_1.

  • freq_array_2 (int or float) – The sampling rate of array_2.

  • name_array_1 (str) – The name of the first array; will be “Array 1” for find_delay and “Array” for find_delays.

  • name_array_2 (str) – The name of the second array; will be “Array 2” for find_delay and “Excerpt n” for find_delays, with n being the index of the excerpt in the folder.

  • envelope_1 (np.array) – The envelope of array_1 (if calculated).

  • envelope_2 (np.array) – The envelope of array_2 (if calculated).

  • y1 (np.array) – The resampled array_1 or envelope_1 (if calculated).

  • y2 (np.array) – The resampled array_2 or envelope_2 (if calculated).

  • compute_envelope (bool) – A boolean describing if the envelope has been computed or not.

  • window_size_env (int) – The size of the windows in which the arrays were cut for the envelope calculation.

  • overlap_ratio_env (float) – The ratio of overlapping between each envelope window with the previous and the next windows.

  • filter_below (int, float or None) – The lower limit of the bandpass filter applied to the envelopes.

  • filter_over (int, float or None) – The upper limit of the bandpass filter applied to the envelopes.

  • resampling_rate (int, float or None) – The rate at which the arrays or the envelopes have been resampled.

  • window_size_res (int) – The size of the windows in which the arrays or envelopes were cut for the resampling.

  • overlap_ratio_res (float) – The ratio of overlapping between each resampling window with the previous and the next windows.

  • cross-correlation (np.array) – The array containing the correlation values for each lag between the two arrays.

  • threshold (float) – The threshold of the maximum correlation value between the two arrays, relative to the maximum correlation value between the excerpt and itself.

  • return_delay_format (str) – Indicates the format of the displayed delay, either "index", "ms", "s", or "timedelta".

  • return_value (int, float or timedelta) – The value of the delay in the format specified by the previous parameter.

  • max_correlation_value (float) – The maximum correlation value from the cross-correlation.

  • index_max_correlation_value (int) – The index at which the maximum correlation value can be found in the cross-correlation array.

  • plot_figure (bool) – If set on True, plots the figure in a Matplotlib window.

  • path_figure (str or None) – If set, saves the figure at the given path.

  • name_figure (str or None) – If set, considers that path_figure is the directory where to save the figure, and name_figure is the name of the file.

  • plot_intermediate_steps (bool) – If set on True, plots the original audio clips, the envelopes and the resampled arrays (if calculated) besides the cross-correlation.

  • x_format_figure (str) – If set on “time”, the values on the x axes of the output will take the HH:MM:SS format (or MM:SS if the time series are less than one hour long). If set on “float”, the values on the x axes will be displayed as float (unit: second). If set on “auto” (default), the format of the values on the x axes will be defined depending on the value of return_delay_format.

  • verbosity (int) –

    Sets how much feedback the code will provide in the console output:

    • 0: Silent mode. The code won’t provide any feedback, apart from error messages.

    • 1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.

    • 2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.