Private functions

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

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|`np.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_) – An array of samples.

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

  • filter_below (float|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|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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.

Returns:

The array with filtered values.

Return type:

np.ndarray

find_delay.private_functions._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 (numpy.ndarray|list|int) – An array of numerical values, or its length.

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

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

  • add_incomplete_window (bool, optional) – If set on True (default), 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.private_functions._get_envelope(array, frequency, window_size=1000000.0, overlap_ratio=0.5, filter_below=None, filter_over=None, verbosity=1, add_tabs=0)

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. To calculate the envelope, the function calculates the absolute values of the scipy.signal.hilbert transform of each window of the envelope.

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 (numpy.ndarray|list) – An array of samples.

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

  • window_size (int|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 (default). 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|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. Default value: 0.5 (each window will overlap at 50% with the previous and the next).

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

  • filter_over (int|float|None, optional) – If not None (default) 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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.

Returns:

The envelope of the original array.

Return type:

np.ndarray

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

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 (numpy.ndarray|list) – An array of samples.

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

  • resampled_timestamps (numpy.ndarray|list) – 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" (default) 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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.

Returns:

The envelope of the original array.

Return type:

np.ndarray

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

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 (numpy.ndarray|list) – An array of samples.

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

  • resampling_frequency (int|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|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 (default). 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|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. Default value: 0.5 (each window will overlap at 50% with the previous and the next).

  • 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" (default) 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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.

Returns:

The resampled array.

Return type:

np.ndarray

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.private_functions._cross_correlation(y1, y2, rate, freq_y1_original, threshold, return_delay_format, verbosity=1, add_tabs=0)

Performs a normalized cross-correlation between two arrays.

Added in version 2.12.

y1: np.ndarray

The first array to cross-correlate.

y2: np.ndarray

The second array to cross-correlate.

rate: int|float

The frequency rate of the two arrays.

freq_y1_original: int|float

The original frequency rate of y1, before resampling.

threshold: float

The threshold of the minimum correlation value between the two arrays to accept a delay as a solution. If multiple delays are over threshold, the delay with the maximum correlation value will be returned. This value should be between 0 and 1; if the maximum found value is below the threshold, the function will return None instead of a timestamp.

return_delay_format: str, optional

This parameter can be either "index", "ms", "s", or "timedelta":

  • If "index" (default), the function will return the index in array_1 at which array_2 has the highest cross-correlation value.

  • If "ms", the function will return the timestamp in array_1, in milliseconds, at which array_2 has the highest cross-correlation value.

  • If "s", the function will return the timestamp in array_1, in seconds, at which array_2 has the highest cross-correlation value.

  • If "timedelta", the function will return the timestamp in array_1 at which array_2 has the highest cross-correlation value as a datetime.timedelta object. Note that, in the case where the result is negative, the timedelta format may give unexpected display results (-1 second returns -1 days, 86399 seconds).

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.

add_tabs: int, optional

Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

Added in version 2.12.

Returns:

  • np.ndarray – The normalized cross-correlation array.

  • int|float|timedelta|None – The sample index, timestamp or timedelta of y1 at which y2 can be found (defined by the parameter return_delay_format), or None if y1 is not contained in y2.

  • float – The max correlation value from the normalized cross-correlation array.

  • int – The index of this max correlation value in the normalized cross-correlation array.

find_delay.private_functions._convert_to_mono(audio_data, mono_channel=0, verbosity=1, add_tabs=0)

Converts an audio array to mono.

Added in version 2.9.

Parameters:
  • audio_data – The parameter data resulting from reading a WAV file with scipy.io.wavfile.read.

  • mono_channel (int|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, 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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.

Returns:

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

Return type:

np.array

find_delay.private_functions._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, dark_mode, verbosity, add_tabs)

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 – The first array involved in the cross-correlation.

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

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

  • freq_array_2 (in|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 – The envelope of array_1 (if calculated).

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

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

  • y2 – 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|None) – The lower limit of the bandpass filter applied to the envelopes.

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

  • resampling_rate (int|float|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 – 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|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|None) – If set, saves the figure at the given path.

  • name_figure (str|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.

  • dark_mode (bool, optional) – If set on True, uses the dark_background theme from matplotlib (default: False).

  • 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.

  • add_tabs (int, optional) –

    Adds the specified amount of tabulations to the verbosity outputs (default: 0). This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them.

    Added in version 2.12.