Whombat Python API

Welcome to the Whombat Python API reference page. This section provides a comprehensive guide to all the functions available through the whombat.api module, designed to simplify the use of Whombat objects without the need to handle the intricacies of SQLAlchemy internals.

The API is organized into distinct submodules, each corresponding to a crucial data object within Whombat. Each sub-API contains functions tailored for interactions with that specific type of object.

Getting Started

To get started, follow the example below, which demonstrates how to use these functions:

from whombat import api

async def main():
    # Create a session
    async with api.create_session() as session:
        # Example 1: Get or create a tag
        tag = await api.tags.get_or_create(session, key="species", value="Myotis myotis")

        # Example 2: Retrieve a recording by path
        recording = await api.recordings.get_by_path(session, path="<path_to_file>")

        # Example 3: Add a tag to a recording
        recording = await api.recordings.add_tag(session, recording, tag)

Async functions

Most functions in the Whombat API are asynchronous. This design choice enhances code efficiency, particularly since many operations involve database transactions that can potentially slow down the program if executed synchronously.

On this page, you can explore all the submodules available and the functions they provide. It's worth noting that each submodule is an instance of a BaseAPI class, which manages an internal cache to minimize unnecessary database queries. To access the reference for a specific submodule, such as api.sound_events, please consult the corresponding class, in this case, SoundEventAPI, to discover all the available functions.

whombat.api

Python API for Whombat.

Functions

compute_spectrogram(recording, start_time, end_time, audio_parameters, spectrogram_parameters, audio_dir=None)

Compute a spectrogram for a recording.

Parameters:

Name	Type	Description	Default
recording	Recording	The recording to compute the spectrogram for.	required
start_time	float	Start time in seconds.	required
end_time	float	End time in seconds.	required
audio_dir	Path | None	The directory where the audio files are stored.	None
spectrogram_parameters	SpectrogramParameters	Spectrogram parameters.	required

Returns:

Type	Description
DataArray	Spectrogram image.

create_session(db_url=DEFAULT_DB_URL) async

Create a database session.

This function creates a database session that can be used to interact with the database.

It is a context manager, so it can be used with the async with syntax.

Parameters:

Name	Type	Description	Default
db_url	str	The database URL to use, by default it is set to sqlite+aiosqlite://, which is an in-memory database.	DEFAULT_DB_URL

Yields:

Name	Type	Description
session	AsyncSession	The database session.

Examples:

To create a database session, use the async with syntax.

async with create_session() as session:
    # Do stuff with the session
    # ...

You can specify a database URL to use.

async with create_session("sqlite+aiosqlite:///my_db.db") as session:
    # Do stuff with the session
    # ...

Note

This function is asynchronous, so it must be called with the await keyword.

find_feature(features, feature_name, default=None)

Find a feature from a list of features by its name.

Helper function for finding a feature by name. Returns the first feature with the given name, or a default value if no feature is found.

Parameters:

Name	Type	Description	Default
features	Sequence[Feature]	The features to search.	required
feature_name	str	The name of the feature to find.	required
default	Any	The default value to return if the feature is not found.	None

Returns:

Name	Type	Description
feature	Feature | None	The feature, or the default value if the feature was not found.

find_feature_value(features, feature_name, default=None)

Find a the value of a feature from a list of features by its name.

Parameters:

Name	Type	Description	Default
features	Sequence[Feature]	The features to search.	required
feature_name	str	The name of the feature to find.	required
default	Any	The default value to return if the feature is not found.	None

Returns:

Name	Type	Description
value	float | None	The feature value, or the default value if the feature was not found.

find_tag(tags, key, default=None)

Find a tag from a list of tags by its key.

Helper function for finding a tag by key. Returns the first tag with the given key, or a default value if no tag is found.

Parameters:

Name	Type	Description	Default
tags	Sequence[Tag]	The tags to search.	required
key	str	The key to search for.	required
default	Any	The default value to return if the tag is not found.	None

Returns:

Name	Type	Description
tag	Tag | None	The tag, or the default value if the tag was not found.

find_tag_value(tags, key, default=None)

Find a the value of a tag from a list of tags by its key.

Parameters:

Name	Type	Description	Default
tags	Sequence[Tag]	The tags to search.	required
key	str	The key to search for.	required
default	Any	The default value to return if the tag is not found.	None

Returns:

Name	Type	Description
value	float | None	The tag value, or the default value if the tag was not found.

load_audio(recording, start_time=None, end_time=None, audio_dir=None, audio_parameters=None)

Load audio.

Parameters:

Name	Type	Description	Default
recording	Recording	The recording to load audio from.	required
start_time	float | None	Start time in seconds.	None
end_time	float | None	End time in seconds.	None
audio_dir	Path | None	The directory where the audio files are stored.	None
audio_parameters	AudioParameters | None	Audio parameters.	None

Returns:

Type	Description
bytes	Audio data.

load_clip_bytes(path, start, speed=1, frames=8192, time_expansion=1, start_time=None, end_time=None, bit_depth=16)

Load audio.

Parameters:

Name	Type	Description	Default
path	Path	The path to the audio file.	required
start	int	Start byte.	required
speed	float	The factor by which to speed up or slow down the audio. By default, it is 1.	1
frames	int	The number of audio frames to read at a time.	8192
time_expansion	float	Time expansion factor of the audio. By default, it is 1.	1
start_time	float | None	The time in seconds at which to start reading the audio.	None
end_time	float | None	The time in seconds at which to stop reading the audio.	None
bit_depth	int	The bit depth of the resulting audio. By default, it is 16 bits.	16

Returns:

Type	Description
bytes	Loaded audio data in bytes
start	Start byte
end	End byte
filesize	Total size of clip in bytes.

whombat.api.users.UserAPI()

Bases: BaseAPI[UUID, User, SimpleUser, UserCreate, UserUpdate]

API to interact with user objects in the database.

Functions

create(session, username, password, email, name=None, is_active=True, is_superuser=False) async

Create a user.

This function creates a user in the database.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
username	str	The username of the user.	required
password	str	The password of the user.	required
email	str	The email of the user.	required
name	str | None	The users full name.	None
is_active	bool	Whether the user is active. This means that the user can log in. By default, this is set to True.	True
is_superuser	bool	Whether the user is a superuser. This means that the user can perform all actions.	False

Returns:

Name	Type	Description
user	User

Raises:

Type	Description
UserAlreadyExists	If a user with the same username or email already exists.

Examples:

To create a user:

    async with create_session() as session:
        user = await create_user(
            session,
            username="username",
            password="password",
            email="email",
        )

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Get or create a user from a soundevent user object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
data	User	The soundevent user object to get or create.	required

Returns:

Name	Type	Description
user	User	The user object.

Raises:

Type	Description
DuplicateObjectError	If a user with the same username or email already exists.

Notes

If no user with the same username, email or UUID exists, a new user will be created with a random password and marked as inactive.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_by_email(session, email) async

Get a user by email.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
email	str	The email to use.	required

Returns:

Name	Type	Description
user	User

Raises:

Type	Description
NotFoundError

get_by_username(session, username) async

Get a user by username.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
username	str	The username to use.	required

Returns:

Name	Type	Description
user	User

Raises:

Type	Description
NotFoundError

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

to_soundevent(obj)

Convert a user instance to soundevent object.

Parameters:

Name	Type	Description	Default
obj	SimpleUser	The user to get the data from.	required

Returns:

Name	Type	Description
user	User	The soundevent user object.

update(session, obj, data) async

Update a user.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	SimpleUser	The user to update.	required
data	UserUpdate	The data to update the user with.	required

Returns:

Name	Type	Description
user	User	The updated user.

Raises:

Type	Description
NoResultFound	If no user with the given id exists.

whombat.api.tags.TagAPI()

Bases: BaseAPI[tuple[str, str], Tag, Tag, TagCreate, TagUpdate]

Functions

count_by_clip_annotation(session, *, limit=1000, offset=0, filters=None, sort_by='-counts') async

count_by_recording(session, *, limit=1000, offset=0, filters=None, sort_by='-counts') async

count_by_sound_event_annotation(session, *, limit=1000, offset=0, filters=None, sort_by='-counts') async

create(session, key, value, **kwargs) async

Create a tag.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
key	str	The tag key.	required
value	str	The tag value.	required

Returns:

Type	Description
Tag	The tag.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, tag) async

Create a tag from a soundevent Tag object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
tag	Tag	The soundevent tag object.	required

Returns:

Type	Description
TagCreate	The tag.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_annotation_tags(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_or_create(session, key, value) async

Get a tag by its key and value, or create it if it does not exist.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
key	str	The tag key.	required
value	str	The tag value.	required

Returns:

Type	Description
Tag	The tag.

get_recording_tags(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

get_sound_event_annotation_tags(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

to_soundevent(tag)

Create a soundevent Tag object from a tag.

Parameters:

Name	Type	Description	Default
tag	Tag	The tag.	required

Returns:

Type	Description
Tag	The soundevent tag object.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.features.FeatureNameAPI()

Bases: BaseAPI[str, FeatureName, FeatureName, FeatureNameCreate, FeatureNameUpdate]

API for interacting with feature names.

Functions

create(session, name, **kwargs) async

Create a feature name.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
name	str	The name of the feature.	required

Returns:

Type	Description
FeatureName	The feature name.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create a feature from a soundevent Feature object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	Feature	The soundevent feature object.	required

Returns:

Type	Description
FeatureCreate	The feature.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_feature(session, name, value) async

Get a feature object.

Will create the feature name if it does not exist.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
name	str	The name of the feature.	required
value	float	The value of the feature.	required

Returns:

Type	Description
FeatureName	The feature name.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_or_create(session, name) async

Get or create a feature name.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
name	str	The name of the feature.	required

Returns:

Type	Description
FeatureName	The feature name.

to_soundevent(feature)

Create a soundevent Feature object from a feature.

Parameters:

Name	Type	Description	Default
feature	Feature	The feature.	required

Returns:

Type	Description
Feature	The soundevent feature object.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.notes.NoteAPI()

Bases: BaseAPI[UUID, Note, Note, NoteCreate, NoteUpdate]

Functions

create(session, message, is_issue=False, created_by=None, **kwargs) async

Create a note.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
message	str	The note message.	required
is_issue	bool	Whether the note is an issue. Defaults to False. Used to indicate that the note is an issue that needs to be resolved.	False
created_by	SimpleUser | None	The user that created the note. Defaults to None.	None
**kwargs		Additional keyword arguments to use when creating the note, (e.g. uuid or created_on.)	{}

Returns:

Name	Type	Description
note	Note	The created note.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create a note from a soundevent Note object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
data	Note	The soundevent Note object.	required

Returns:

Name	Type	Description
note	Note	The created note.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_annotation_notes(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_recording_notes(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

get_sound_event_annotation_notes(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

to_soundevent(obj)

Create a soundevent Note object from a note.

Parameters:

Name	Type	Description	Default
obj	Note	The note.	required

Returns:

Name	Type	Description
note	Note	The soundevent Note object.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.recordings.RecordingAPI()

Bases: BaseAPI[UUID, Recording, Recording, RecordingCreate, RecordingUpdate]

Functions

add_feature(session, obj, feature) async

Add a feature to a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to add the feature to.	required
feature	Feature	The feature to add.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

add_note(session, obj, note) async

Add a note to a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to add the note to.	required
note	Note	The note to add.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

add_owner(session, obj, owner) async

Add an owner to a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to add the owner to.	required
owner	SimpleUser	The owner to add.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

add_tag(session, obj, tag) async

Add a tag to a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to add the tag to.	required
tag	Tag	The tag to add.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

adjust_time_expansion(session, obj, time_expansion) async

Adjust the time expansion of a recording.

When the time expansion of a recording is adjusted several associated entities must be updated to reflect the new time expansion. Firstly the duration and samplerate of the recording must be updated. Secondly, the time and frequency coordinates of all associated objects must be updated.

Parameters:

Name	Type	Description	Default
obj	Recording	The recording to adjust.	required
time_expansion	float	The new time expansion.	required

create(session, path, date=None, time=None, latitude=None, longitude=None, time_expansion=1.0, rights=None, audio_dir=None, **kwargs) async

Create a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
path	Path	The path to the audio file. This should be relative to the current working directory, or an absolute path.	required
date	date | None	The date of the recording.	None
time	time | None	The time of the recording.	None
latitude	float | None	The latitude of the recording site.	None
longitude	float | None	The longitude of the recording site.	None
time_expansion	float	Some recordings may be time expanded or time compressed. This value is the factor by which the recording is expanded or compressed. The default value is 1.0.	1.0
rights	str | None	A string describing the usage rights of the recording.	None
audio_dir	Path | None	The root directory for audio files. If not given, it will default to the value of settings.audio_dir.	None
**kwargs		Additional keyword arguments to use when creating the recording, (e.g. uuid or created_on.)	{}

Returns:

Name	Type	Description
recording	Recording	The created recording.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data, audio_dir=None) async

Create recordings.

If you want to create a single recording, use create_recording. However if you want to create multiple recordings, it is more efficient to use this function.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
data	Sequence[dict]	The data to create the recordings with.	required
audio_dir	Path | None	The root directory for audio files. If not given, it will default to the value of settings.audio_dir.	None

Returns:

Name	Type	Description
recordings	list[Recording]	The created recordings.

Notes

This function will only create recordings for files that: - are audio files (according to files.is_audio_file) - media info can be extracted from it. - do not already exist in the database.

Any files that do not meet these criteria will be silently ignored.

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, recording, audio_dir=None) async

Create a recording from a soundevent.Recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
recording	Recording	The soundevent.Recording to create the recording from.	required
audio_dir	Path | None	The root directory for audio files. If not given, it will default to the value of settings.audio_dir.	None

Returns:

Name	Type	Description
recording	Recording	The created recording.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_by_hash(session, recording_hash) async

Get a recording by hash.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
recording_hash	str	The hash of the recording.	required

Returns:

Name	Type	Description
recording	Recording	The recording.

Raises:

Type	Description
NotFoundError	If a recording with the given hash does not exist.

get_by_path(session, recording_path) async

Get a recording by path.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
recording_path	Path	The path of the recording.	required

Returns:

Name	Type	Description
recording	Recording	The recording.

Raises:

Type	Description
NotFoundError	If a recording with the given path does not exist.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_media_info(session, recording_uuid, audio_dir=None) async

remove_feature(session, obj, feature) async

Remove a feature from a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to remove the feature from.	required
feature	Feature	The feature to remove.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

remove_note(session, obj, note) async

Remove a note from a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to remove the note from.	required
note	Note	The note to remove.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

remove_owner(session, obj, owner) async

Remove an owner from a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to remove the owner from.	required
owner	SimpleUser	The owner to remove.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

remove_tag(session, obj, tag) async

Remove a tag from a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to remove the tag from.	required
tag	Tag	The tag to remove.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

to_soundevent(recording, audio_dir=None)

Create a soundevent.Recording from a recording.

Parameters:

Name	Type	Description	Default
recording	Recording	The recording to create the soundevent.Recording from.	required
audio_dir	Path | None	The root directory for audio files. If not given, it will default to the value of settings.audio_dir.	None

Returns:

Name	Type	Description
recording	Recording	The created soundevent.Recording.

update(session, obj, data, audio_dir=None) async

Update a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to update.	required
data	RecordingUpdate	The data to update the recording with.	required
audio_dir	Path | None	The root directory for audio files. If not given, it will default to the value of settings.audio_dir.	None

Returns:

Name	Type	Description
recording	Recording	The updated recording.

update_feature(session, obj, feature) async

Update a feature of a recording.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Recording	The recording to update the feature of.	required
feature	Feature	The feature to update.	required

Returns:

Name	Type	Description
recording	Recording	The updated recording.

whombat.api.datasets.DatasetAPI()

Bases: BaseAPI[UUID, Dataset, Dataset, DatasetCreate, DatasetUpdate]

Functions

add_file(session, obj, path, date=None, time=None, latitude=None, longitude=None, time_expansion=1.0, rights=None, audio_dir=None) async

Add a file to a dataset.

This function adds a file to a dataset. The file is registered as a recording and is added to the dataset. If the file is already registered in the database, it is only added to the dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset to add the file to.	required
path	Path	The path to the audio file. This should be relative to the current working directory, or an absolute path.	required
date	date | None	The date of the recording.	None
time	time | None	The time of the recording.	None
latitude	float | None	The latitude of the recording site.	None
longitude	float | None	The longitude of the recording site.	None
time_expansion	float	Some recordings may be time expanded or time compressed. This value is the factor by which the recording is expanded or compressed. The default value is 1.0.	1.0
rights	str | None	A string describing the usage rights of the recording.	None
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None

Returns:

Name	Type	Description
recording	DatasetRecording	The recording that was added to the dataset.

Raises:

Type	Description
NotFoundError	If the file does not exist.
ValueError	If the file is not part of the dataset audio directory.

add_recording(session, obj, recording) async

Add a recording to a dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset to add the recording to.	required
recording	Recording	The recording to add to the dataset.	required

Returns:

Name	Type	Description
dataset_recording	DatasetRecording	The dataset recording that was created.

Raises:

Type	Description
ValueError	If the recording is not part of the dataset audio directory.

add_recordings(session, obj, recordings) async

Add recordings to a dataset.

Use this function to efficiently add multiple recordings to a dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset to add the recordings to.	required
recordings	Sequence[Recording]	The recordings to add to the dataset.	required

create(session, name, dataset_dir, description=None, audio_dir=None, **kwargs) async

Create a dataset.

This function will create a dataset and populate it with the audio files found in the given directory. It will look recursively for audio files within the directory.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
name	str	The name of the dataset.	required
dataset_dir	Path	The directory of the dataset.	required
description	str | None	The description of the dataset, by default None.	None
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Name	Type	Description
dataset	Dataset

Raises:

Type	Description
ValueError	If a dataset with the given name or audio directory already exists.
ValidationError	If the given audio directory does not exist.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, dataset_audio_dir=None, audio_dir=None) async

Create a dataset from a soundevent dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
data	Dataset	The soundevent dataset.	required
dataset_audio_dir	Path | None	The audio directory of the dataset, by default None. If None, the audio directory from the settings will be used.	None
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None

Returns:

Name	Type	Description
dataset	Dataset	The dataset.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_by_audio_dir(session, audio_dir) async

Get a dataset by audio directory.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
audio_dir	Path	The audio directory of the dataset to get.	required

Returns:

Name	Type	Description
dataset	Dataset

Raises:

Type	Description
NotFoundError	If no dataset with the given audio directory exists.

get_by_name(session, name) async

Get a dataset by name.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
name	str	The name of the dataset to get.	required

Returns:

Name	Type	Description
dataset	Dataset

Raises:

Type	Description
NotFoundError	If no dataset with the given name exists.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_recordings(session, obj, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get all recordings of a dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The ID of the dataset to get the recordings of.	required
limit	int	The maximum number of recordings to return, by default 1000. If set to -1, all recordings will be returned.	1000
offset	int	The number of recordings to skip, by default 0.	0
filters	Sequence[Filter] | None	A list of filters to apply to the query, by default None.	None
sort_by	str | None	The column to sort the recordings by, by default None.	'-created_on'

Returns:

Name	Type	Description
recordings	list[DatasetRecording]
count	int	The total number of recordings in the dataset.

get_state(session, obj, audio_dir=None) async

Compute the state of the dataset recordings.

The dataset directory is scanned for audio files and compared to the registered dataset recordings in the database. The following states are possible:

• missing: A file is registered in the database and but is missing.

• registered: A file is registered in the database and is present.

• unregistered: A file is not registered in the database but is present in the dataset directory.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset to get the state of.	required
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None

Returns:

Name	Type	Description
files	list[DatasetFile]

to_dataframe(session, dataset) async

Convert a dataset to a pandas DataFrame.

Generates a DataFrame containing information about the recordings in the dataset. The DataFrame includes the following columns: 'uuid', 'hash', 'path', 'samplerate', 'duration', 'channels', 'time_expansion', 'date', 'time', 'latitude', 'longitude', 'rights'.

Owners, tags, and features receive special treatment. Owners are concatenated into a string with the format 'user1:user2:user3'. Each tag is added as a column with the name 'tag_', and features as 'feature_'.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
dataset	Dataset	The dataset to convert to a DataFrame.	required

Returns:

Name	Type	Description
df	DataFrame	The dataset as a DataFrame.

Notes

The encoding of the dataset as a DataFrame is not lossless. Notes are excluded from the DataFrame, and there is no way to recover all owner information from the concatenated string of usernames. For full dataset recovery, use the to_soundevent method instead, returning a sound event dataset that can be exported to a JSON file and later imported, recovering all information.

to_soundevent(session, obj, audio_dir=None) async

Create a soundevent dataset from a dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset.	required
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None

Returns:

Name	Type	Description
dataset	Dataset	The soundevent dataset.

update(session, obj, data, audio_dir=None) async

Update a dataset.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
obj	Dataset	The dataset to update.	required
data	DatasetUpdate	The data to update the dataset with.	required
audio_dir	Path | None	The root audio directory, by default None. If None, the root audio directory from the settings will be used.	None

Returns:

Name	Type	Description
dataset	Dataset

Raises:

Type	Description
NotFoundError	If no dataset with the given UUID exists.

whombat.api.sound_events.SoundEventAPI()

Bases: BaseAPI[UUID, SoundEvent, SoundEvent, SoundEventCreate, SoundEventUpdate]

Functions

add_feature(session, obj, feature) async

Add features to a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	SoundEvent	The sound event to add features to.	required
feature	Feature	The feature to add to the sound event.	required

Returns:

Type	Description
SoundEvent	The updated sound event.

Raises:

Type	Description
NotFoundError	If the sound event does not exist in the database.

create(session, recording, geometry, **kwargs) async

Create a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
recording	Recording	The recording the sound event is from.	required
geometry	Geometry	The geometry representing the ROI of the sound event.	required
**kwargs		Additional keyword arguments to use when creating the sound event (e.g. uuid or created_on.)	{}

Returns:

Type	Description
SoundEvent	The created sound event.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_geometric_features(session, sound_events) async

Create sound event features.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
sound_events	Sequence[SoundEvent]	The sound events.	required

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, recording) async

Create a sound event from a soundevent SoundEvent object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	SoundEvent	The soundevent sound event object.	required
recording	Recording	The recording the sound event is from.	required

Returns:

Type	Description
SoundEvent	The sound event.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_recording(session, sound_event) async

remove_feature(session, obj, feature) async

Remove features from a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	SoundEvent	The sound event to remove features from.	required
feature	Feature	The feature to remove from the sound event.	required

Returns:

Type	Description
SoundEvent	The updated sound event.

Raises:

Type	Description
NotFoundError	If the sound event does not exist in the database.

to_soundevent(session, sound_event, audio_dir=None, recording=None) async

Create a soundevent SoundEvent object from a sound event.

Parameters:

Name	Type	Description	Default
sound_event	SoundEvent	The sound event.	required

Returns:

Type	Description
SoundEvent	The soundevent sound event object.

update(session, obj, data) async

Update a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	SoundEvent	The sound event to update.	required
data	SoundEventUpdate	The data to update the sound event with.	required

Returns:

Type	Description
SoundEvent	The updated sound event.

Raises:

Type	Description
NotFoundError	If the sound event does not exist in the database.

update_feature(session, obj, feature) async

Update features of a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	SoundEvent	The sound event to update features for.	required
feature	Feature	The feature to update.	required

Returns:

Type	Description
SoundEvent	The updated sound event.

Raises:

Type	Description
NotFoundError	If the sound event does not exist in the database.

update_geometric_features(session, sound_event) async

Update the geometric features of a sound event.

Parameters:

Name	Type	Description	Default
sound_event	SoundEvent	The sound event to update the geometric features for.	required

Returns:

Type	Description
SoundEvent	The updated sound event.

whombat.api.clips.ClipAPI()

Bases: BaseAPI[UUID, Clip, Clip, ClipCreate, ClipUpdate]

Functions

add_feature(session, obj, feature) async

Add feature to clip.

Parameters:

Name	Type	Description	Default
session	AsyncSession	Database session.	required
obj	Clip	Clip to add feature to.	required
feature	Feature	Feature to add to clip.	required

Returns:

Type	Description
Clip	Updated clip.

Raises:

Type	Description
NotFoundError	If clip does not exist.

create(session, recording, start_time, end_time, **kwargs) async

Create a clip.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
recording	Recording	The recording the clip belongs to.	required
start_time	float	The start time of the clip.	required
end_time	float	The end time of the clip.	required
**kwargs		Additional keyword arguments for creating the clip.	{}

Returns:

Name	Type	Description
clip	Clip	The created clip.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create clips without duplicates.

Parameters:

Name	Type	Description	Default
session	AsyncSession	Database session.	required
data	Sequence[dict]	List of clips to create.	required
return_all	bool	Whether to return all clips or only the created ones. Since some clips may already exist, this may not be the same.	False

Returns:

Type	Description
list[Clip]	Created clips.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create a clip from a soundevent Clip object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
data	Clip	The soundevent Clip object.	required

Returns:

Name	Type	Description
clip	Clip	The created clip.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_feature(session, obj, feature) async

Remove feature from clip.

Parameters:

Name	Type	Description	Default
session	AsyncSession	Database session.	required
obj	Clip	Clip to remove feature from.	required
feature	Feature	Feature to remove from clip.	required

Returns:

Type	Description
Clip	The updated clip.

Raises:

Type	Description
NotFoundError	Raised if clip does not exist in the database.

to_soundevent(obj, audio_dir=None)

Create a soundevent Clip object from a clip.

Parameters:

Name	Type	Description	Default
obj	Clip	The clip.	required

Returns:

Name	Type	Description
clip	Clip	The soundevent Clip object.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_feature(session, obj, feature) async

Update a feature value for a clip.

If the clip does not have the feature, it will be added.

Parameters:

Name	Type	Description	Default
session	AsyncSession	Database session.	required
obj	Clip	Clip to update feature for.	required
feature	Feature	Feature to update.	required

Returns:

Type	Description
Clip	The updated clip.

Raises:

Type	Description
NotFoundError	Raised if clip does not exist in the database.

whombat.api.sound_event_annotations.SoundEventAnnotationAPI()

Bases: BaseAPI[UUID, SoundEventAnnotation, SoundEventAnnotation, SoundEventAnnotationCreate, SoundEventAnnotationUpdate]

Functions

add_note(session, obj, note) async

Add a note to an annotation project.

add_tag(session, obj, tag, user=None) async

Add a tag to an annotation project.

create(session, sound_event, clip_annotation, created_by=None, **kwargs) async

Create a sound event annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
sound_event	SoundEvent	The sound event to annotate.	required
clip_annotation	ClipAnnotation	The clip annotation to add the annotation to.	required
created_by	SimpleUser | None	The user that created the annotation. Defaults to None.	None
**kwargs		Additional keyword arguments to use when creating the annotation, (e.g. uuid or created_on.)	{}

Returns:

Type	Description
SoundEventAnnotation	The created sound event annotation.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, clip_annotation) async

Get or create an annotation from a soundevent annotation.

If an annotation with the same UUID already exists, it will be updated with any tags or notes that are in the soundevent annotation but not in current state of the annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
data	SoundEventAnnotation	The sound event annotation to create the annotation from.	required
clip_annotation	ClipAnnotation	The clip annotation to add the annotation to.	required

Returns:

Type	Description
SoundEventAnnotation	The created annotation.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_annotation_task(session, data) async

Get the annotation task in which the sound event was annotated.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	SoundEventAnnotation	The sound event annotation.	required

Returns:

Type	Description
AnnotationTask	The annotation task for the sound event annotation.

get_clip_annotation(session, data) async

Get the clip annotation in which the sound event was annotated.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	SoundEventAnnotation	The sound event annotation.	required

Returns:

Type	Description
ClipAnnotation	The clip annotation for the sound event annotation.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_note(session, obj, note) async

Remove a note from an annotation project.

remove_tag(session, obj, tag) async

Remove a tag from an annotation project.

to_soundevent(session, annotation, audio_dir=None, recording=None) async

Convert an annotation to a soundevent annotation.

Parameters:

Name	Type	Description	Default
annotation	SoundEventAnnotation	The annotation to convert.	required

Returns:

Type	Description
SoundEventAnnotation	The soundevent annotation.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.clip_annotations.ClipAnnotationAPI()

Bases: BaseAPI[UUID, ClipAnnotation, ClipAnnotation, ClipAnnotationCreate, ClipAnnotationUpdate]

Functions

add_note(session, obj, note) async

Add a note to a clip annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	ClipAnnotation	The clip annotation to add the note to.	required
note	Note	The note to add.	required

Returns:

Type	Description
ClipAnnotation	The updated clip annotation.

Raises:

Type	Description
NotFoundError	If the clip annotation or note do not exist.

add_tag(session, obj, tag, user=None) async

Add a tag to a clip annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	ClipAnnotation	The clip annotation to add the tag to.	required
tag	Tag	The tag to add.	required
user	SimpleUser	The user adding the tag, by default None	None

Returns:

Type	Description
ClipAnnotation	The updated clip annotation.

Raises:

Type	Description
NotFoundError	If the clip annotation or tag do not exist.

create(session, clip, **kwargs) async

Create a clip annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
clip	Clip	The clip to annotate.	required
**kwargs		Additional keyword arguments to pass to the creation (e.g. uuid).	{}

Returns:

Type	Description
ClipAnnotation	The created clip annotation.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create multiple clip annotations.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	Sequence[dict]	A list of dictionaries containing the data need to create the clip annotations.	required

Returns:

Type	Description
list[ClipAnnotation]	The created clip annotations.

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create a clip annotation from a sound event.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	ClipAnnotation	The clip annotation to create.	required

Returns:

Type	Description
ClipAnnotation	The created clip annotation.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_annotation_task(session, data) async

Get the annotation task where the clip is the target.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
data	ClipAnnotation	The clip annotation to get the task for.	required

Returns:

Type	Description
AnnotationTask	The annotation task for the clip.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_note(session, obj, note) async

Remove a note from a clip annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	ClipAnnotation	The clip annotation to remove the note from.	required
note	Note	The note to remove.	required

Returns:

Type	Description
ClipAnnotation	The updated clip annotation.

Raises:

Type	Description
NotFoundError	If the clip annotation or note do not exist.

remove_tag(session, obj, tag) async

Remove a tag from a clip annotation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session.	required
obj	ClipAnnotation	The clip annotation to remove the tag from.	required
tag	Tag	The tag to remove.	required

Returns:

Type	Description
ClipAnnotation	The updated clip annotation.

Raises:

Type	Description
NotFoundError	If the clip annotation or tag do not exist.

to_soundevent(session, clip_annotation, audio_dir=None) async

Convert a clip annotation to a soundevent object.

Parameters:

Name	Type	Description	Default
clip_annotation	ClipAnnotation	The clip annotation to convert.	required

Returns:

Type	Description
ClipAnnotation	The converted object in the soundevent format.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.annotation_tasks.AnnotationTaskAPI()

Bases: BaseAPI[UUID, AnnotationTask, AnnotationTask, AnnotationTaskCreate, AnnotationTaskUpdate]

API for tasks.

Functions

add_status_badge(session, obj, state, user=None) async

Add a status badge to a task.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationTask	Task to add the status badge to.	required
state	AnnotationState	State of the status badge.	required
user	SimpleUser | None	User that owns the status badge.	None

Returns:

Type	Description
AnnotationTask	Task with the new status badge.

create(session, annotation_project, clip, **kwargs) async

Create a task.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
annotation_project	AnnotationProject	Annotation project to which the task belongs.	required
clip	Clip	Clip to annotate.	required
**kwargs		Additional keyword arguments to pass to the creation (e.g. uuid).	{}

Returns:

Type	Description
AnnotationTask	Created task.

create_clip_annotation(session, obj) async

Create a clip annotation for a task.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, annotation_project) async

Get or create a task from a soundevent task.

Parameters:

Name	Type	Description	Default
session	AsyncSession	An async database session.	required
data	AnnotationTask	The soundevent task.	required
annotation_project	AnnotationProject	The annotation project to which the task belongs.	required

Returns:

Type	Description
AnnotationTask	The created task.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip(session, obj) async

Get the clip of a task.

Parameters:

Name	Type	Description	Default
obj	AnnotationTask	The task.	required

Returns:

Type	Description
Clip	The clip of the task.

get_clip_annotation(session, obj) async

Get clip annotations for a task.

If the task does not have a clip annotation, one will be created.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationTask	Task for which to get the annotations.	required

Returns:

Type	Description
list[Annotation]	Annotations for the task.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_status_badge(session, obj, state) async

Remove a status badge from a task.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationTask	Task to remove the status badge from.	required
state	AnnotationState	The state of the status badge to remove.	required

Returns:

Type	Description
AnnotationTask	Task with the status badge removed.

to_soundevent(session, task, clip=None, audio_dir=None) async

Convert a task to a soundevent task.

Parameters:

Name	Type	Description	Default
task	AnnotationTask	The task to convert.	required

Returns:

Type	Description
AnnotationTask	The converted task.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.annotation_projects.AnnotationProjectAPI()

Bases: BaseAPI[UUID, AnnotationProject, AnnotationProject, AnnotationProjectCreate, AnnotationProjectUpdate]

Functions

add_tag(session, obj, tag) async

Add a tag to an annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationProject	Annotation project to add the tag to.	required
tag	Tag	Tag to add.	required

Returns:

Type	Description
AnnotationProject	Annotation project with the tag added.

create(session, name, description, annotation_instructions=None, **kwargs) async

Create an annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
name	str	Name of the annotation project.	required
description	str	Description of the annotation project.	required
annotation_instructions	str | None	Intructions for annotators on how to successfully annotate an annotation task. This is important for ensuring that annotations are consistent across annotators, and provides a unambiguous definition of what a completed annotation task should look like.	None
**kwargs		Additional keyword arguments to pass to the creation.	{}

Returns:

Type	Description
AnnotationProject	Created annotation project.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Convert a soundevent Annotation Project to a Whombat annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
data	AnnotationProject	soundevent annotation project.	required

Returns:

Type	Description
AnnotationProject	Whombat annotation project.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_annotations(session, obj, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get a list of annotations for an annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationProject	Annotation project to get annotations for.	required
limit	int	Maximum number of annotations to return. By default 1000.	1000
offset	int	Offset of the first annotation to return. By default 0.	0
filters	Sequence[Filter] | None	Filters to apply. Only annotations matching all filters will be returned. By default None.	None
sort_by	str | None	Field to sort by.	'-created_on'

Returns:

Name	Type	Description
annotations	list[ClipAnnotation]	List of clip annotations.
count	int	Total number of annotations matching the given criteria. This number may be larger than the number of annotations returned if limit is smaller than the total number of annotations matching the given criteria.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_tag(session, obj, tag) async

Remove a tag from an annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationProject	Annotation project to remove the tag from.	required
tag	Tag	Tag to remove.	required

Returns:

Type	Description
AnnotationProject	Annotation project with the tag removed.

to_soundevent(session, obj, audio_dir=None) async

Convert a Whombat annotation project to a soundevent annotation project.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
obj	AnnotationProject	Whombat annotation project.	required

Returns:

Type	Description
AnnotationProject	soundevent annotation project.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.sound_event_predictions.SoundEventPredictionAPI()

Bases: BaseAPI[UUID, SoundEventPrediction, SoundEventPrediction, SoundEventPredictionCreate, SoundEventPredictionUpdate]

Functions

add_tag(session, obj, tag, score) async

Add a tag to a sound event prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy database session.	required
obj	SoundEventPrediction	Sound event prediction to add the tag to.	required
tag	Tag	Tag to add.	required
score	float	Confidence score of the tag.	required

Returns:

Name	Type	Description
sound_event_prediction_tag	SoundEventPredictionTag	Updated sound event prediction.

create(session, sound_event, clip_prediction, score, **kwargs) async

Create a sound event prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
sound_event	SoundEvent	The sound event that was predicted.	required
clip_prediction	ClipPrediction	The clip prediction that this sound event prediction belongs to.	required
score	float	The confidence score of the prediction.	required
**kwargs		Additional keyword arguments to use when creating the sound event (e.g. uuid or created_on.)	{}

Returns:

Type	Description
SoundEventPrediction	Created sound event prediction.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, clip_prediction) async

Get the Whombat representation of a sound event prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy database session.	required
data	SoundEventPrediction	A sound event prediction in soundevent format.	required
clip_prediction	ClipPrediction	The clip prediction that the sound event prediction belongs to.	required

Returns:

Name	Type	Description
sound_event_prediction	SoundEventPrediction	The sound event prediction in Whombat format.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_tag(session, obj, tag) async

Remove a tag from a sound event prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy database session.	required
obj	SoundEventPrediction	Sound event prediction to remove the tag from.	required
tag	Tag	Tag to remove.	required

Returns:

Name	Type	Description
sound_event_prediction	SoundEventPrediction	The updated sound event prediction.

to_soundevent(session, sound_event_prediction, audio_dir=None, recording=None) async

Get the the sound event prediction in soundevent format.

Parameters:

Name	Type	Description	Default
sound_event_prediction	SoundEventPrediction	The sound event prediction to convert to soundevent format.	required

Returns:

Name	Type	Description
sound_event	SoundEventPrediction	The sound event prediction in soundevent format.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.clip_predictions.ClipPredictionAPI()

Bases: BaseAPI[UUID, ClipPrediction, ClipPrediction, ClipPredictionCreate, ClipPredictionUpdate]

Functions

add_tag(session, obj, tag, score) async

Add a tag to a clip prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession to use for the database connection.	required
obj	ClipPrediction	Clip prediction to add the tag to.	required
tag	Tag	Tag to add to the clip prediction.	required
score	float	Score of the tag.	required

Returns:

Name	Type	Description
clip_prediction	ClipPrediction	Clip prediction with the added tag.

create(session, clip, **kwargs) async

Create a clip prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
clip	Clip	Clip to create the clip prediction for.	required
**kwargs		Additional arguments to pass to the create method (e.g. uuid).	{}

Returns:

Type	Description
ClipPrediction	Created clip prediction.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create or update a clip prediction from an object in soundevent.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession to use for the database connection.	required
data	ClipPrediction	Data of the clip prediction to create or update in soundevent format.	required

Returns:

Name	Type	Description
clip_prediction	ClipPrediction	Created or updated clip prediction.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_tag(session, obj, tag) async

Remove a tag from a clip prediction.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession to use for the database connection.	required
obj	ClipPrediction	Clip prediction to remove the tag from.	required
tag	Tag	Tag to remove from the clip prediction.	required

Returns:

Name	Type	Description
clip_prediction	ClipPrediction	Clip prediction with the removed tag.

to_soundevent(session, clip_prediction, audio_dir=None) async

Convert a clip prediction to an object in soundevent format.

Parameters:

Name	Type	Description	Default
clip_prediction	ClipPrediction	Clip prediction to convert.	required

Returns:

Name	Type	Description
clip_prediction	ClipPrediction	Converted clip prediction.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

whombat.api.model_runs.ModelRunAPI()

Bases: BaseAPI[UUID, ModelRun, ModelRun, ModelRunCreate, ModelRunUpdate]

Functions

add_clip_prediction(session, obj, clip_prediction, raise_if_exists=False) async

create(session, name, version, description=None, **kwargs) async

Create a model run.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
name	str	The name of the model used to generate the predictions in this run.	required
version	str	The version of the model used to generate the predictions in this run.	required
description	str | None	A description of the model used to generate the predictions in this run.	None
**kwargs		Additional keyword arguments to use when creating the model run, (e.g. uuid or created_on.)	{}

Returns:

Type	Description
ModelRun	Created model run.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_predictions(session, obj, *, limit=1000, offset=0, filters=None, sort_by=None) async

get_evaluation(session, data, evaluation_set) async

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

to_soundevent(session, obj, audio_dir=None) async

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_from_soundevent(session, obj, data) async

whombat.api.user_runs.UserRunAPI()

Bases: BaseAPI[UUID, UserRun, UserRun, UserRunCreate, UserRunUpdate]

Functions

add_clip_prediction(session, obj, clip_prediction, raise_if_exists=False) async

create(session, user, **kwargs) async

Create a user run.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
user	SimpleUser	The user that created the run.	required
**kwargs		Additional keyword arguments to use when creating the user run, (e.g. uuid or created_on.)	{}

Returns:

Type	Description
UserRun	Created user run.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, user) async

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_predictions(session, obj, *, limit=1000, offset=0, filters=None, sort_by=None) async

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

to_soundevent(session, obj, audio_dir=None) async

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_from_soundevent(session, obj, data) async

whombat.api.sound_event_evaluations.SoundEventEvaluationAPI()

Bases: BaseAPI[UUID, SoundEventEvaluation, SoundEventEvaluation, SoundEventEvaluationCreate, SoundEventEvaluationUpdate]

API for sound event evaluations.

Functions

add_metric(session, obj, metric) async

Add a metric to a sound event evaluation.

create(session, clip_evaluation, affinity=0, score=0, source=None, target=None, **kwargs) async

Create a sound event evaluation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
clip_evaluation	ClipEvaluation	The clip evaluation that this sound event evaluation belongs to.	required
affinity	float	The geometric affinity between the source and target sound events regions of interest. Defaults to 0.	0
score	float	An overall score for the sound event evaluation. Defaults to 0.	0
source	SoundEventPrediction | None	The prediction being evaluated. Can be None if the target is not None, in which case no prediction was matched to the target, that is, this is a false negative.	None
target	SoundEventAnnotation | None	The annotation being evaluated. Can be None if the source is not None, in which case no annotation was matched to the source, that is, this is a false positive.	None
**kwargs		Additional keyword arguments to use when creating the sound event evaluation, (e.g. uuid or created_on.)	{}

Returns:

Type	Description
SoundEventEvaluation	Created sound event evaluation.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, clip_evaluation) async

Create a sound event evaluation from a sound event evaluation.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_metric(session, obj, metric) async

Remove a metric from a sound event evaluation.

to_soundevent(session, obj, audio_dir=None, recording=None) async

Convert a sound event evaluation to soundevent format.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_metric(session, obj, metric) async

Update a metric of a sound event evaluation.

whombat.api.clip_evaluations.ClipEvaluationAPI()

Bases: BaseAPI[UUID, ClipEvaluation, ClipEvaluation, ClipEvaluationCreate, ClipEvaluationUpdate]

API for clip evaluations.

Functions

add_metric(session, obj, metric) async

Add a metric to a clip evaluation.

create(session, evaluation, clip_annotation, clip_prediction, score=0, **kwargs) async

Create a clip evaluation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
evaluation	Evaluation	The evaluation to which the clip evaluation belongs.	required
clip_annotation	ClipAnnotation	The annotations used as ground truth.	required
clip_prediction	ClipPrediction	The predictions to evaluate.	required
score	float	An overall score for the clip evaluation.	0
**kwargs		Additional keyword arguments to pass at creation (e.g. uuid).	{}

Returns:

Type	Description
ClipEvaluation	Created clip evaluation.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data, evaluation) async

Create a clip evaluation from an object in soundevent format.

Parameters:

Name	Type	Description	Default
session	AsyncSession	An open database session.	required
data	ClipEvaluation	The clip evaluation in soundevent format.	required
evaluation	Evaluation	The evaluation to which the clip evaluation belongs.	required

Returns:

Type	Description
ClipEvaluation	The clip evaluation in whombat format.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_sound_event_evaluations(session, obj, *, limit=100, offset=0, filters=None, sort_by=None) async

Get the sound event evaluations of a clip evaluation.

remove_metric(session, obj, metric) async

Remove a metric from a clip evaluation.

to_soundevent(session, obj, audio_dir=None, evaluations=None) async

Create a clip evaluation in soundevent format from a clip evaluation in whombat format.

Parameters:

Name	Type	Description	Default
session	AsyncSession	An open database session.	required
obj	ClipEvaluation	The clip evaluation in whombat format.	required

Returns:

Type	Description
ClipEvaluation	The clip evaluation in soundevent format.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_metric(session, obj, metric) async

Update a metric of a clip evaluation.

whombat.api.evaluations.EvaluationAPI()

Bases: BaseAPI[UUID, Evaluation, Evaluation, EvaluationCreate, EvaluationUpdate]

API functions to interact with evaluations.

Functions

add_metric(session, obj, metric) async

Add a metric to an evaluation.

create(session, task, score=0, **kwargs) async

Create an evaluation.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
task	str	The evaluated task.	required

Returns:

Type	Description
Evaluation	Created evaluation.

Notes

The task parameter is a string that plays a crucial role in defining the machine learning context for the function evaluation. It represents the specific name of the machine learning task being assessed. This task name serves as a key identifier, indicating both the nature of the expected predictions and the criteria for evaluating their performance. Specifying the task is essential for providing clear and meaningful evaluations. Different machine learning tasks have distinct objectives, metrics, and criteria for success. Therefore, by explicitly defining the task, the function ensures that predictions are evaluated in a manner aligned with the specific requirements and expectations of that task. For example, the task parameter might be set to "clip classification," "sound event detection," or any other task type relevant to the machine learning model or user predictions.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

evaluate_model_run(session, model_run, evaluation_set, audio_dir) async

find(session, filters) async

from_soundevent(session, data) async

Create an evaluation from a sound event evaluation.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_evaluations(session, obj, *, limit=100, offset=0, filters=None, sort_by=None) async

Get clip evaluations of an evaluation.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

remove_metric(session, obj, metric) async

Remove a metric from an evaluation.

to_soundevent(session, obj, audio_dir=None) async

Create a sound event evaluation from an evaluation.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.

update_metric(session, obj, metric) async

Update a metric of an evaluation.

whombat.api.evaluation_sets.EvaluationSetAPI()

Bases: BaseAPI[UUID, EvaluationSet, EvaluationSet, EvaluationSetCreate, EvaluationSetUpdate]

Functions

add_annotation_tasks(session, obj, annotation_task_uuids) async

Add multiple annotation tasks to an evaluation set.

add_clip_annotation(session, obj, annotation) async

Add a clip annotation to an evaluation set.

add_model_run(session, obj, model_run) async

Add a model run to an evaluation set.

add_tag(session, obj, tag) async

Add a tag to an annotation project.

add_user_run(session, obj, user_run) async

Add a user run to an evaluation set.

create(session, name, description=None, task=PredictionTypes.sound_event_detection, **kwargs) async

Create an evaluation set.

Parameters:

Name	Type	Description	Default
session	AsyncSession	SQLAlchemy AsyncSession.	required
name	str	Name of the evaluation set.	required
description	str | None	A description of the evaluation set. Include information about how the evaluation set was created and what it is meant to be used for.	None
task	PredictionTypes	The task the evaluation set is used for. For example, Sound Event Detection.	sound_event_detection
**kwargs		Additional keyword arguments to pass to the create function.	{}

Returns:

Type	Description
EvaluationSet	Created evaluation set.

create_from_data(session, data=None, **kwargs) async

Create an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	CreateSchema | None	The data to use for creation of the object.	None
**kwargs		Additional keyword arguments to pass to the creation function.	{}

Returns:

Type	Description
WhombatSchema	The created object.

create_many(session, data) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required

create_many_without_duplicates(session, data, return_all=False) async

Create many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
data	Sequence[dict]	The data to use for creation of the objects.	required
return_all	bool	Whether to return all objects, or only those created.	False

Returns:

Type	Description
objs	Will only return the created objects, not the existing ones.

delete(session, obj) async

Delete an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to delete.	required

Returns:

Type	Description
obj	The deleted object.

find(session, filters) async

from_soundevent(session, data) async

Create an evaluation set from an object in soundevent format.

get(session, pk) async

Get an object by primary key.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The database session to use.	required
pk	PrimaryKey	The primary key.	required

Returns:

Type	Description
obj	The object with the given primary key.

Raises:

Type	Description
NotFoundError	If the object could not be found.

get_clip_annotations(session, obj, *, limit=100, offset=0, filters=None, sort_by='-created_on') async

Get all clip annotations in an evaluation set.

get_many(session, *, limit=1000, offset=0, filters=None, sort_by='-created_on') async

Get many objects.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
limit	int | None	The maximum number of objects to return, by default 1000	1000
offset	int | None	The offset to use, by default 0	0
filters	Sequence[Filter | _ColumnExpressionArgument] | None	A list of filters to apply, by default None	None
sort_by	_ColumnExpressionArgument | str | None	The column to sort by, by default None	'-created_on'

Returns:

Name	Type	Description
	objs	The objects.
count	int	The total number of objects. This is the number of objects that would have been returned if no limit or offset was applied.

get_model_runs(session, obj, *, limit=100, offset=0, filters=None, sort_by=None) async

Get all model runs in an evaluation set.

get_user_runs(session, obj, *, limit=100, offset=0, filters=None, sort_by=None) async

Get all user runs in an evaluation set.

remove_clip_annotation(session, obj, annotation) async

Remove a clip annotation from an evaluation set.

remove_model_run(session, obj, model_run) async

Remove a model run from an evaluation set.

remove_tag(session, obj, tag) async

Remove a tag from an annotation project.

remove_user_run(session, obj, user_run) async

Remove a user run from an evaluation set.

to_soundevent(session, obj, audio_dir=None) async

Create an object in soundevent format from an evaluation set.

update(session, obj, data) async

Update an object.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The SQLAlchemy AsyncSession of the database to use.	required
obj	WhombatSchema	The object to update.	required
data	UpdateSchema	The data to use for update.	required

Returns:

Type	Description
WhombatSchema	The updated object.