maad.features.region_of_interest_index

maad.features.region_of_interest_index(Sxx_power, tn, fn, seed_level=13, low_level=6, fusion_rois=None, remove_rois_flim_min=50, remove_rois_flim_max=None, remove_rain=True, min_event_duration=0.025, max_event_duration=None, min_freq_bw=50, max_freq_bw=None, max_ratio_xy=10, display=False, verbose=False, **kwargs)

Compute acoustic activity indices based on the regions of interest 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_powerndarray of floats

Power spectrogram (i.e matrix of spectrum)

tn1d ndarray of floats

time vector (horizontal x-axis)

fn1d ndarray of floats

Frequency vector (vertical y-axis)

seed_levelscalar, default is 13

Higher threshold (in dB) for the absolute binarization. Pixels with values above this threshold are considered part of a potential ROI.

low_levelscalar, default is 6

Lower threshold (in dB) for the absolute binarization. Pixels with values above this threshold and connected to a “seed” pixel are also considered part of a potential ROI.

fusion_roistuple of scalars, default is (0.05, 100)

Tuple defining the temporal (in seconds) and frequency (in Hz) dimensions for morphological closing. This operation fuses nearby ROIs.

remove_rois_flim_minscalar or tuple of scalars, default is 50

Frequency limit (in Hz) below which ROIs are removed. Can be a single value or a tuple defining a range (min_freq, max_freq).

remove_rois_flim_maxscalar, default is none

Frequency limit (in Hz) above which ROIs are removed.

remove_rainboolean, default is True

If True, vertical frequency spikes due to rain are removed as possible by applying a morphological mathematical image processing : grey opening

min_event_durationscalar, optional

Minimum time duration of an event (in s). ROIs shorter than this are removed.

max_event_durationscalar, optional

Maximum time duration of an event (in s). ROIs longer than this are removed.

min_freq_bwscalar, optional

Minimum frequency bandwidth (in Hz). ROIs with smaller bandwidth than this are removed.

max_freq_bwscalar, optional

Maximum frequency bandwidth (in Hz). ROIs with larger bandwidth than this are removed.

max_ratio_xyscalar, optional

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.

displayboolean, default is False

If True, plot graphs and spectrograms.

verboseboolean, default is False

If True, print additional information during processing.

**kwargsoptional

This parameter is used by plt.plot and savefig functions.

Returns:

nROIfloat

Total number of ROIs found per minute. The higher is the number of ROI, the higher is the acoustic abondance and/or richness expected

aROIfloat

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)
>>> nROI, aROI = maad.features.region_of_interest_index(Sxx_power, tn, fn, display=True)
>>> print('The total number of ROIs found in the spectrogram is %2.0f' % nROI)
The total number of ROIs found in the spectrogram is 241
>>> print('The percentage of spectrogram covered by ROIs is%2.0f%%' % aROI)
The percentage of spectrogram covered by ROIs is 5%