detect¶

detect.py - Detection module of DAS4Whales package

This module provides functions for detecting whale calls in DAS strain data.

Author: Quentin Goestchel Date: 2023-2024

das4whales.detect.buildkernel(f0, f1, bdwdth, dur, f, t, samp, fmin, fmax, plotflag=False)[source]¶

Calculate kernel and plot.

Parameters:

f0 (float) – Starting frequency.
f1 (float) – Ending frequency.
bdwdth (float) – Frequency width of call.
dur (float) – Call length (seconds).
f (np.array) – Vector of frequencies returned from plotwav.
t (np.array) – Vector of times returned from plotwav.
samp (float) – Sample rate.
plotflag (bool, optional) – If True, plots kernel. If False, no plot. Default is False.
kernel_lims (tuple, optional) – Tuple of minimum kernel range and maximum kernel range. Default is finKernelLims.

Returns:

tvec (numpy.array) – Vector of kernel times.
fvec_sub (numpy.array) – Vector of kernel frequencies.
BlueKernel (2-d numpy.array) – Matrix of kernel values.
Key variables
————-
tvec (numpy.array) – Kernel times (seconds).
fvec (numpy.array) – Kernel frequencies.
BlueKernel (numpy.array) – Matrix of kernel values.

das4whales.detect.buildkernel_from_template(fmin, fmax, dur, fs, nperseg, nhop, plotflag=False)[source]¶

Build a kernel from a template.

Parameters:

fmin (float) – The minimum frequency of interest.
fmax (float) – The maximum frequency of interest.
dur (float) – The duration of the kernel in seconds.
fs (float) – The sampling rate of the kernel in Hz.
nperseg (int) – The length of each segment for the spectrogram computation.
nhop (int) – The number of samples to advance between segments.
plotflag (bool, optional) – Whether to plot the kernel, defaults to False.

Returns:

The computed kernel.

Return type:

numpy.ndarray

das4whales.detect.calc_nmf(data, template)[source]¶

Calculate the normalized matched filter between the input data and the template.

Parameters:

data (ndarray) – The input data array.
template (ndarray) – The template array.

Returns:

The normalized matched filter array (vector).

Return type:

ndarray

das4whales.detect.calc_nmf_correlogram(data, template)[source]¶

Calculate the normalized matched filter correlogram between the input data and the template.

Parameters:

data (ndarray) – The input data array.
template (ndarray) – The template array.

Returns:

The normalized matched filter correlogram array.

Return type:

ndarray

das4whales.detect.compute_cross_correlogram(data, template)[source]¶

Compute the cross correlogram between the given data and template.

Parameters:

data (ndarray) – The input data array.
template (ndarray) – The template array.

Returns:

The cross correlogram array.

Return type:

ndarray

das4whales.detect.compute_cross_correlogram_spectrocorr(data, fs, flims, kernel, win_size, overlap_pct)[source]¶

Compute the cross-correlogram via spectrogram correlation.

This function computes the cross-correlogram spectrocorr between the input data and a kernel. The cross-correlogram spectrocorr is a measure of similarity between the spectrogram of the input data and the kernel.

Parameters:

data (ndarray) – Input data array of shape (n, m), where n is the number of samples and m is the number of channels.
fs (float) – Sampling frequency of the input data.
flims (tuple) – Frequency limits (fmin, fmax) for the spectrogram computation.
kernel (dict) – Dictionary containing the kernel parameters (f0, f1, duration, bandwidth).
win_size (float) – Window size in seconds for the spectrogram computation.
overlap_pct (float) – Percentage of overlap between consecutive windows for the spectrogram computation.

Returns:

cross_correlogram – Cross-correlogram spectrocorr array of shape (n, p), where n is the number of samples and p is the number of time bins.

Return type:

ndarray

das4whales.detect.convert_pick_times(peaks_indexes_m)[source]¶

Convert pick times from a list of lists to a numpy array.

Parameters:: peaks_indexes_m (List[ndarray]) – A list of lists containing the pick times. The indexes of each list correspond to the space index. [[t1, t2, t3, …], [t1, t2, t3, …], …]
Returns:: A numpy array containing a tuple (time index, spatial index) of the converted pick times.
Return type:: Tuple[ndarray, ndarray]

das4whales.detect.gen_hyperbolic_chirp(fmin, fmax, duration, sampling_rate)[source]¶

Generate a hyperbolic chirp signal.

Parameters:

fmin (float) – The ending frequency of the chirp signal.
fmax (float) – The starting frequency of the chirp signal.
duration (float) – The duration of the chirp signal in seconds.
sampling_rate (int) – The sampling rate of the chirp signal in Hz.

Returns:

The generated hyperbolic chirp signal.

Return type:

ndarray

das4whales.detect.gen_linear_chirp(fmin, fmax, duration, sampling_rate)[source]¶

Generate a linear chirp signal.

Parameters:

fmin (float) – The ending frequency of the chirp signal.
fmax (float) – The starting frequency of the chirp signal.
duration (float) – The duration of the chirp signal in seconds.
sampling_rate (int) – The sampling rate of the chirp signal in Hz.

Returns:

The generated linear chirp signal.

Return type:

ndarray

das4whales.detect.gen_template_fincall(time, fs, fmin=15.0, fmax=25.0, duration=1.0, window=True)[source]¶

generate template of a fin whale call

Parameters:

time (ndarray) – time vector
fs (float) – sampling rate in Hz
fmin (float) – Minimum frequency, by default 15
fmax (float) – Maximum frequency, by default 25
duration (float) – Duration of the chirp signal in seconds, by default 1.
window (bool)

Return type:

ndarray

das4whales.detect.get_sliced_nspectrogram(trace, fs, fmin, fmax, nperseg, nhop, plotflag=False)[source]¶

Compute the sliced non-stationary spectrogram of a given trace.

Parameters:

trace (numpy.ndarray) – The input trace signal.
fs (float) – The sampling rate of the trace signal.
fmin (float) – The minimum frequency of interest.
fmax (float) – The maximum frequency of interest.
nperseg (int) – The length of each segment for the spectrogram computation.
nhop (int) – The number of samples to advance between segments.
plotflag (bool, optional) – Whether to plot the spectrogram, defaults to False.

Returns:

spectrogram (numpy.ndarray) – The computed spectrogram.
ff (ndarray) – The frequency values of the spectrogram.
tt (ndarray) – The time values of the spectrogram.

Notes

This function computes the non-stationary spectrogram of a given trace signal. The spectrogram is computed using the Short-Time Fourier Transform (STFT) with a specified segment length and hop size. The resulting spectrogram is then sliced between the specified minimum and maximum frequencies of interest.

Examples

>>> trace = np.random.randn(1000)
>>> fs = 1000
>>> fmin = 10
>>> fmax = 100
>>> nperseg = 256
>>> nhop = 128
>>> spectrogram, ff, tt = get_sliced_nspectrogram(trace, fs, fmin, fmax, nperseg, nhop, plotflag=True)

das4whales.detect.nxcorr2d(spectro, kernel)[source]¶

Calculate the normalized cross-correlation between a spectrogram and a kernel.

Parameters:

spectro (numpy.ndarray) – The spectrogram array.
kernel (numpy.ndarray) – The kernel array.

Returns:

The maximum correlation values along the time axis.

Return type:

numpy.ndarray

Notes

The normalized cross-correlation is calculated using scipy.signal.correlate2d. The correlation values are normalized by dividing by the standard deviation of the spectrogram and the kernel, multiplied by the number of columns in the spectrogram.

Examples

>>> spectro = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> kernel = np.array([[1, 0], [0, 1]])
>>> nxcorr2d(spectro, kernel)
array([0.        , 0.33333333, 0.66666667])

das4whales.detect.pick_times(corr_m, threshold, ipi_idx)[source]¶

Detects the peak times in a correlation matrix.

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold.

Parameters:

corr_m (ndarray) – The correlation matrix.
threshold (float) – The threshold value for peak detection. Defaults to 0.3.
ipi_idx (int) – The minimum inter-pulse interval in indexes.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.pick_times_env(corr_m, threshold)[source]¶

Detects the peak times in a correlation matrix. Parallelized version : pick_times_par

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold.

Parameters:

corr_m (ndarray) – The correlation matrix.
threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.pick_times_par(corr_m, threshold)[source]¶

Detects the peak times in a correlation matrix using parallel processing.

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold using parallel processing.

Parameters:

corr_m (ndarray) – The correlation matrix.
threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.process_corr(corr, threshold)[source]¶

Detects the peak times in a correlation serie, kernel for parallelization.

This function takes a correlation serie, computes the Hilbert transform of the correlation, and detects the peak times based on a given threshold.

Parameters:

corr (ndarray) – The correlogram array.
threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

The peak indexes for the given correlation.

Return type:

ndarray

das4whales.detect.resolve_hf_lf_crosstalk(input_peaks, comp_peaks, input_SNR, comp_SNR, dt_tol, dx_tol)[source]¶

Sort peaks that are at the same distance and time but keep the one with higher SNR to differentiate between HF and LF peaks.

Parameters:

input_peaks (ndarray) – Array of shape (2, n_peaks) containing [distance_indices, time_indices] of the input peaks.
comp_peaks (ndarray) – Array of shape (2, n_peaks) containing [distance_indices, time_indices] of the comparison peaks.
input_SNR (ndarray) – Array of shape (n_peaks_input) containing the SNR values for the input peaks
comp_SNR (ndarray) – Array of shape (n_peaks_comp) containing the SNR values for the comparison peaks
dt_tol (int) – Tolerance in time index to consider peaks as matching.
dx_tol (int) – Tolerance in distance index to consider peaks as matching.

das4whales.detect.select_picked_times(idx_tp, tstart, tend, fs)[source]¶

Select the picked times within a given time range.

Parameters:

idx_tp (numpy.ndarray) – The time and spatial indexes of the picked times.
tstart (float) – The starting time of the time range [s].
tend (float) – The ending time of the time range [s].
fs (float) – The sampling rate of the data.

Returns:

The selected picked times within the given time range (time index, spatial index).

Return type:

numpy.ndarray

das4whales.detect.shift_nxcorr(x, y)[source]¶

Compute the shifted (positive lags only) normalized cross-correlation with standard deviation normalization.

Parameters:

x (ndarray) – first input signal.
y (ndarray) – second input signal

Returns:

The normalized cross-correlation between the two signals

Return type:

ndarray

das4whales.detect.shift_xcorr(x, y)[source]¶

compute the shifted (positive lags only) cross correlation between two 1D arrays

Parameters:

x (ndarray) – 1D array containing signal
y (ndarray) – 1D array containing signal

Returns:

1D array cross-correlation betweem x and y, only for positive lags

Return type:

ndarray

das4whales.detect.xcorr(t, f, Sxx, tvec, fvec, BlueKernel)[source]¶

Cross-correlate kernel with spectrogram

Parameters:

t (np.array) – Vector of times returned from plotwav
f (np.array) – Vector of frequencies returned from plotwav
Sxx (np.array) – 2-D array of spectrogram amplitudes
tvec (np.array) – Vector of times of kernel
fvec (np.array) – Vector of frequencies of kernel
BlueKernel (np.array) – 2-D array of kernel amplitudes

Returns:

t_scale (numpy.array) – Vector of correlation lags
CorrVal (numpy.array) – Vector of correlation values

das4whales.detect.xcorr2d(spectro, kernel)[source]¶

Calculate the 2D cross-correlation between a spectrogram and a kernel.

Parameters:

spectro (numpy.ndarray) – The input spectrogram array [frequency x time].
kernel (numpy.ndarray) – The kernel array used for cross-correlation [frequency x time].

Returns:

The resulting cross-correlation array.

Return type:

numpy.ndarray