Geometry Module#

Additional dependencies

To use the soundevent.geometry module you need to install some additional dependencies. Make sure you have them installed by running the following command:

pip install soundevent[geometry]

`soundevent.geometry` #

Geometry Module.

The geometry module in the soundevent package offers a set of essential functions to handle sound event geometry objects effectively. It provides tools to manage various aspects of sound event geometries, including operations like overlap detection, geometry shifting, and transformations. These functionalities are crucial in bioacoustic analysis, allowing users to comprehend the geometric relationships between different sound events.

Understanding the spatial arrangement of sound events is pivotal in bioacoustic research, enabling tasks such as matching sound event predictions with ground truths for evaluation. The geometry module simplifies these tasks by providing a clear and efficient interface for handling sound event geometries.

Modules:

Name	Description
`conversion`	Convert Geometry objects into shapely objects and vice versa.
`features`	Compute sound event features from geometries.
`html`	HTML representation of geometries.
`operations`	Functions that handle SoundEvent geometries.

Functions:

Name	Description
`buffer_geometry`	Buffer a geometry.
`compute_bounds`	Compute the bounds of a geometry.
`compute_geometric_features`	Compute features from a geometry.
`geometry_to_html`	Represent the geometry as HTML.
`geometry_to_shapely`	Convert a Geometry to a shapely geometry.
`get_geometry_point`	Calculate the coordinates of a specific point within a geometry.
`group_sound_events`	Group sound events into sequences based on a pairwise comparison.
`have_frequency_overlap`	Check if two geometries have frequency overlap.
`intervals_overlap`	Check if two intervals overlap.
`is_in_clip`	Check if a geometry lies within a clip, considering a minimum overlap.
`rasterize`	Rasterize geometric objects into an xarray DataArray.

Functions#

`buffer_geometry(geometry, time_buffer=0, freq_buffer=0, **kwargs)` #

Buffer a geometry.

Parameters:

Name	Type	Description	Default
`geometry`	`Geometry`	The geometry to buffer.	required
`time_buffer`	`Time`	The time buffer to apply to the geometry, in seconds. Defaults to 0.	`0`
`freq_buffer`	`Frequency`	The frequency buffer to apply to the geometry, in Hz. Defaults to 0.	`0`
`**kwargs`	`Any`	Additional keyword arguments to pass to the Shapely buffer function.	`{}`

Returns:

Name	Type	Description
`geometry`	`Geometry`	The buffered geometry.

Raises:

Type	Description
`NotImplementedError`	If the geometry type is not supported.
`ValueError`	If the time buffer or the frequency buffer is negative.

`compute_bounds(geometry)` #

Compute the bounds of a geometry.

Parameters:

Name	Type	Description	Default
`geometry`	`Geometry`	The geometry to compute the bounds of.	required

Returns:

Name	Type	Description
`bounds`	`tuple[float, float, float, float]`	The bounds of the geometry. The bounds are returned in the following order: start_time, low_freq, end_time, high_freq.

`compute_geometric_features(geometry)` #

Compute features from a geometry.

Some basic acoustic features can be computed from a geometry. This function computes these features and returns them as a list of features.

The following features are computed when possible:

duration: The duration of the geometry.
low_freq: The lowest frequency of the geometry.
high_freq: The highest frequency of the geometry.
bandwidth: The bandwidth of the geometry.
num_segments: The number of segments in the geometry.

Depending on the geometry type, some features may not be computed. For example, a TimeStamp geometry does not have a bandwidth.

Parameters:

Name	Type	Description	Default
`geometry`	`Geometry`	The geometry to compute features from.	required

Returns:

Type	Description
`List[Feature]`	The computed features.

Raises:

Type	Description
`NotImplementedError`	If the geometry type is not supported.

`geometry_to_html(geom)` #

Represent the geometry as HTML.

Parameters:

Name	Type	Description	Default
`geom`	`Geometry`	The geometry to represent as HTML.	required

Returns:

Type	Description
`str`	The HTML representation of the geometry.

`geometry_to_shapely(geom)` #

geometry_to_shapely(geom: data.TimeStamp) -> shapely.LineString

geometry_to_shapely(geom: data.TimeInterval) -> shapely.Polygon

geometry_to_shapely(geom: data.Point) -> shapely.Point

geometry_to_shapely(geom: data.LineString) -> shapely.LineString

geometry_to_shapely(geom: data.Polygon) -> shapely.Polygon

geometry_to_shapely(geom: data.BoundingBox) -> shapely.Polygon

geometry_to_shapely(geom: data.MultiPoint) -> shapely.MultiPoint

geometry_to_shapely(geom: data.MultiLineString) -> shapely.MultiLineString

geometry_to_shapely(geom: data.MultiPolygon) -> shapely.MultiPolygon

Convert a Geometry to a shapely geometry.

Parameters:

Name	Type	Description	Default
`geom`	`Geometry`	The Geometry to convert.	required

Returns:

Type	Description
`Geometry`	The converted shapely geometry.

`get_geometry_point(geometry, position='bottom-left')` #

Calculate the coordinates of a specific point within a geometry.

Parameters:

Name	Type	Description	Default
`geometry`	`Geometry`	The geometry object for which to calculate the point coordinates.	required
`position`	`Positions`	The specific point within the geometry to calculate coordinates for. Defaults to 'bottom-left'.	`'bottom-left'`

Returns:

Type	Description
`Tuple[float, float]`	The coordinates of the specified point within the geometry.

Raises:

Type	Description
`ValueError`	If an invalid point is specified.

Notes

The following positions are supported:

'bottom-left': The point defined by the start time and lowest frequency of the geometry.
'bottom-right': The point defined by the end time and lowest frequency of the geometry.
'top-left': The point defined by the start time and highest frequency of the geometry.
'top-right': The point defined by the end time and highest frequency of the geometry.
'center-left': The point defined by the middle time and lowest frequency of the geometry.
'center-right': The point defined by the middle time and highest frequency of the geometry.
'top-center': The point defined by the end time and middle frequency of the geometry.
'bottom-center': The point defined by the start time and middle frequency of the geometry.
'center': The point defined by the middle time and middle frequency of the geometry.
'centroid': The centroid of the geometry. Computed using the shapely library.
'point_on_surface': A point on the surface of the geometry. Computed using the shapely library.

For all positions except 'centroid' and 'point_on_surface', the time and frequency values are calculated by first computing the bounds of the geometry and then determining the appropriate values based on the specified point type.

`group_sound_events(sound_events, comparison_fn)` #

Group sound events into sequences based on a pairwise comparison.

This function takes a sequence of data.SoundEvent objects and a comparison function. It applies the comparison function to all pairs of sound events to determine their similarity. Sound events that are deemed similar are grouped together into data.Sequence objects.

The comparison function should take two data.SoundEvent objects as input and return True if they are considered similar, and False otherwise.

Parameters:

Name	Type	Description	Default
`sound_events`	`Sequence[SoundEvent]`	A sequence of `data.SoundEvent` objects to be grouped.	required
`comparison_fn`	`Callable[[SoundEvent, SoundEvent], bool]`	A function that compares two `data.SoundEvent` objects and returns True if they should be grouped together, False otherwise.	required

Returns:

Type	Description
`list[Sequence]`	A list of `data.Sequence` objects, where each sequence contains a group of similar sound events.

Notes

This function groups sound events based on transitive similarity. While it uses pairwise comparisons, the final groups (sequences) can include sound events that aren't directly similar according to your comparison_fn. Think of it like a chain: sound event A is similar to B, B is similar to C, but A might not be similar to C directly. They all end up in the same group because of their connections through B. Technically, this works by finding the connected components in a graph where the sound events are nodes, and the edges represent similarity based on your comparison_fn.

Examples:

>>> # Define a comparison function based on temporal overlap
>>> def compare_sound_events(se1, se2):
...     return have_temporal_overlap(
...         se1.geometry, se2.geometry, min_absolute_overlap=0.5
...     )
>>> # Group sound events with the comparison function
>>> sequences = group_sound_events(
...     sound_events, compare_sound_events
... )

`have_frequency_overlap(geom1, geom2, min_absolute_overlap=None, min_relative_overlap=None)` #

Check if two geometries have frequency overlap.

This function determines whether two geometry objects have any frequency overlap, optionally considering a minimum required overlap, either in absolute terms (Hz) or relative to the smaller frequency range of the two geometries.

Parameters:

Name	Type	Description	Default
`geom1`	`Geometry`	The first geometry object.	required
`geom2`	`Geometry`	The second geometry object.	required
`min_absolute_overlap`	`float`	The minimum required absolute overlap in Hz. Defaults to None, meaning any overlap is sufficient.	`None`
`min_relative_overlap`	`float`	The minimum required relative overlap (between 0 and 1). Defaults to None.	`None`

Returns:

Type	Description
`bool`	True if the geometries overlap with the specified minimum overlap, False otherwise.

Raises:

Type	Description
`ValueError`	If both `min_absolute_overlap` and `min_relative_overlap` are provided. If `min_relative_overlap` is not in the range [0, 1].

`intervals_overlap(interval1, interval2, min_absolute_overlap=None, min_relative_overlap=None)` #

Check if two intervals overlap.

This function determines whether two intervals, represented as tuples of (start, stop) values, have any overlap. It optionally allows specifying a minimum required overlap, either in absolute terms or relative to the smaller interval.

Parameters:

Name	Type	Description	Default
`interval1`	`tuple[float, float]`	The first interval, as a tuple (start, stop).	required
`interval2`	`tuple[float, float]`	The second interval, as a tuple (start, stop).	required
`min_absolute_overlap`	`float`	The minimum required absolute overlap. Defaults to None, meaning any overlap is sufficient.	`None`
`min_relative_overlap`	`float`	The minimum required relative overlap (between 0 and 1). Defaults to None.	`None`

Returns:

Type	Description
`bool`	True if the intervals overlap with the specified minimum overlap, False otherwise.

Raises:

Type	Description
`ValueError`	If both `min_absolute_overlap` and `min_relative_overlap` are provided. If `min_relative_overlap` is not in the range [0, 1].

Examples:

>>> intervals_overlap((1.0, 3.0), (2.0, 4.0))
True
>>> intervals_overlap(
...     (1.0, 3.0),
...     (2.0, 4.0),
...     min_absolute_overlap=0.5,
... )
True
>>> intervals_overlap(
...     (1.0, 3.0),
...     (2.0, 4.0),
...     min_absolute_overlap=1.5,
... )
False
>>> intervals_overlap(
...     (1.0, 3.0),
...     (2.0, 4.0),
...     min_relative_overlap=0.25,
... )
True
>>> intervals_overlap(
...     (1.0, 3.0),
...     (2.0, 4.0),
...     min_relative_overlap=0.75,
... )
False

`is_in_clip(geometry, clip, minimum_overlap=0)` #

Check if a geometry lies within a clip, considering a minimum overlap.

This function determines whether a given geometry falls within the time boundaries of a clip. It takes into account a minimum_overlap parameter, which specifies the minimum required temporal overlap (in seconds) between the geometry and the clip for the geometry to be considered inside the clip.

Parameters:

Name	Type	Description	Default
`geometry`	`Geometry`	The geometry object to be checked.	required
`clip`	`Clip`	The clip object to check against.	required
`minimum_overlap`	`float`	The minimum required overlap between the geometry and the clip in seconds. Defaults to 0, meaning any overlap is sufficient.	`0`

Returns:

Type	Description
`bool`	True if the geometry is within the clip with the specified minimum overlap, False otherwise.

Raises:

Type	Description
`ValueError`	If the `minimum_overlap` is negative.

Examples:

>>> from soundevent import data
>>> geometry = data.Geometry(...)
>>> clip = data.Clip(start_time=0.0, end_time=5.0, ...)
>>> is_in_clip(geometry, clip, minimum_overlap=0.5)
True

`rasterize(geometries, array, values=1, fill=0, dtype=np.float32, xdim=Dimensions.time.value, ydim=Dimensions.frequency.value, all_touched=False)` #

Rasterize geometric objects into an xarray DataArray.

This function takes a list of geometric objects (geometries) and rasterizes them into a specified xr.DataArray. Each geometry can be associated with a value, which is used to fill the corresponding pixels in the rasterized array.

Parameters:

Name	Type	Description	Default
`geometries`	`List[Geometry]`	A list of `Geometry` objects to rasterize.	required
`array`	`DataArray`	The xarray DataArray into which the geometries will be rasterized.	required
`values`	`Union[Value, List[Value], Tuple[Value]]`	The values to fill the rasterized pixels for each geometry. If a single value is provided, it will be used for all geometries. If a list or tuple of values is provided, it must have the same length as the `geometries` list. Defaults to 1.	`1`
`fill`	`float`	The value to fill pixels not covered by any geometry. Defaults to 0.	`0`
`dtype`	`DTypeLike`	The data type of the output rasterized array. Defaults to np.float32.	`float32`
`xdim`	`str`	The name of the dimension representing the x-axis in the DataArray. Defaults to "time".	`time.value`
`ydim`	`str`	The name of the dimension representing the y-axis in the DataArray. Defaults to "frequency".	`frequency.value`
`all_touched`	`bool`	If True, all pixels touched by geometries will be filled, otherwise only pixels whose center point is within the geometry are filled. Defaults to False.	`False`

Returns:

Type	Description
`DataArray`	A new xarray DataArray containing the rasterized data, with the same coordinates and dimensions as the input `array`.

Raises:

Type	Description
`ValueError`	If the number of `values` does not match the number of `geometries`.

Geometry Module#

soundevent.geometry #

Functions#

buffer_geometry(geometry, time_buffer=0, freq_buffer=0, **kwargs) #

compute_bounds(geometry) #

compute_geometric_features(geometry) #

geometry_to_html(geom) #

geometry_to_shapely(geom) #

get_geometry_point(geometry, position='bottom-left') #

group_sound_events(sound_events, comparison_fn) #

have_frequency_overlap(geom1, geom2, min_absolute_overlap=None, min_relative_overlap=None) #

intervals_overlap(interval1, interval2, min_absolute_overlap=None, min_relative_overlap=None) #

is_in_clip(geometry, clip, minimum_overlap=0) #

rasterize(geometries, array, values=1, fill=0, dtype=np.float32, xdim=Dimensions.time.value, ydim=Dimensions.frequency.value, all_touched=False) #

`soundevent.geometry` #

`buffer_geometry(geometry, time_buffer=0, freq_buffer=0, **kwargs)` #

`compute_bounds(geometry)` #

`compute_geometric_features(geometry)` #

`geometry_to_html(geom)` #

`geometry_to_shapely(geom)` #

`get_geometry_point(geometry, position='bottom-left')` #

`group_sound_events(sound_events, comparison_fn)` #

`have_frequency_overlap(geom1, geom2, min_absolute_overlap=None, min_relative_overlap=None)` #

`intervals_overlap(interval1, interval2, min_absolute_overlap=None, min_relative_overlap=None)` #

`is_in_clip(geometry, clip, minimum_overlap=0)` #

`rasterize(geometries, array, values=1, fill=0, dtype=np.float32, xdim=Dimensions.time.value, ydim=Dimensions.frequency.value, all_touched=False)` #