Utilities

The module utils has a handful of useful set of tools used in the audio analysis framework.

Visualization

rand_cmap(nlabels[, type, ...])	Creates a random colormap to be used together with matplotlib.
crop_image(im, tn, fn[, fcrop, tcrop])	Crop a spectrogram (or an image) in time (horizontal X axis) and frequency (vertical y axis)
save_figlist(fname, figlist)	Save a list of figures or spectrograms to disk.
plot1d(x, y[, ax])	Plot the waveform or spectrum of an audio signal.
plot_wave(s, fs[, tlims, ax])	Plot audio waveform.
plot_spectrum(pxx, f_idx[, ax, flims, ...])	Plot power spectral density estimate (PSD).
plot2d(im[, ax, colorbar])	Display the spectrogram of an audio signal.
plot_spectrogram(Sxx, extent[, db_range, ...])	Plot spectrogram represenation.
overlay_rois(im_ref, rois[, edge_color, ...])	Display bounding boxes with time-frequency regions of interest over a spectrogram.
overlay_centroid(im_ref, centroid[, savefig])	Overlay centroids on the original spectrogram
plot_features_map(df[, norm, mode])	Plot features values on a heatmap.
plot_features(df[, ax, norm, mode])	Plot the variation of features values (ie.
heatmap_by_date_and_time(dataframe, disp_column)	Plot a heatmap of a features by time (x-axis) and date (y-axis).
plot_correlation_map(df[, R_threshold, method])	Plot the correlation map between indices in the DataFrame obtained with maad.
plot_shape(shape, params[, row, ax, ...])	Plot shape features in a bidimensional plot.
false_Color_Spectro(df[, indices, plim, ...])	Create False Color Spectrogram from indices obtained by MAAD.

Mathematical

running_mean(x, N[, mode])	Compute fast running mean for a window size N.
get_unimode(X[, mode, axis, N, N_bins, verbose])	Get the statistical mode or modal value which is the most common number in the dataset.
entropy(x[, axis])	Compute the entropy of a vector (waveform) or matrix (spectrogram).
rms(s)	Compute the root-mean-square (RMS) level of an input signal.
kurtosis(x[, axis])	Compute the kurtosis (tailedness or curved or arching) of an audio signal.
skewness(x[, axis])	Compute the skewness (asymetry) of an audio signal.
moments(X[, axis])	Computes the first 4th moments of a vector (1d, ie.

Parser

read_audacity_annot(audacity_filename)	Read Audacity annotations file (or labeling file) and return a Pandas Dataframe with the bounding box and the label of each region of interest (ROI).
write_audacity_annot(fname, df_rois[, save_file])	Write audio segmentation to text file in Audacity format, a file that can be imported and modified with Audacity.
read_raven_annot(raven_filename)	Read Raven annotations file (or labeling file) and return a Pandas Dataframe with the bounding box and the label of each region of interest (ROI).
write_raven_annot(fname, df_rois[, save_file])	Write audio segmentation to text file in Raven format, a file that can be imported and modified with Raven.
date_parser(datadir[, dateformat, ...])	Extracts dates from filenames in a given folder and subfolders.

Miscellaneous

index_bw(fn, bw)	Select all the index coresponding to a selected frequency band.
into_bins(x, an, bin_step[, axis, bin_min, ...])	Divide a vector (1D) or a matrix (2D) into multiple bins according to a bin_step with respect of the energy
shift_bit_length(x)	Find the closest power of 2 that is superior or equal to the number x.
rle(x)	Compute the Run-Length encoding (RLE) of a vector.
linear_scale(x[, minval, maxval, axis])	Scale the values of a vector or matrix from a user specified minimum to a user specified maximum.
amplitude2dB(x[, db_range, db_gain])	Transform amplitude data (signal, scalar) into decibel scale within the dB range (db_range).
power2dB(x[, db_range, db_gain])	Transform power (amplitude²) signal or scalar into decibel scale within the dB range (db_range).
dB2amplitude(x[, db_gain])	Transform data in dB scale into amplitude A gain (db_gain) could be added at the end.
dB2power(x[, db_gain])	Transform data in dB scale into power (amplitude²) A gain (db_gain) could be added at the end.
mean_dB(*argv[, axis])	Compute the average of decibel values.
add_dB(*argv[, axis])	Computes an addition on decibel values.
nearest_idx(array, value)	Find nearest value on array and return its index.
get_df_single_row(df, index[, mode])	Extract a single row from a dataframe keeping the DataFrame type (instead of becoming a Series).
format_features(df, tn, fn)	Format features such as bounding box coordinates and centroids coordinates to predifined format : time-frequency to pixels or pixels to time-frequency units.
crossfade(s1, s2, fs[, fade_len])	Add a smooth transition (cross-fade) between two audio signals.
crossfade_list(s_list, fs[, fade_len])	Apply a cross-fade to a list of audio signals.

Xeno-Canto

xc_query(searchTerms[, max_nb_files, ...])	Query metadata from Xeno-Canto website depending on the search terms.
xc_multi_query(df_query[, max_nb_files, ...])	Multi_query performs multiple queries following the search terms defined in the input dataframe
xc_selection(df_dataset[, max_nb_files, ...])	Select a maximum number of recordings depending on their quality and duration in order to create an homogeneous dataset.
xc_download(df, rootdir[, dataset_name, ...])	Download the audio files from Xeno-Canto based on the input dataframe It will create directories for each species if needed

Audio metadata

check_file_format(path_audio)	Check Wave file consistency.
audio_header(path_audio)	Get audio header information from WAVE file.
filename_info(path_audio[, verbose])	Get information from filename when using standard format.
get_metadata_file(path_audio[, verbose])	Get metadata asociated with audio recordings in audio file.
get_metadata_dir(path_dir[, verbose])	Get metadata asociated with audio recordings in a directory.