maad.rois.template_matching
- maad.rois.template_matching(Sxx, Sxx_template, tn, ext, peak_th, peak_distance=None, display=False, **kwargs)[source]
Use normalized spectrogram cross-correlation to detect the occurrence of a template sound in a target audio.
The output is an array with values between -1.0 and 1.0. The value at a given position corresponds to the correlation coefficient between the spectrograms of the target audio and the template. The function also delivers the detection found as peaks and as regions of interest (rois).
- Parameters:
- Sxx2D array
Spectrogram of audio signal.
- Sxx_templateTYPE
Spectrogram of target sound.
- tn1d array
Time vector of target audio, which results from the maad.sound.spectrogram function.
- fn1d array
Frecuency vector of target audio, which results from the maad.sound.spectrogram function.
- extlist of scalars [left, right, bottom, top]
Extent keyword arguments controls the bounding box in data coordinates for the spectrogram of the target audio, which results from the maad.sound.spectrogram function.
- peak_thfloat, optional
Threshold applied to find peaks in the cross-correlation array. Should be a value between -1 and 1.
- peak_distancefloat, optional
Required minimal temporal distance (>= 0) in seconds between neighbouring peaks. If set to None, the minimum temporal resolution will be used. The minimal temporal resolution is given by the array tn and depends on the parameters used to compute the spectrogram.
- displayBoolean, optional
display the results of the template matching. The default is False.
- **kwargs: keywords pair, optional
Set aditional specificities to find peaks in xcorroelation array. Arguments are passed to the the function scipy.signal.find_peaks.
- Returns:
- xcorrcoef1D array
Correlation coefficients resulting from the cross-correlation between audio and target template.
- roispandas DataFrame
Detections found based on cross-correlation coefficients. The result is presented as a DataFrame where each row represent a detection, with the peak time (peak_time), peak amplitude (xcorrcoef), minimum and maximum time (min_t, max_t), and minimum and maximum frequency (min_f, max_f).