Python API - Whombat

Skip to content

# 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
--- | --- | --- | ---
`clip` |  | The clip to load audio from. | required
`start` | `int` | Start byte. | required
`end` |  | End byte. | required
`speed` | `float` | Speed of the audio. | `1`
`time_expansion` | `float` | Time expansion factor. | `1`
`start_time` | `float | None` | Start time in seconds. | `None`
`end_time` | `float | None` | End time in seconds. | `None`

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
`clips` |  | The clips to annotate. | required
`**kwargs` |  | Additional keyword arguments to pass to the creation (e.g. `uuid`). | 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
`user` | `SimpleUser` | If provided, will remove the tag only if it was created by the user, by default None | 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
`badge` |  | 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.