maad.features.shape_features

maad.features.shape_features(Sxx, resolution='low', rois=None)[source]

Computes time-frequency shape coefficients at multiple resolutions using 2D Gabor filters.

Parameters:

Sxx: 2D array: Input image to process
resolution: str or dict: Specify resolution of shape descriptors. Can be: ‘low’, ‘med’, ‘high’. Default is ‘low’. Alternatively, custom resolution can be provided using a dictionary with options to define the filter bank. Valid keys are: ntheta, bandwidth, frequency, gamma, npyr.
rois: pandas DataFrame: Regions of interest where descriptors will be computed. Array must have a valid input format with column names: min_t min_f, max_t, max_f. Use format_features(rois,tn,fn) before using shape_features to be sure that the format of the rois DataFrame is correct.

Returns:

shape: pandas DataFrame: Shape coefficient for each region of interest
params: 2D numpy structured array: Corresponding parameters of the 2D fileters used to compute the shape coefficients. Params has 4 fields (theta, freq, pyr_level, scale)

See also

maad.features.opt_shape_presets, maad.features.filter_bank_2d_nodc, maad.util.plot_shape

References

[1]

Ulloa, J. S., Aubin, T., Llusia, D., Bouveyron, C., & Sueur, J. (2018). Estimating animal acoustic diversity in tropical environments using unsupervised multiresolution analysis. Ecological Indicators, 90, 346–355. DOI: 10.1016/j.ecolind.2018.03.026

[2]

Sifre, L., & Mallat, S. (2013). Rotation, scaling and deformation invariant scattering for texture discrimination. Computer Vision and Pattern Recognition (CVPR), 2013 IEEE Conference On, 1233–1240. DOI: 10.1109/CVPR.2013.163

[3]

Mallat, S. (2008). A Wavelet Tour of Signal Processing: The Sparse Way. Academic Press. DOI: 10.1016/B978-0-12-374370-1.X0001-8

Examples

Get shape features from the whole power spectrogram

>>> from maad.sound import load, spectrogram 
>>> from maad.features import shape_features
>>> from maad.util import format_features, power2dB, plot_shape 
>>> s, fs = load('../data/spinetail.wav')
>>> Sxx, tn, fn, ext = spectrogram(s, fs, db_range=100, display=True) 
>>> Sxx_db = power2dB(Sxx, db_range=100)
>>> shape, params = shape_features(Sxx_db, resolution='med') 
>>> ax = plot_shape(shape.mean(), params) 

Or get shape features from specific regions of interest

>>> from maad.util import read_audacity_annot
>>> rois = read_audacity_annot('../data/spinetail.txt') 
>>> rois = format_features(rois, tn, fn) 
>>> shape, params = shape_features(Sxx_db, resolution='med', rois=rois)

The shape coefficient can be visualized using plot_shape. Note that these coefficient allow to disciminate between the two vocalization types found in the audio file, the spinetail song and the background calls.

>>> shape_crer, shape_sp = shape.groupby('label')
>>> ax1 = plot_shape(shape_crer[1].filter(regex=r'^shp_').mean(), params) 
>>> ax1 = ax1.set_title('Spinetail song')
>>> ax2 = plot_shape(shape_sp[1].filter(regex=r'^shp_').mean(), params) 
>>> ax2 = ax2.set_title('Background call') 