Feat/Add functions for sound event grouping

[mbsantiago]

This PR introduces new functions to facilitate the grouping of sound events into sequences based on various similarity criteria. This is particularly useful when dealing with complex acoustic scenarios where multiple sound events might be related to the same source or individual.

Motivation:

• Multiple components of a single source: Sound events representing different acoustic or harmonic components of the same source might occur in different frequency ranges. Grouping these events helps to analyze them collectively rather than as independent occurrences.
• Repeated vocalizations: When an individual produces repeated vocalizations (e.g., bat echolocation, cricket songs), the events might appear in the same frequency range but at different times. Grouping these events can help identify vocalizations from the same individual or species.

New functions:

• soundevent.geometry.operations.group_sound_events:
  • Takes a list of data.SoundEvent objects and a user-defined comparison function (comparison_fn).
  • Groups sound events into data.Sequence objects based on pairwise similarity determined by the comparison_fn.
• soundevent.geometry.operations.have_temporal_overlap:
  • Checks if two data.Geometry objects have temporal overlap, optionally considering minimum absolute or relative overlap thresholds.
• soundevent.geometry.operations.have_frequency_overlap:
  • Checks if two data.Geometry objects have frequency overlap, optionally considering minimum absolute or relative overlap thresholds.

Example usage:

from soundevent import data
from soundevent.geometry.operations import (
    group_sound_events,
    have_temporal_overlap,
    have_frequency_overlap,
)

# Define a comparison function based on temporal and frequency overlap
def compare_sound_events(se1, se2):
    return (
        have_temporal_overlap(se1.geometry, se2.geometry, min_relative_overlap=0.5)
        and have_frequency_overlap(se1.geometry, se2.geometry, min_relative_overlap=0.8)
    )

# Group sound events
sequences = group_sound_events(sound_events, compare_sound_events)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.14%. Comparing base (6e5224d) to head (afa09e3).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #18      +/-   ##
==========================================
+ Coverage   87.96%   88.14%   +0.17%     
==========================================
  Files         112      112              
  Lines        3249     3297      +48     
  Branches      381      388       +7     
==========================================
+ Hits         2858     2906      +48     
  Misses        305      305              
  Partials       86       86              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.