maad.util.overlay_rois

maad.util.overlay_rois(im_ref, rois, edge_color=None, unique_labels=None, textbox_label=False, savefig=None, **kwargs)

Display bounding boxes with time-frequency regions of interest over a spectrogram.

Regions of interest (ROIs) must be provided. They can be loaded as manual annotations or computed using automated methods (see the example section).

Parameters:

im_ref2d ndarray of scalars

Spectrogram (or image)

rois_bboxpandas.DataFrame

Contains the bounding box of each ROI. The pandas.DataFrame must have columns [‘min_x’, ‘max_x’, ‘min_y’, ‘max_y’]. If your data is in the time-frequency format [‘min_t’, ‘max_t’, ‘min_f’, ‘max_f’], use the function maad.util.format_features to get the cooresponding x, y coordinates.

edge_color{None, string, tuple, list of tuples}, default is None

Define the color of the bounding-box to display. if it’s a string, select a color name if it’s a tuple, give a tuple of floats [0,1] in the form (r,g,b,a), with r for red, g for green, b for blue and a for alpha (i.e transparency) for example - pure red : (1,0,0,0) - pure yellow : (1,1,0,0) - pure blue with transparency(0,0,1,0.5) if it’s a list, give a list of tuple or string. The number of element in the list should be equal to the number of elements in unique_labels. if it’s set to None, a random list of colors is used.

unique_labelslist, default is None

list of unique labels that could be either strings or numbers. When a list is given as argument, the number element in the list should be the same as the number of edge_color

textbox_label: bool

Display a text box above the bounding box indicating the name of the label. The rois_bbox pandas.DataFrame must have a column called ‘label’ with names assigned to each ROI.

savefigstring, optional, default is None

Root filename (with full path) is required to save the figures. Postfix is added to the root filename.

kwargs, optional. This parameter is used by plt.plot and savefig functions

• savefilenamestr, optional, default :’_spectro_overlayrois.png’

  Postfix of the figure filename

• extentlist of scalars [left, right, bottom, top], optional, default: None

  The location, in data-coordinates, of the lower-left and upper-right corners. If None, the image is positioned such that the pixel centers fall on zero-based (row, column) indices.

• titlestring, optional, default‘Spectrogram’

  title of the figure

• xlabelstring, optional, default‘Time [s]’

  label of the horizontal axis

• ylabelstring, optional, default‘Amplitude [AU]’

  label of the vertical axis

• cmapstring or Colormap object, optional, default is ‘gray’

  See https://matplotlib.org/examples/color/colormaps_reference.html in order to get all the existing colormaps examples: ‘hsv’, ‘hot’, ‘bone’, ‘tab20c’, ‘jet’, ‘seismic’, ‘viridis’…

• vmin, vmaxscalar, optional, default: None

  vmin and vmax are used in conjunction with norm to normalize luminance data. Note if you pass a norm instance, your settings for vmin and vmax will be ignored.

• dpiinteger, optional, default is 96

  Dot per inch. For printed version, choose high dpi (i.e. dpi=300) => slow For screen version, choose low dpi (i.e. dpi=96) => fast

• formatstring, optional, default is ‘png’

  Format to save the figure

… and more, see matplotlib

Returns:

axaxis object (see matplotlib)

figfigure object (see matplotlib)

Examples

Simple display of bounding boxes over the spectrogram.

>>> from maad import sound, util
>>> s, fs = sound.load('./data/spinetail.wav')
>>> rois = util.read_audacity_annot('./data/spinetail.txt')
>>> Sxx, tn, fn, ext = sound.spectrogram(s, fs, nperseg=512, noverlap=256)
>>> rois = util.format_features(rois, tn, fn)
>>> fig, ax = plt.subplots(figsize=(10,5))
>>> util.plot_spectrogram(Sxx,ext, db_range=70, ax=ax)
>>> util.overlay_rois(Sxx, rois, fig=fig, ax=ax, textbox_label=True)

Detect regions of interest and display them over the spectrogram. Load audio recording and compute the spectrogram.

>>> s, fs = maad.sound.load('../data/cold_forest_daylight.wav')
>>> Sxx,tn,fn,ext = maad.sound.spectrogram (s, fs, fcrop=(0,10000))   

Subtract the background noise before finding ROIs.

>>> Sxx_noNoise = maad.sound.median_equalizer(Sxx)

Convert linear spectrogram into dB and smooth.

>>> Sxx_noNoise_dB = maad.util.power2dB(Sxx_noNoise)         
>>> Sxx_noNoise_dB_blurred = maad.sound.smooth(Sxx_noNoise_dB)

Detection of the acoustic signature => creation of a mask

>>> im_bin = maad.rois.create_mask(Sxx_noNoise_dB_blurred, bin_std=6, bin_per=0.5, mode='relative') 

Select rois from the mask and display bounding box over the spectrogram without noise.

>>> import numpy as np
>>> im_rois, df_rois = maad.rois.select_rois(im_bin, min_roi=100)  
>>> maad.util.overlay_rois (Sxx_noNoise_dB, df_rois, extent=ext,vmin=np.median(Sxx_noNoise_dB), vmax=np.median(Sxx_noNoise_dB)+60)