Plotting

This module contains functions for generating and plotting spectrograms.

avn.plotting module

Created on Tue May 4 13:39:10 2021

@author: Therese

class avn.plotting.Utils

Bases: object

Containts plotting utilities.

plot_syll_examples(syll_label, song_folder_path, n_examples=1, random_seed=2021, padding=0.25, figsize=(5, 5))

Plots n_examples examples of syllables with label syll_label from syll_df.

Parameters

  • syll_df (Pandas DataFrame) – pandas dataframe containing one row for every syllable to be analyzed from the subject bird. It must contain columns onsets and offsets which contain the timestamp in seconds at which the syllable occurs within a file, files which contains the name of the .wav file in which the syllable is found, and labels which contains a categorical label for the syllable type. These can be generated through manual song annotation, or automated labeling methods.

  • syll_label (int, float or string) – Syllable label class in syll_df.labels to plot.

  • song_folder_path (string) – Path to folder containing a subfolder called Bird_ID, which contains .wav files of songs in syll_df. Should end with ‘/’.

  • n_examples (int, optional) – The number of random examples of syllable syll_label to plot. The default value is 1.

  • random_seed (int, optional) – Specifies the random state for selecting example syllables. The default value is 2021.

  • padding (float, optional) – The amount of time in seconds before and after syllable onset and offset which should be included in the spectrogram plot. The default value is 0.25.

  • figsize (tuple, optional) – Tuple specifying the dimensions of the figure(s) to be plotted. The default value is (5,5)

avn.plotting.make_spectrogram(song)

Generates spectrogram information for plotting

Parameters

song (avn.dataloading.SongFile object) – SongFile object corresponding to the file to be plotted

Returns

spectrogram_db – Array containing spectrogram data for plotting.

Return type

numpy ndarray, 2D

avn.plotting.plot_spectrogram(spectrogram, sample_rate, ax=None, figsize=(20, 5))

Plots a spectrogram of a song.

Parameters

  • spectrogram (numpy ndarray, 2D) – Array containing spectrogram data.

  • sample_rate (int) – Sample rate of audio. Necessary to determine time along the x-axis.

  • ax (matplotlob.axes._subplots.AxesSubplot object) – Axis object must be specified if you want to plot the spectrogram as a subplot within a matplotlib.pyplot figure with other subplots as well. If plotting a spectrogram alone, ax doesn’t need to be specified.

  • figsize (tuple of floats, optional) – Specifies the dimensions of the output plot. The default is (20, 5).

Returns

Return type

None.

avn.plotting.plot_spectrogram_with_labels(syll_df, song_folder_path, Bird_ID, song_file=None, song_file_index=None, figsize=(80, 10), cmap='tab20', add_legend=True, fontsize=24)

Plots the sectrogram of a specified file with syllable labels indicated through colored bars overlaid on spectrogram.

Parameters

  • syll_df (Pandas DataFrame) – pandas dataframe containing one row for every syllable to be analyzed from the subject bird. It must contain columns onsets and offsets which contain the timestamp in seconds at which the syllable occurs within a file, files which contains the name of the .wav file in which the syllable is found, and labels which contains a categorical label for the syllable type. These can be generated through manual song annotation, or automated labeling methods.

  • song_folder_path (string) – Path to folder containing a subfolder called Bird_ID, which contains .wav files of songs in syll_df. Should end with ‘/’.

  • Bird_ID (string) – String containing a unique identifier for the subject bird.

  • song_file (string, optional) – A value must be provided for song_file OR song_file_index, but not both. String containing the name of a .wav file in syll_df and song_folder_path/Bird_ID/ to be plotted.

  • song_file_index (int >= 0, optional) – A value must be provided for song_file or song_file_index, but not both. Denotes the index of the unique file in syll_df.files.unique() to be plotted.

  • figsize (tuple, optional) – Dimensions of figure to be plotted. The default is (80, 10).

  • cmap (matplotlib colormap, optional) – matplotlib color map for syllable labels. The colormap must contain more unique shades than syllable label types. The default value is ‘tab20’.

  • add_legend (boolean, optional) – If True, a legend mapping syllable labels to colors will be plotted over the spectrogram. If False, no legend will be plotted. The default is True.

  • fontsize (float, optional) – The size of the font for the legend. The default is 24.

Returns

Return type

None

avn.plotting.plot_syll(song, onset, offset, padding=0, figsize=(5, 5), title=None)

Plots the spectrogram of a portion of a song spectrogram (generally a single syllable).

Parameters

  • song (avn.dataloading.SongFile type object) – Instance of an avn.SongFile object with .data, .sample_rate and .duration attributes.

  • onset (float) – Start time in seconds of syllable to plot from song.

  • offset (float) – End time in seconds of syllable to plot from song.

  • padding (float, optional) – Time in seconds to pad before and after onset and offset times for plotting. The default value is 0.

  • figsize (tuple, optional) – Dimensions of the figure to plot. The default is (5,5)

  • title (string, optional) – Title of the figure to plot. The default is None.

Returns

Return type

None

avn.plotting.plot_syntax_raster(syntax_data, syntax_raster_df, figsize=(10, 10), title=None, palette='husl')

Plots a syntax_raster_df dataframe.

Parameters

  • syntax_data (avn.syntax.SyntaxData object) – An instance of avn.syntax.SyntaxData on which .make_synta_raster() was called to generate syntax_raster_df.

  • syntax_raster_df (Pandas DataFrame) – Dataframe where each row reflects a song bout (a sequence of syllables flanked by file boundaries or long silent gaps), and each cell contains the label of the song syllable produced at that index in the song bout, based on syntax_data.syll_df.labels. This is returned by .make_syntax_raster() called on an instance of a syntax.SyntaxData object.

  • figsize (tuple, optional) – Tuple specifying dimensions of output figure. The default is (10, 10)

  • title (String, optional) – Title of the output figure. The default is None, which will result in a figure without a title.

  • palette (string or sequence, optional) – String corresponding to the name of a seaborn palette, matplotlib colormap or sequence of colors in any format matplotlib accepts. See seaborn.color_palette() documentation for more information. The default is ‘husl’.

Returns

Return type

None