wingbeats.processing package

Submodules

wingbeats.processing.postprocessing module

Library for postprocessing functions

wingbeats.processing.postprocessing.autolabel(rects, coords=(0, 0), label_size=15)[source]

Attach a text label above each bar in rects, displaying its height.

Parameters

  • rects (matplotlib object) – Bars from barplot.

  • coords (tuple) – Label coordinates. Defaults to (0, 0).

  • label_size (int) – Size of the labels above the bars. Defaults to 15.

wingbeats.processing.postprocessing.compute_mean_conf_mat(conf_mats)[source]

Compute means and standard deviations itemwise for a list of (confusion) matrices.

Parameters

conf_mats (list) – Matrices to compute the statistics on.

Returns

Mean and standard deviation matrices (rounded to 0.001).

Return type

tuple

wingbeats.processing.postprocessing.mean_plot(X, title='Mean amplitudes', figsize=None, path_to_save=None)[source]

Plot mean amplitudes of signals in X.

Parameters

  • X (list or array) – Matrix of signals.

  • title (str) – Title of the plot. Defaults to ‘Mean amplitudes’.

  • figsize (tuple, optional) – Figure size. Defaults to None.

  • path_to_save (str, optional) – Location for saving the plot as a png. Defaults to None.

Returns

Array of mean amplitudes

wingbeats.processing.postprocessing.plot_accuracy(history, title='Accuracy', figsize=None, fontsize=15, show=True, path_to_save=None)[source]

Plot training and validation accuracy curves.

Parameters

  • history (dict) – Dictionary of training statistics.

  • title (str) – Title of the plot. Defaults to ‘Accuracy’.

  • figsize (tuple, optional) – Figure size. Defaults to None.

  • fontsize (int) – Fontsize in legend. Defaults to 15.

  • show (bool) – Whether to show the plot. Defaults to True.

  • path_to_save (str, optional) – Location for saving the plot as a png. Defaults to None.

wingbeats.processing.postprocessing.plot_all_transforms(sig, fs, cutoff, nperseg, noverlap, title_size=32, num_rows=1, row_ind=0)[source]

Plot a raw signal along with its FFT, PSD and spectrogram.

Parameters

  • sig (list or array) – Raw signal.

  • fs (int) – Sampling frequency.

  • cutoff (int) – Number of frequencies to keep in FFT, PSD and spectrograms.

  • nperseg (int) – Length of a segment to apply the Welch Transform to.

  • noverlap (int) – Lenth of overlapping region between segments.

  • title_size (int) – Size of the plot titles. Defaults to 32.

  • num_rows (int) – Number of rows (in case multiple signals are plotted). Defaults to 1.

  • row_ind (int) – Index of current row (in case multiple signals are plotted). Defaults to 0.

wingbeats.processing.postprocessing.plot_confusion(y_true, y_pred, title='Confusion matrix', axis_labels=None, hide_diag=False, path_to_save=None)[source]

Compute and plot confusion matrix.

Parameters

  • y_true (list or array) – True labels.

  • y_pred (list or array) – Predicted labels.

  • title (str) – Plot title. Defaults to ‘Confusion matrix’.

  • axis_labels (str, optional) – X and y labels. Defaults to None.

  • hide_diag (bool) – Whether to mask the diagonal entries. Defaults to False.

  • path_to_save (str, optional) – Location for saving the plot as a png. Defaults to None.

wingbeats.processing.postprocessing.plot_heatmap(mat, xticklab, yticklab, xlab='x', ylab='y', title='Heat map', mask=None, path_to_save=None, title_size=15, ticks_size=15, label_size=15, item_size=15, cbar=False)[source]

Plot matrix as a heat map.

Parameters

  • mat (array) – Matrix to plot.

  • xticklab (str) – X ticks labels.

  • yticklab (str) – Y ticks labels.

  • xlab (str) – X label. Defaults to ‘x’.

  • ylab (str) – Y label. Defaults to ‘y’.

  • title (str) – Plot title. Defaults to ‘Heat map’.

  • mask (array, optional) – Matrix of 1’s and 0’s specifying which entries of the matrix to mask. Defaults to None.

  • path_to_save (str, optional) – Location for saving the plot as a png. Defaults to None.

  • title_size (int) – Size of the plot titles. Defaults to 15.

  • ticks_size (int) – Size of the axis ticks. Defaults to 15.

  • label_size (int) – Size of the axis labels. Defaults to 15.

  • item_size (int) – Size of each matrix entry. Defaults to 15.

wingbeats.processing.postprocessing.plot_roc(y_true, y_pred, labels, title='ROC', title_size=15, ticks_size=15, label_size=15)[source]

Plot multi-class ROC along with the individual AUC values.

Parameters

  • y_true (array) – True labels (needs to be a binarized vector).

  • y_pred (array.) – Predicted labels.

  • labels (list) – Names of classes.

  • title (str) – Plot title. Defaults to ‘ROC’.

  • title_size (int) – Size of the plot titles. Defaults to 15.

  • ticks_size (int) – Size of the axis ticks. Defaults to 15.

  • label_size (int) – Size of the axis labels. Defaults to 15.

wingbeats.processing.preprocessing module

Library for preprocessing functions

wingbeats.processing.preprocessing.add_noise(sig, label, snr=10)[source]

Add random noise to a signal sig from a tf.Dataset.

The label is not modified but requested by the mapping format of tf.Dataset.

Parameters

  • sig (ndarray or Tensor) – Signals to inject noise into.

  • label (int) – Signal label.

  • snr (float) – Signal to Noise Ratio (in dB). Defaults to 10.

Returns

Noisy signals and their labels.

Return type

tuple

wingbeats.processing.preprocessing.add_noise_to_list(sig, snr=10)[source]

Add random noise to a signal sig callable as a list..

Parameters

  • sig (list) – Signals to inject noise into.

  • snr (float) – Signal to Noise Ratio (in dB). Defaults to 10.

Returns

Noisy signal.

Return type

list

wingbeats.processing.preprocessing.convert_to_fourier(X)[source]

Convert a matrix X of raw amplitudes into a 3d tensor of complex Fourier coefficients.

Each row of n amplitude values will be mapped to 2 new neighbouring rows of n/2 Fourier coefficients (real part on the 1st row, imaginary part on the 2nd row). The matrix grows into a two-slice tensor (all real parts on the 1st slice, all imaginary parts on the 2nd). Note that for real valued signals, the Fourier coeffiecients are symmetric (real part even, imaginary part odd).

Parameters

X (list or array) – Matrix of signals.

wingbeats.processing.preprocessing.convert_to_psd(X, fs, window, nperseg, noverlap, cutoff=None)[source]

Convert a matrix of raw amplitudes into a matrix of PSD values through the Welch-Transform.

Parameters

  • X (list or array) – Matrix of raw signals.

  • fs (int) – Sampling frequency.

  • window (str) – Window-function to multiply each segment with i.e. ‘hann’.

  • nperseg (int) – Length of a segment.

  • noverlap (int) – Lenth of overlapping region between segments.

  • cutoff (int, optional) – How many PSD frequencies should be kept. Defaults to None.

wingbeats.processing.preprocessing.convert_to_spectro(sig, labels, fft_length, frame_step, window=<function hann_window>, cutoff=None)[source]

Generate spectrograms out of raw signals (converted into tf.Dataset) through Short Time Fourier Transform.

Parameters

  • sig (Tensor) – Batch of signals to be transformed into spectrograms.

  • labels (list) – Labels of the signals.

  • fft_length (int) – Length of the frames to be Fourier transformed.

  • frame_step (int) – Hopping length between frames.

  • window (function pointer) – Window-function to multiply each segment with. Defaults to tf.signal.hann_window.

  • cutoff (int, optional) – How many frequencies should be kept. Defaults to None.

Returns

Spectrograms with labels

Return type

tuple

wingbeats.processing.preprocessing.convert_to_tf_dataset(X, y, model_name)[source]

Convert dataset (X, y) to tf.Dataset according to model architecture.

Parameters

  • X (ndarray) – Matrix of signals.

  • y (ndarray) – Label vector.

  • model_name (str) – Name of model architecture. Currently allowed: SimpleCls, Emb, SimpleEmbCls, HieraCls, HieraEmbCls.

Returns

Tensorflow dataset

wingbeats.processing.preprocessing.convert_to_wavelet(sig, labels, wavelet=<function ricker>, hop_length=50, n_scales=64, scales_step=2)[source]

Compute the discrete/continuous wavelet transform from raw signals (converted into tf.Dataset).

Parameters

  • sig (Tensor) – Batch of signals to be transformed into spectrograms.

  • labels (list) – Labels of the signals.

  • wavelet (function pointer) – Function to apply wavelet transform. Defaults to ricker (‘mexican hat’).

  • hop_length (int, optional) – Step for moving wavelet window (if 1, all WT coefficients are returned). Defaults to 50.

  • n_scales (int, optional) – Number of wavelet scales to compute (usually 16, 32, 64, 128). Defaults to 64.

  • scales_step (int, optional) – Step to pick computed scales (if 1, all n_scales scales are returned). Defaults to 2.

Returns

Wavelet signals and labels.

Return type

tuple

wingbeats.processing.preprocessing.create_model_folders(models_path)[source]

Create folder structure for each model architecture and each input format.

Example: The folder models has the subfolder Hierarchical Classifier, which in turn has two subfolders psd and spectro, each with subfolders histories and logs.

Parameters

models_path (str) – Path with model folders.

wingbeats.processing.preprocessing.cut_off_rms(X, min_len, nperseg, hop_len)[source]

Cut off signals so that part of the uninteresting amplitudes are discarded.

The RMS is computed within multiple frames (nperseg long) of signals in X, overlapping each other by nperseg - hop_len. The signal is cut around the frame with the greatest RMS, so that it gets shortened to length min_len.

Parameters

  • X (array or list) – Matrix of signals.

  • min_len (int) – length of the cropped signal.

  • nperseg (int) – Length of the frame for which to compute the RMS.

  • hop_len (int) – Step size from frame to frame.

wingbeats.processing.preprocessing.get_uniform_random_samples(X, y, sample_size, indexes, return_numpy=True)[source]

Build uniform random samples from matrix X and label vector y.

Parameter indices defines the subintervalls from which the samples are selected:

  • indexes = [ind_0, ind_1, ind_2, …, ind_n]

  • subsample_1 will be selected from X by the half closed index subintervall [ind_0, ind_1) …

  • subsample_n will be selected from X by the half closed index subintervall [ind_{n-1}, ind_n)

Each class is equally represented, if indexes are selected accordingly. Note that the signals in X should be ordered according to their class.

Parameters

  • X (ndarray) – Matrix of signals.

  • y (ndarray) – Label vector.

  • sample_size (int) – Size of samples from each class.

  • indexes (list) – List of starting indexes for each class. Final index gives the length of the dataset.

  • return_numpy (bool) – Whether to return the sampled signals and labels as a Numpy array. Otherwise as list. Defaults to True.

Returns

Sampled signals and labels.

Return type

tuple

wingbeats.processing.preprocessing.load_signals(load_path, species, X, y, genus_mapping=None, with_scipy=True)[source]

Load wav signals from load_path into matrix X.

The subfolder structure in load_path should follow species. A vector of species labels is also created at the same time; if genus_mapping is provided, such that genus_mapping[i] gives the genus index of the i-th species, then y will also store the genus index as a separate column. You can also choose whether to load the signals with scipy.io.wavfile.read or with librosa.load. Beware that the latter converts the signal to float automatically by mapping it into [-1, 1]. The same can be achieved with scipy by dividing by np.iinfo(np.int16).

Parameters

  • load_path (str) – Path to load the wav files from.

  • species (list) – List with species names as strings.

  • X (list) – Empty list to append the signals to.

  • y (list) – Empty list to append the labels to.

  • genus_mapping (list, optional) – List containing genus indexes ef every species. Defaults to None.

  • with_scipy (bool, optional) – Boolean to control whether to load the signals using the scipy library or librosa. Defaults to True.

Returns

List of species lengths.

wingbeats.processing.preprocessing.low_pass(sig, fs, cutoff, threshold, window='hann')[source]

Custom low pass filter.

Amplitudes of frequencies after cutoff (Hz) are reduced to threshold if greater than threshold. Signal sig can be first multiplied with a window function. Sampling rate fs is needed in order to convert cutoff from Hz to array index of the amplitude spectrum.

Parameters

  • sig (list or array) – Raw signal.

  • fs (int) – Frequency sample.

  • cutoff (flloat) – Minimal frequency (Hz) to consider for filtering.

  • threshold (float) – Maximal allowed amplitude value for frequencies higher than cutoff Hz.

  • window (str, optional) – Window-function to multiply the signal with, before applying FFT. Defaults to ‘hann’.

Returns

Filtered signal.

wingbeats.processing.preprocessing.preprocess_dataset(X, y, model_name, input_format, sampling_rate=16000, batch_size=64, window=None, nperseg=None, noverlap=None, cutoff=None, shuffle=False, prefetch=True, cache=True, drop_uneven_batch=False)[source]

Apply preprocessing steps to signal matrix X such as conversion to PSD/Spectrogram, conversion to tf.Dataset, expand dimensions, shuffle, split into batches and integrate prefetching.

Parameters

  • X (ndarray) – Matrix of signals.

  • y (ndarray) – Label vector.

  • model_name (str) – Name of model architecture. Currently allowed: SimpleCls, Emb, SimpleEmbCls, HieraCls, HieraEmbCls.

  • input_format – Type of input signal. Currently allowed: raw, psd, spectro.

  • sampling_rate (int) – Sampling frequency. Defaults to 16 kHz.

  • batch_size (int) – Size of batches to split the dataset into. Defaults to 64.

  • window (str (for psd) or function pointer (for spectrograms)) – Window-function to multiply each segment with i.e. ‘hann’ (for psd) or tf.signal.hann_window (for spectrograms). Defaults to None.

  • nperseg (int) – Length of a segment for applying the Welch-Transform or STFT. Defaults to None.

  • noverlap (int) – Lenth of overlapping region between segments. Defaults to None.

  • cutoff (int, optional) – How many PSD frequencies should be kept. Defaults to None.

  • shuffle (bool) – Whether to shuffle the signals in the dataset. Note that you need to shuffle the training set before splitting it into batches. Defaults to False.

  • prefetch (bool) – Whether to integrate prefetching strategy into the dataset. Note that batching and caching are only applied, if prefectch is True. Defaults to True.

  • cache (bool) – Whether to cache the dataset so that it is read only once before training. Make sure that there is enough memory. Defaults to True.

  • drop_uneven_batch (bool) – Whether to drop the final natch if it is smaller than the rest. Defaults to False.

Returns

Processed Tensorflow dataset

wingbeats.processing.preprocessing.rms_frame(frame)[source]

Compute the Root Mean Square value of the amplitudes within frame.

Parameters

frame (array) – Portion of the signal for which to compute RMS.

Returns

RMS

wingbeats.processing.preprocessing.shift_data(signals, labels, shift_axis, shift_max, shift_min=0)[source]

Shift signals along time axis.

Every row in the batch signals is randomly shifted to the right or left by a random amount between shift_min and shift_max % of the original length of the signal. The whole batch is shifted by the same amount. The labels are not modified, but are requested by the mapping format of tf.Dataset. Note: When inputing single signals, choose shift_axis = 0; in case of 2D batches, choose shift_axis = 1.

Parameters

  • signals (array) – Batch of signals to shift in time.

  • labels (list) – Signal labels.

  • shift_axis (int) – Axis along which the signals are shifted.

  • shift_max (float) – Maximal shifting percent.

  • shift_min (float, optional) – Minimal shifting percent. Defaults to 0.

Returns

Shifted signals and labels.

Return type

tuple

wingbeats.processing.preprocessing.unitsphere_embedding(class_sim)[source]

Find an embedding of n classes on a unit sphere in n-dimensional space, so that their dot products correspond to the pre-defined similarities in class_sim.

Code taken from https://github.com/cvjena/semantic-embeddings/blob/master/compute_class_embedding.py

Parameters

class_sim (array) – A n-by-n matrix specifying the desired similarity between each pair of classes.

Returns

A n-by-n matrix with rows being the locations of the corresponding classes in the embedding space.

Module contents