pykanto.plot#

A collection of functions to plot spectrograms. annotations and other output.

Functions

build_plot_summary(dataset[, nbins, variable])

Plots a histogram + kernel densiyy estimate of the frequency distribution of vocalisation duration and frequencies.

melspectrogram(nparray_or_dir[, parameters, ...])

Plots a melspectrogram from a numpy array or path to a numpy array.

mspaced_mask(N, M)

Returns a mask of length N to select M indices as regularly spaced as possible.

rand_jitter(arr[, jitter])

Adds random jitter to an array.

segmentation(dataset[, key, spectrogram, ...])

Plots a vocalisation and overlays the results of the segmentation process.

show_minmax_frequency(dataset, minfreqs, ...)

Plots approximate minimum and maximum frequencies over a mel spectrogram.

show_spec_centroid_bandwidth(dataset, ...[, ...])

Plots spectral centroids and bandwiths over a mel spectrogram.

sns_histoplot(data[, nbins])

Plots a histogram using seaborn
pykanto.plot.sns_histoplot(data, nbins=100) → None[source]#

Plots a histogram using seaborn

pykanto.plot.melspectrogram(nparray_or_dir: Path | np.ndarray, parameters: None | Parameters = None, title: None | str = None, cmap: str = 'bone', max_lenght: None | float = None, colour_bar=True) → Axes[source]#

Plots a melspectrogram from a numpy array or path to a numpy array.

Parameters

  • nparray_or_dir (Path | np.ndarray) – Spectrogram array or path to a stored numpy array.

  • parameters (None | Parameters, optional) – Parameters used to calculate the spectrogram. Defaults to None.

  • title (None | str, optional) – Title for plot. Defaults to None.

  • cmap (str, optional) – Matplotlib colour palette to use. Defaults to “bone”.

  • max_lenght (None | float, optional) – Maximum length of the spectrogram beyond which it will be center-cropped for plotting. Defaults to None.

  • colour_bar (bool, optional) – Wheter to include a colour bar legend for the amplitude. Defaults to True.

Returns

A matplotlib.axes.Axes instance

Return type

Axes

pykanto.plot.segmentation(dataset: KantoData, key: str | None = None, spectrogram: bool | np.ndarray = False, onsets_offsets: bool | Tuple[np.ndarray, np.ndarray] = False, **kwargs) → None[source]#

Plots a vocalisation and overlays the results of the segmentation process.

Parameters

  • dataset (KantoData) – A KantoData object.

  • key (str, optional) – Vocalisation key. Defaults to None.

  • spectrogram (bool | np.ndarray, optional) – [description]. Defaults to False.

  • onsets_offsets (bool | Tuple[np.ndarray, np.ndarray], optional) – Tuple containing arrays with unit onsets and offsets. Defaults to False.

  • kwargs – Keyword arguments to be passed to melspectrogram()

pykanto.plot.mspaced_mask(N: int, M: int) → List[int][source]#

Returns a mask of length N to select M indices as regularly spaced as possible.

Parameters

  • N (int) – Lenght of list

  • M (int) – Number of indices to return

Returns

A binary mask

Return type

List[int]

pykanto.plot.rand_jitter(arr: np.ndarray, jitter: float = 0.001) → np.ndarray[source]#

Adds random jitter to an array.

Parameters

  • arr (np.ndarray) – Array to jitter.

  • jitter (float, optional) – Jitter factor. Defaults to 0.001.

Returns

Jittered array.

Return type

np.ndarray

pykanto.plot.show_spec_centroid_bandwidth(dataset: KantoData, centroid: np.ndarray, spec_bw: np.ndarray, key: None | str = None, spec: None | np.ndarray = None) → None[source]#

Plots spectral centroids and bandwiths over a mel spectrogram. You can either provide a key string for a vocalisation or its mel spectrogram directly.

Parameters

  • dataset (KantoData) – Dataset object with your data.

  • centroid (np.ndarray) – Array of centroids.

  • spec_bw (np.ndarray) – Array of badwidths.

  • key (None | str = None) – Key of a vocalisation. Defaults to None.

  • (spec (spec) – None | np.ndarray): Mel spectrogram. Defaults to None.

pykanto.plot.show_minmax_frequency(dataset: KantoData, minfreqs: np.ndarray, maxfreqs: np.ndarray, roll_percents: list[float, float], key: None | str = None, spec: None | np.ndarray = None) → None[source]#

Plots approximate minimum and maximum frequencies over a mel spectrogram. You can either provide a key string for a vocalisation or its mel spectrogram directly.

Parameters

  • dataset (KantoData) – Dataset object with your data.

  • maxfreqs (np.ndarray) – Array of maximum frequencies.

  • minfreqs (np.ndarray) – Array of minimum frequencies.

  • roll_percents (list[float, float]) – Percentage of energy contained in bins.

  • key (None | str = None) – Key of a vocalisation. Defaults to None.

  • (spec (spec) – None | np.ndarray): Mel spectrogram. Defaults to None.

pykanto.plot.build_plot_summary(dataset: KantoData, nbins: int = 50, variable: str = 'frequency') → None[source]#

Plots a histogram + kernel densiyy estimate of the frequency distribution of vocalisation duration and frequencies.

Note

Durations and frequencies come from bounding boxes, not vocalisations. This function, along with show_extreme_songs(), is useful to spot any outliers, and to quickly explore the full range of data.

Parameters

  • dataset (KantoData) – Dataset to use.

  • nbins (int, optional) – Number of bins in histogram. Defaults to 50.

  • variable (str, optional) – One of ‘frequency’, ‘duration’, ‘sample_size’, ‘all’. Defaults to ‘frequency’.

Raises

ValueError – variable must be one of [‘frequency’, ‘duration’, ‘sample_size’, ‘all’]