maad.features.region_of_interest_index

maad.features.region_of_interest_index(Sxx_dB_noNoise, tn, fn, smooth_param1=1, mask_mode='relative', mask_param1=6, mask_param2=0.5, min_roi=9, max_roi=5120000, max_ratio_xy=None, remove_rain=False, display=False, **kwargs)[source]

Compute an acoustic activity index based on the regions of interested detected on a spectrogram.

The function first find regions of interest (ROI) and then compute the number or ROIs and the cover area of these ROIS on the spectrogram.

Parameters:

Sxx_dB_noNoisendarray of floats: Spectrogram without noise (i.e matrix of spectrum)
tn1d ndarray of floats: time vector (horizontal x-axis)
fn1d ndarray of floats: Frequency vector (vertical y-axis)
smooth_param1scalar, default is 1: Standard deviation of the gaussian kernel used to smooth the image The larger is the number, the smoother will be the image and the longer it takes. Standard values should fall between 0.5 to 3
mask_modestring in {‘relative’, ‘absolute’}, optional, default is ‘relative’: if ‘relative’: Binarize an image based on a double relative threshold. The values used for the thresholding depends on the values found in the image. => relative threshold

if ‘absolute’ : Binarize an image based on a double relative threshold. The values used for the thresholding are independent of the values in the image => absolute threshold

Warning

The default mask_mode parameter is deprecated in version 1.3 and will be changed to absolute in version 1.4.
mask_param1scalar, default is 6: if ‘relative’ : bin_std

if ‘absolute’ : bin_h

Warning

The default mask_param1 parameter is deprecated in version 1.3 and will be changed to 10 in version 1.4.
mask_param2scalar, default is 0.5: if ‘relative’ : bin_per

if ‘absolute’ : bin_l

Warning

The default mask_param2 parameter is deprecated in version 1.3 and will be changed to 3 in 1.4.
min_roi, max_roiscalars, optional, default9, 512*10000: Define the minimum and the maximum area possible for a ROI. If None, the minimum ROI area is 1 pixel and the maximum ROI area is the area of the image .. warning:: The default min_roi and max_roi parameter is deprecated in version 1.3 and will be changed to None in 1.4.
max_ratio_xyscalar, optional, defaultNone: Define the maximum ratio between the vertical axis (y) and horizontal axis (x) that is allowed for a ROI. This is very convenient to remove vertical spikes (e.g. rain). 10 seems a reasonable value to remove most of spikes due to light to medium rainfall.
remove_rainboolean, default is False: If True, vertical frequency spikes due to rain are removed as possible by applying a morphological mathematical image processing : grey opening .. warning:: The remove_rain parameter is deprecated in version 1.3 and will be removed in 1.4. It’s better to use the max_ratio_yx parameter
displayboolean, default is false: plot graphs and spectrograms
/*/*kwargs optional. This parameter is used by plt.plot and savefig functions

Returns:

ROItotalfloat: Total number of ROIs found. The higher is the number of ROI, the higher is the acoustic abondance and/or richness expected
ROIcoverfloat: Percentage of spectrogram cover. The higher is the cover percentage, the higher is the acoustic richness expected.

Examples

>>> import maad 
>>> s, fs = maad.sound.load('../data/cold_forest_daylight.wav')
>>> Sxx_power,tn,fn,_ = maad.sound.spectrogram(s,fs)
>>> Sxx_noNoise= maad.sound.median_equalizer(Sxx_power) 
>>> Sxx_dB_noNoise = maad.util.power2dB(Sxx_noNoise)
>>> ROItotal, ROIcover = maad.features.region_of_interest_index(Sxx_dB_noNoise, tn, fn, display=True)
>>> print('The total number of ROIs found in the spectrogram is %2.0f' %ROItotal) 
The total number of ROIs found in the spectrogram is 265
>>> print('The percentage of spectrogram covered by ROIs is %2.0f%%' %ROIcover) 
The percentage of spectrogram covered by ROIs is 12%