Plotting Module

soundevent.plot

Plotting utilities.

Modules:

Name	Description
annotation	Functions for plotting annotations.
common	Common utilities for plotting.
geometries	Functions for plotting sound event geometries.
prediction
tags	Functions for plotting tags.

Classes:

Name	Description
TagColorMapper	Maps tags to colors.

Functions:

Name	Description
add_tags_legend	Add a legend for tags.
create_axes	Create a new figure and axes.
plot_annotation	Plot a sound event annotation on a spectrogram.
plot_annotations	Plot a collection of sound event annotations on a spectrogram.
plot_geometry	Plot a geometry in the given ax.
plot_prediction	Plot a sound event prediction on a spectrogram.
plot_predictions	Plot a collection of sound event predictions on a spectrogram.
plot_tag	Plot a tag as a dot on a spectrogram.

Classes

TagColorMapper(cmap='tab20', num_colors=20)

Maps tags to colors.

Methods:

Name	Description
get_color	Get color for tag.

Functions

get_color(tag)

Get color for tag.

Functions

add_tags_legend(ax, color_mapper)

Add a legend for tags.

create_axes(figsize=None)

Create a new figure and axes.

Parameters:

Name	Type	Description	Default
figsize	Optional[Tuple[float, float]]	The size of the figure. If None, use the default size.	None

Returns:

Type	Description
ax	The axes.

plot_annotation(annotation, ax=None, position='top-right', color_mapper=None, time_offset=0.001, freq_offset=1000, color=None, **kwargs)

Plot a sound event annotation on a spectrogram.

This function plots the geometry of the sound event and its associated tags.

Parameters:

Name	Type	Description	Default
annotation	SoundEventAnnotation	The sound event annotation to plot.	required
ax	Optional[Axes]	The matplotlib axes to plot on. If None, a new one is created.	None
position	Positions	The position of the tags relative to the geometry.	'top-right'
color_mapper	Optional[TagColorMapper]	A TagColorMapper instance to map tags to colors. If None, a new one is created.	None
time_offset	float	The time offset for positioning the tags.	0.001
freq_offset	float	The frequency offset for positioning the tags.	1000
color	Optional[str]	The color of the geometry. If None, the color is determined by the color mapper.	None
**kwargs		Additional keyword arguments passed to create_axes and plot_geometry.	{}

Returns:

Type	Description
Axes	The matplotlib axes with the annotation plotted.

plot_annotations(annotations, ax=None, position='top-right', color_mapper=None, time_offset=0.001, freq_offset=1000, legend=True, color=None, **kwargs)

Plot a collection of sound event annotations on a spectrogram.

This function iterates through a collection of sound event annotations and plots each one on the provided matplotlib axes.

Parameters:

Name	Type	Description	Default
annotations	Iterable[SoundEventAnnotation]	An iterable of SoundEventAnnotation objects to plot.	required
ax	Optional[Axes]	The matplotlib axes to plot on. If None, a new one is created.	None
position	Positions	The position of the tags relative to the geometry.	'top-right'
color_mapper	Optional[TagColorMapper]	A TagColorMapper instance to map tags to colors. If None, a new one is created.	None
time_offset	float	The time offset for positioning the tags.	0.001
freq_offset	float	The frequency offset for positioning the tags.	1000
legend	bool	Whether to add a legend for the tags.	True
color	Optional[str]	The color of the geometries. If None, the color is determined by the color mapper.	None
**kwargs		Additional keyword arguments passed to plot_annotation.	{}

Returns:

Type	Description
Axes	The matplotlib axes with the annotations plotted.

plot_geometry(geometry, ax=None, figsize=None, **kwargs)

Plot a geometry in the given ax.

plot_prediction(prediction, ax=None, position='top-right', color_mapper=None, time_offset=0.001, freq_offset=1000, max_alpha=0.5, color=None, **kwargs)

Plot a sound event prediction on a spectrogram.

This function plots the geometry of the sound event and its associated tags. The transparency of the geometry is determined by the prediction score and the max_alpha parameter. The transparency of the tags is directly controlled by the prediction score of each tag.

Parameters:

Name	Type	Description	Default
prediction	SoundEventPrediction	The sound event prediction to plot.	required
ax	Optional[Axes]	The matplotlib axes to plot on. If None, a new one is created.	None
position	Positions	The position of the tags relative to the geometry.	'top-right'
color_mapper	Optional[TagColorMapper]	A TagColorMapper instance to map tags to colors. If None, a new one is created.	None
time_offset	float	The time offset for positioning the tags.	0.001
freq_offset	float	The frequency offset for positioning the tags.	1000
max_alpha	float	The maximum transparency of the plotted geometry, scaled by the prediction score.	0.5
color	Optional[str]	The color of the geometry. If None, the color is determined by the color mapper.	None
**kwargs		Additional keyword arguments passed to create_axes and plot_geometry.	{}

Returns:

Type	Description
Axes	The matplotlib axes with the prediction plotted.

plot_predictions(predictions, ax=None, position='top-right', color_mapper=None, time_offset=0.001, freq_offset=1000, legend=True, max_alpha=0.5, color=None, **kwargs)

Plot a collection of sound event predictions on a spectrogram.

This function iterates through a collection of sound event predictions and plots each one on the provided matplotlib axes.

Parameters:

Name	Type	Description	Default
predictions	Iterable[SoundEventPrediction]	An iterable of SoundEventPrediction objects to plot.	required
ax	Optional[Axes]	The matplotlib axes to plot on. If None, a new one is created.	None
position	Positions	The position of the tags relative to the geometry.	'top-right'
color_mapper	Optional[TagColorMapper]	A TagColorMapper instance to map tags to colors. If None, a new one is created.	None
time_offset	float	The time offset for positioning the tags.	0.001
freq_offset	float	The frequency offset for positioning the tags.	1000
legend	bool	Whether to add a legend for the tags.	True
max_alpha	float	The maximum transparency of the plotted geometries, scaled by the prediction score.	0.5
color	Optional[str]	The color of the geometries. If None, the color is determined by the color mapper.	None
**kwargs		Additional keyword arguments passed to plot_prediction.	{}

Returns:

Type	Description
Axes	The matplotlib axes with the predictions plotted.

plot_tag(time, frequency, color, ax=None, size=10, alpha=1, **kwargs)

Plot a tag as a dot on a spectrogram.

Parameters:

Name	Type	Description	Default
time	float	Time coordinate of the tag.	required
frequency	float	Frequency coordinate of the tag.	required
color	str	Color of the tag.	required
ax	Optional[Axes]	Axes to plot on. If None, a new one is created.	None
size	int	Size of the tag marker.	10
alpha	float	Transparency of the tag marker.	1
**kwargs		Keyword arguments passed to create_axes.	{}

Returns:

Type	Description
Axes	Axes with the tag plotted.