Models - Whombat

Skip to content

# Database Models

Welcome to the comprehensive database models reference for Whombat! Here, you'll discover an organized collection of all the database models defined within the Whombat framework. Our categorization mirrors the structure outlined in `soundevent`.

The models within Whombat share an analogical relationship with those in `soundevent` and are essentially a SQLAlchemy port. While the core concepts remain consistent, it's essential to note that some minor differences do exist.

## Data Descriptors

### Users

#### `` `whombat.models.User`

Bases: `Base`

User Model.

Represents a user in the system.

This model stores information about a user, including their email, hashed password, username, full name, and status (active, superuser, verified).

Notes

This class inherits from `SQLAlchemyBaseUserTableUUID` (provided by `fastapi-users`) which defines the `id`, `email`, `hashed_password`, `is_active`, and `is_superuser` attributes.

Important: Do not create instances of this class directly. Use the `create_user` function in the `whombat.api.users` module instead.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`email` | `str` | The email address of the user. | required
`hashed_password` | `str` | The hashed password of the user. | required
`username` | `str` | The username of the user. | required
`id` | `UUID` | Generate a random UUID. | `UUID('17342554-c755-4b19-9a9c-5a414fc90f4f')`
`name` | `str | None` | The full name of the user. | `None`
`is_active` | `bool` | Whether the user is active. | `True`
`is_superuser` | `bool` | Whether the user is a superuser. | `False`
`is_verified` | `bool` | Whether the user is verified. | `False`

Attributes:

Name | Type | Description
--- | --- | ---
`notes` | `list[ForwardRef(Note)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotation_tags` | `list[ForwardRef(SoundEventAnnotationTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`recordings` | `list[ForwardRef(Recording)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`recording_owner` | `list[ForwardRef(RecordingOwner)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`user_runs` | `list[ForwardRef(UserRun)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

### Tags

#### `` `whombat.models.Tag`

Bases: `Base`

Tag Model.

Represents a tag with a key-value structure.

Tags are used to categorize and annotate various elements, such as audio clips or sound events. The key-value structure provides a flexible way to organize and manage tags, with the "key" acting as a category or namespace and the "value" representing the specific tag within that category.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the tag.
`recordings` | `list[ForwardRef(Recording)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`recording_tags` | `list[ForwardRef(RecordingTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotations` | `list[ForwardRef(SoundEventAnnotation)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotation_tags` | `list[ForwardRef(SoundEventAnnotationTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_annotations` | `list[ForwardRef(ClipAnnotation)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_annotation_tags` | `list[ForwardRef(ClipAnnotationTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`evaluation_set_tags` | `list[ForwardRef(EvaluationSetTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`annotation_projects` | `list[ForwardRef(AnnotationProject)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`annotation_project_tags` | `list[ForwardRef(AnnotationProjectTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_prediction_tags` | `list[ForwardRef(SoundEventPredictionTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_prediction_tags` | `list[ForwardRef(ClipPredictionTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`key` | `str` | The key of the tag (e.g., "instrument", "genre", "mood"). This serves as a category or namespace for organizing tags. | required
`value` | `str` | The value of the tag (e.g., "guitar", "rock", "happy"). This represents the specific tag within the category defined by the key. | required

### Features

#### `` `whombat.models.FeatureName`

Bases: `Base`

Feature Name Model.

Represents the name of a feature.

Features are numerical values associated with sound events, clips, or recordings, providing additional information about these objects. This model stores the unique names of those features.

Features can represent various aspects:

- Sound Events: Duration, bandwidth, or other characteristics extracted via deep learning models.
- Clips: Acoustic properties like signal-to-noise ratio or acoustic indices.
- Recordings: Contextual information like temperature, wind speed, or recorder height.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the feature name
`recordings` | `list[ForwardRef(RecordingFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clips` | `list[ForwardRef(ClipFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_events` | `list[ForwardRef(SoundEventFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`name` | `str` | The feature name. | required

### Notes

#### `` `whombat.models.Note`

Bases: `Base`

Note model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the note (autogenerated).
`created_by` | `User` | The user who created the note.
`recording` | `ForwardRef(Recording) | None` |
`recording_note` | `ForwardRef(RecordingNote) | None` |
`sound_event_annotation` | `ForwardRef(SoundEventAnnotation) | None` |
`sound_event_annotation_note` | `ForwardRef(SoundEventAnnotationNote) | None` |
`clip_annotation` | `ForwardRef(ClipAnnotation) | None` |
`clip_annotation_note` | `ForwardRef(ClipAnnotationNote) | None` |

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | The textual message of the note. | required
`created_by_id` | `UUID` | The database id of the user who created the note. | required
`is_issue` | `bool` | Whether the note is an issue. | `False`
`uuid` | `UUID` | Generate a random UUID. | `UUID('3064b89d-b359-4cd4-a8d7-4c90076dad5b')`

## Audio Content

### Recordings

#### `` `whombat.models.Recording`

Bases: `Base`

Recording model for recording table.

This model represents the recording table in the database. It contains the all the information about a recording.

Notes

If the time expansion factor is not 1.0, the duration and samplerate are the duration and samplerate of original recording, not the expanded recording.

The path of the dataset is the path to the recording file relative to the base audio directory. We dont store the absolute path to the recording file in the database, as this may expose sensitive information, and it makes it easier to share datasets between users.

The hash of the recording is used to uniquely identify it. It is computed from the recording file, and is used to check if a recording has already been registered in the database. If the hash of a recording is already in the database, the recording is not registered again.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the recording (autogenerated).
`clips` | `list[ForwardRef(Clip)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`recording_datasets` | `list[ForwardRef(DatasetRecording)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('b05886a5-b80c-46ff-b527-6f9b6b274dc2')`
`hash` | `str` | The md5 hash of the recording. | required
`path` | `Path` | The path to the recording file relative to the base audio directory. | required
`duration` | `float` | The duration of the recording in seconds. | required
`samplerate` | `int` | The samplerate of the recording in Hz. | required
`channels` | `int` | The number of channels of the recording. | required
`date` | `date | None` | The date at which the recording was made. | `None`
`time` | `time | None` | The time at which the recording was made. | `None`
`latitude` | `float | None` | The latitude of the recording site. | `None`
`longitude` | `float | None` | The longitude of the recording site. | `None`
`time_expansion` | `float` | The time expansion factor of the recording. | `1.0`
`rights` | `str | None` | A string describing the usage rights of the recording. | `None`
`notes` | `list[Note]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`tags` | `list[Tag]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`features` | `list[ForwardRef(RecordingFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`owners` | `list[User]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`recording_notes` | `list[ForwardRef(RecordingNote)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`recording_tags` | `list[ForwardRef(RecordingTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`recording_owners` | `list[ForwardRef(RecordingOwner)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`

#### `` `whombat.models.RecordingTag`

Bases: `Base`

Recording Tag Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The id of the recording. | required
`tag_id` | `int` | The id of the tag. | required

Attributes:

Name | Type | Description
--- | --- | ---
`recording` | `Recording` | The recording to which the tag belongs.
`tag` | `Tag` | The tag associated with the recording.
`recording_uuid` | `AssociationProxy[UUID]` |

#### `` `whombat.models.RecordingNote`

Bases: `Base`

Recording Note Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The id of the recording. | required
`note_id` | `int` | The id of the note. | required

Attributes:

Name | Type | Description
--- | --- | ---
`recording` | `Recording` | The recording to which the note belongs.
`note` | `Note` | The note associated with the recording.

#### `` `whombat.models.RecordingFeature`

Bases: `Base`

Recording Feature Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The id of the recording. | required
`feature_name_id` | `int` | The id of the feature name. | required
`value` | `float` | The value of the feature. | required

Attributes:

Name | Type | Description
--- | --- | ---
`name` | `AssociationProxy[str]` | The name of the feature.
`recording` | `Recording` |
`feature_name` | `FeatureName` |

#### `` `whombat.models.RecordingOwner`

Bases: `Base`

RecordingOwner model for recording_owner table.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The id of the recording. | required
`user_id` | `UUID` | The id of the user. | required

Attributes:

Name | Type | Description
--- | --- | ---
`recording` | `Recording` | The recording being owned.
`user` | `User` | The user owning the recording.

### Datasets

#### `` `whombat.models.Dataset`

Bases: `Base`

Dataset model for dataset table.

Notes

The `audio_dir` attribute is the path to the audio directory of the dataset. This is the directory that contains all the recordings of the dataset. Only the relative path to the base audio directory is stored in the database. Note that we should NEVER store absolute paths in the database.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the dataset.
`recordings` | `list[Recording]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`dataset_recordings` | `list[ForwardRef(DatasetRecording)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('9a97aca2-f1c9-40c5-a94b-11a3e029b8c3')`
`name` | `str` | The name of the dataset. | required
`description` | `str` | A textual description of the dataset. | required
`audio_dir` | `Path` | The path to the audio directory of the dataset. | required

#### `` `whombat.models.DatasetRecording`

Bases: `Base`

Dataset Recording Model.

A dataset recording is a link between a dataset and a recording. It contains the path to the recording within the dataset.

Notes

The dataset recording model is a many-to-many relationship between the dataset and recording models. This means that a recording can be part of multiple datasets. This is useful when a recording is used in multiple studies or deployments. However, as we do not want to duplicate recordings in the database, we use a many-to-many relationship to link recordings to datasets.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`dataset_id` | `int` | The id of the dataset. | required
`recording_id` | `int` | The id of the recording. | required
`path` | `Path` | The path to the recording within the dataset. | required

Attributes:

Name | Type | Description
--- | --- | ---
`dataset` | `Dataset` |
`recording` | `Recording` |

## Acoustic Objects

### Sound Events

#### `` `whombat.models.SoundEvent`

Bases: `Base`

Sound Event model.

Notes

The geometry attribute is stored as a JSON string in the database.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the sound event.
`recording` | `Recording` | The recording to which the sound event belongs.
`features` | `list[ForwardRef(SoundEventFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotation` | `ForwardRef(SoundEventAnnotation) | None` |
`sound_event_prediction` | `ForwardRef(SoundEventPrediction) | None` |

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('8245e270-e432-4da1-bf98-42139adeaeb1')`
`recording_id` | `int` | The id of the recording to which the sound event belongs. | required
`geometry_type` | `str` | The type of geometry used to mark the RoI of the sound event. | required
`geometry` | `TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon` | The geometry of the mark used to mark the RoI of the sound event. | required

#### `` `whombat.models.SoundEventFeature`

Bases: `Base`

Sound Event Feature model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_id` | `int` | The id of the sound event. | required
`feature_name_id` | `int` | The id of the feature name. | required
`value` | `float` | The value of the feature. | required

Attributes:

Name | Type | Description
--- | --- | ---
`name` | `AssociationProxy[str]` | The name of the feature.
`sound_event` | `SoundEvent` |
`feature_name` | `FeatureName` |

### Clips

#### `` `whombat.models.Clip`

Bases: `Base`

Clip Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the clip.
`recording` | `Recording` | The recording to which the clip belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('93dbe72f-9efb-42f7-8c14-5a9ab6ae31e8')`
`recording_id` | `int` | The database id of the recording to which the clip belongs. | required
`start_time` | `float` | The start time of the clip in seconds. | required
`end_time` | `float` | The end time of the clip in seconds. | required
`features` | `list[ForwardRef(ClipFeature)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`

#### `` `whombat.models.ClipFeature`

Bases: `Base`

Clip Feature Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_id` | `int` | The database id of the clip to which the feature belongs. | required
`feature_name_id` | `int` | The database id of the feature name of the feature. | required
`value` | `float` | The value of the feature. | required

Attributes:

Name | Type | Description
--- | --- | ---
`name` | `AssociationProxy[str]` | The name of the feature.
`feature_name` | `FeatureName` |
`clip` | `Clip` |

## Annotation

### Sound Event Annotation

#### `` `whombat.models.SoundEventAnnotation`

Bases: `Base`

Sound Event Annotation model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation.
`clip_annotation` | `ForwardRef(ClipAnnotation)` | The clip annotation to which the annotation belongs.
`created_by` | `User | None` | The user who created the annotation.
`sound_event` | `SoundEvent` | The sound event annotated by the annotation.
`tags` | `list[Tag]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`notes` | `list[Note]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotation_notes` | `list[ForwardRef(SoundEventAnnotationNote)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_event_annotation_tags` | `list[ForwardRef(SoundEventAnnotationTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('0860fb6f-f8f0-4f4b-b30e-06f5ea526d8a')`
`clip_annotation_id` | `int` | The id of the clip annotation to which the annotation belongs. | required
`created_by_id` | `int | None` | The id of the user who created the annotation. | required
`sound_event_id` | `int` | The id of the sound event annotated by the annotation. | required

#### `` `whombat.models.SoundEventAnnotationTag`

Bases: `Base`

Annotation tag model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation tag.
`sound_event_annotation` | `SoundEventAnnotation` | The annotation to which the annotation tag belongs.
`tag` | `Tag` | The tag attached to the annotation.
`created_by` | `User | None` | The user who created the annotation.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_annotation_id` | `int` | The id of the annotation to which the annotation tag belongs. | required
`tag_id` | `int` | The id of the tag attached to the annotation. | required
`created_by_id` | `int | None` | The id of the user who created the annotation. | required

#### `` `whombat.models.SoundEventAnnotationNote`

Bases: `Base`

Sound Event Annotation Note Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_annotation_id` | `int` | The id of the annotation to which the note belongs. | required
`note_id` | `int` | The id of the note associated with the annotation. | required

Attributes:

Name | Type | Description
--- | --- | ---
`sound_event_annotation` | `SoundEventAnnotation` | The annotation to which the note belongs to.
`note` | `Note` | The note associated with the annotation.

### Clip Annotation

#### `` `whombat.models.ClipAnnotation`

Bases: `Base`

Clip Annotation Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation.
`clip` | `Clip` | The clip being annotated.
`sound_events` | `list[SoundEventAnnotation]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`tags` | `list[Tag]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`notes` | `list[Note]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_annotation_notes` | `list[ForwardRef(ClipAnnotationNote)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_annotation_tags` | `list[ForwardRef(ClipAnnotationTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`annotation_task` | `ForwardRef(AnnotationTask)` |
`evaluation_sets` | `list[ForwardRef(EvaluationSet)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`evaluation_set_annotations` | `list[ForwardRef(EvaluationSetAnnotation)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('318473d4-d82f-401c-b260-e65e8ad6c7ee')`
`clip_id` | `int` | The database id of the clip being annotated. | required

#### `` `whombat.models.ClipAnnotationTag`

Bases: `Base`

Clip Annotation Tag Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation tag.
`tag` | `Tag` | The tag attached to the annotation.
`created_by` | `User | None` | The user who tagged the annotation.
`clip_annotation` | `ClipAnnotation` | The annotation being tagged.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_annotation_id` | `int` | The database id of the annotation to which the tag belongs | required
`tag_id` | `int` | The database id of the tag attached to the annotation. | required
`created_by_id` | `int | None` | The database id of the user who tagged the annotation. | required

#### `` `whombat.models.ClipAnnotationNote`

Bases: `Base`

Clip Annotation Note Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation note.
`clip_annotation` | `ClipAnnotation` | The annotation to which the note belongs to.
`note` | `Note` | The note associated with the annotation.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_annotation_id` | `int` | The database id of the annotation to which the note belongs. | required
`note_id` | `int` | The database id of the note attached to the annotation. | required

### Annotation Task

#### `` `whombat.models.AnnotationTask`

Bases: `Base`

Annotation Task model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the task.
`annotation_project` | `ForwardRef(AnnotationProject)` | The project to which the task belongs.
`clip` | `Clip` | The clip that needs to be annotated to complete this task.
`clip_annotation` | `ClipAnnotation` | The annotations of the clip this task pertains to.
`status_badges` | `list[ForwardRef(AnnotationStatusBadge)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`annotation_project_id` | `int` | The id of the project to which the task belongs. | required
`clip_id` | `int` | The id of the clip to be annotated. | required
`clip_annotation_id` | `int` | The id of the annotation created for the task. | required
`uuid` | `UUID` | Generate a random UUID. | `UUID('d346cda9-9354-4705-b7b4-f91228d4f08e')`

#### `` `whombat.models.AnnotationStatusBadge`

Bases: `Base`

Annotation status badge model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the status badge.
`annotation_task` | `AnnotationTask` | The task to which the status badge belongs.
`user` | `User | None` | The user to whom the status badge refers.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`annotation_task_id` | `int` | The id of the task to which the status badge belongs. | required
`user_id` | `UUID | None` | The id of the user to whom the status badge refers. | required
`state` | `AnnotationState` | The state of annotation attached to the badge. | required

### Annotation Project

#### `` `whombat.models.AnnotationProject`

Bases: `Base`

Annotation Project model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the annotation project.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('8ced5c27-6982-4d93-8e56-825deed70c94')`
`name` | `str` | The name of the annotation project. | required
`description` | `str` | The description of the annotation project. | required
`annotation_instructions` | `str | None` | The instructions for annotators. | `None`
`tags` | `list[Tag]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`annotation_tasks` | `list[ForwardRef(AnnotationTask)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`annotation_project_tags` | `list[ForwardRef(AnnotationProjectTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`

#### `` `whombat.models.AnnotationProjectTag`

Bases: `Base`

Annotation Project Tag model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`annotation_project_id` | `int` | The database id of the annotation project associated with the tag. | required
`tag_id` | `int` | The database id of the tag. | required

Attributes:

Name | Type | Description
--- | --- | ---
`annotation_project` | `AnnotationProject` | The annotation project associated with the tag.
`tag` | `Tag` | The tag associated with the annotation project.

## Prediction

### Sound Event Prediction

#### `` `whombat.models.SoundEventPrediction`

Bases: `Base`

Predicted Sound Event model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`id` | `int` | The database id of the sound event prediction. | required
`uuid` | `UUID` | Generate a random UUID. | `UUID('0cd48d02-7bcd-48ce-89e8-557959ba8f02')`
`sound_event_id` | `int` | The database id of the predicted sound event. | required
`clip_prediction_id` | `int` | The database id of the clip prediction to which the sound event belongs. | required
`score` | `float` | The confidence score assigned to the sound event prediction. The confidence score assigned to the sound event prediction reflects the model's confidence in the presence and location of the sound event, but not in its identification. The individual score in each predicted tag provides the confidence in the identification. | required

Attributes:

Name | Type | Description
--- | --- | ---
`sound_event` | `SoundEvent` | The sound event being predicted.
`clip_prediction` | `ForwardRef(ClipPrediction)` | The clip prediction to which the sound event prediction belongs.
`tags` | `list[ForwardRef(SoundEventPredictionTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

#### `` `whombat.models.SoundEventPredictionTag`

Bases: `Base`

Sound Event Prediction Tag model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_prediction_id` | `int` | The database id of the sound event prediction associated with the | required
`tag_id` | `int` | The database id of the tag associated with the sound event. | required
`score` | `float` | The confidence score assigned to the tag. | `1.0`

Attributes:

Name | Type | Description
--- | --- | ---
`tag` | `Tag` | The tag associated with the sound event prediction.

### Clip Prediction

#### `` `whombat.models.ClipPrediction`

Bases: `Base`

Prediction Clip model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`id` | `int` | The database id of the clip prediction. | required
`uuid` | `UUID` | Generate a random UUID. | `UUID('353653fd-abf5-47f8-a2c3-8688d24f0645')`
`clip_id` | `int` | The database id of the clip to which the prediction belongs. | required

Attributes:

Name | Type | Description
--- | --- | ---
`clip` | `Clip` | The clip over which the predictions were made.
`tags` | `list[ForwardRef(ClipPredictionTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`sound_events` | `list[SoundEventPrediction]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

#### `` `whombat.models.ClipPredictionTag`

Bases: `Base`

Clip Prediction Tag model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_prediction_id` | `int` | The database id of the clip prediction associated with the tag. | required
`tag_id` | `int` | The database id of the tag associated with the clip prediction. | required
`score` | `float` | The confidence score of the prediction tag. The confidence score of the prediction tag represents the predictors's confidence in the assignment of this tag to the clip. The score is a number between 0 and 1, where 1 is the highest confidence and 0 is the lowest. | `1.0`

Attributes:

Name | Type | Description
--- | --- | ---
`tag` | `Tag` | The tag associated with the clip prediction.

### Model Run

#### `` `whombat.models.ModelRun`

Bases: `Base`

Model Run Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the model run.
`clip_predictions` | `list[ClipPrediction]` | List of the predictions made during the model run.
`evaluations` | `list[Evaluation]` | List of evaluations for the model run.
`model_run_predictions` | `list[ForwardRef(ModelRunPrediction)]` |
`model_run_evaluations` | `list[ForwardRef(ModelRunEvaluation)]` |
`evaluation_sets` | `list[ForwardRef(EvaluationSet)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`evaluation_set_model_runs` | `list[ForwardRef(EvaluationSetModelRun)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('d7beabf7-75c0-4dfe-93f2-5232a7b2d563')`
`name` | `str` | The name of the model used to generate the predictions. | required
`version` | `str` | The version of the model used to generate the predictions. | required
`description` | `str` | The description of the model. | required

### User Run

#### `` `whombat.models.UserRun`

Bases: `Base`

User Run User.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the user run.
`user` | `ForwardRef(User)` | The user who created the user run.
`clip_predictions` | `list[ClipPrediction]` | The list of clip predictions made by the user.
`evaluations` | `list[Evaluation]` | List of evaluations for the user run.
`user_run_predictions` | `list[ForwardRef(UserRunPrediction)]` |
`user_run_evaluations` | `list[ForwardRef(UserRunEvaluation)]` |
`evaluation_sets` | `list[ForwardRef(EvaluationSet)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`evaluation_set_user_runs` | `list[ForwardRef(EvaluationSetUserRun)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('b351e949-50fa-4bdd-a1e8-dbf31d890d98')`
`user_id` | `int` | The database id of the user who created the user run. | required

## Evaluation

### Sound Event Evaluation

#### `` `whombat.models.SoundEventEvaluation`

Bases: `Base`

Sound Event Evaluation.

Represents the evaluation of a predicted sound event against a ground truth annotation.

This class stores the results of comparing a predicted sound event (from a model or user) to a corresponding annotated sound event (ground truth). It includes various metrics and scores to quantify the accuracy of the prediction.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the sound event evaluation.
`source` | `SoundEventPrediction | None` | The predicted sound event object.
`target` | `SoundEventAnnotation | None` | The target (ground truth) sound event annotation object.
`metrics` | `list[ForwardRef(SoundEventEvaluationMetric)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`clip_evaluation` | `ForwardRef(ClipEvaluation)` |

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('fe76d0df-94f5-4172-b9f7-f9941dccd52d')`
`clip_evaluation_id` | `int` | The ID of the clip evaluation to which this evaluation belongs. | required
`source_id` | `int | None` | The id of the predicted sound event. | required
`target_id` | `int | None` | The ID of the target (ground truth) sound event annotation. | required
`affinity` | `float` | The affinity score between the prediction and the ground truth. This score measures the geometric similarity between the predicted and true sound event regions, without considering semantic information. | required
`score` | `float` | The overall score of the match between prediction and ground truth. | required

#### `` `whombat.models.SoundEventEvaluationMetric`

Bases: `Base`

Sound Event Evaluation Metric model.

Represents a specific metric used to evaluate a sound event prediction.

This class stores the value of a single evaluation metric (e.g., precision, recall, F1-score) calculated for a SoundEventEvaluation. It links the metric value to its name (stored in the FeatureName table) and the corresponding evaluation.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the metric.
`name` | `AssociationProxy[str]` | The name of the metric (accessed via the FeatureName relationship).
`feature_name` | `FeatureName` | The FeatureName object associated with this metric.
`sound_event_evaluation` | `SoundEventEvaluation` | The SoundEventEvaluation object to which this metric belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_evaluation_id` | `int` | The ID of the sound event evaluation to which this metric belongs. | required
`feature_name_id` | `int` | The ID of the feature name associated with this metric. | required
`value` | `float` | The value of the metric. | required

### Clip Evaluation

#### `` `whombat.models.ClipEvaluation`

Bases: `Base`

Clip Evaluation Model.

Represents the evaluation of a clip-level prediction against ground truth.

This class compares a prediction made on an audio clip to the corresponding ground truth annotation for that clip. It considers both clip-level tags and sound event predictions within the clip, providing an overall score and detailed metrics for the evaluation.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the clip evaluation.
`clip_annotation` | `ClipAnnotation` | The ground truth clip annotation object.
`clip_prediction` | `ClipPrediction` | The clip prediction object.
`sound_event_evaluations` | `list[SoundEventEvaluation]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`metrics` | `list[ForwardRef(ClipEvaluationMetric)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
`evaluation` | `ForwardRef(Evaluation)` | The overall evaluation object to which this clip evaluation belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('c1466904-4665-4ee5-b572-57c86dbec125')`
`evaluation_id` | `int` | The ID of the overall evaluation to which this clip evaluation belongs. | required
`clip_annotation_id` | `int` | The ID of the ground truth clip annotation. | required
`clip_prediction_id` | `int` | The ID of the clip prediction. | required
`score` | `float` | The overall score of the clip prediction. | required

#### `` `whombat.models.ClipEvaluationMetric`

Bases: `Base`

Clip Evaluation Metric.

Represents a specific metric used to evaluate a clip-level prediction.

This class stores the value of a single evaluation metric (e.g., accuracy, precision, recall) calculated for a ClipEvaluation. It links the metric value to its name (stored in the FeatureName table) and the corresponding clip evaluation.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the metric.
`name` | `AssociationProxy[str]` | The name of the metric (accessed via the FeatureName relationship).
`feature_name` | `FeatureName` | The FeatureName object associated with this metric.
`clip_evaluation` | `ClipEvaluation` | The clip evaluation to which the metric belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_evaluation_id` | `int` | The ID of the clip evaluation to which this metric belongs. | required
`feature_name_id` | `int` | The ID of the feature name associated with this metric. | required
`value` | `float` | The value of the metric. | required

### Evaluation

#### `` `whombat.models.Evaluation`

Bases: `Base`

Evaluation.

Represents a complete evaluation of a model's predictions.

This class stores high-level information about the evaluation of a set of predictions compared to ground truth annotations. It includes an overall score, aggregated metrics, and a breakdown of individual clip evaluations. This provides a comprehensive overview of the model's performance on a specific task (e.g., sound event detection).

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the evaluation.
`metrics` | `list[ForwardRef(EvaluationMetric)]` | A list of metrics associated with the overall evaluation.
`clip_evaluations` | `list[ClipEvaluation]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('50737449-64b6-448f-a1be-7c4921294e36')`
`task` | `str` | The specific task that was evaluated (e.g., 'sound_event_detection'). | required
`score` | `float` | The overall score of the evaluation. | `0`

#### `` `whombat.models.EvaluationMetric`

Bases: `Base`

Evaluation Metric.

Represents a specific metric associated with an overall evaluation.

This class stores the value of an evaluation metric (e.g., overall accuracy, macro F1-score) calculated for an Evaluation. It links the metric value to its name (from the FeatureName table) and the corresponding evaluation, providing insights into the model's performance on a broader level.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the metric.
`name` | `AssociationProxy[str]` | The name of the metric (accessed via the FeatureName relationship).
`feature_name` | `FeatureName` | The FeatureName object associated with this metric.
`evaluation` | `Evaluation` | The Evaluation object to which this metric belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_id` | `int` | The ID of the evaluation to which this metric belongs. | required
`feature_name_id` | `int` | The ID of the feature name associated with this metric. | required
`value` | `float` | The value of the metric. | required

### Evaluation Set

#### `` `whombat.models.EvaluationSet`

Bases: `Base`

Evaluation Set Model.

Represents a collection of data and settings for evaluating model predictions.

An EvaluationSet defines the parameters and data required for a specific evaluation task. It includes:

1. Target Tags: The list of sound tags that are the focus of the evaluation.
2. Prediction Task: The type of prediction being evaluated (e.g., sound event detection).
3. Ground Truth Examples: A set of clip annotations serving as the ground truth for comparison.

This allows for structured and standardized evaluation of different models and prediction types.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database ID of the evaluation set.
`clip_annotations` | `list[ForwardRef(ClipAnnotation)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`uuid` | `UUID` | Generate a random UUID. | `UUID('61c1b59e-bef0-4a45-bc88-c548cbae1b03')`
`name` | `str` | A unique name for the evaluation set. | required
`description` | `str` | A description of the evaluation set. | required
`task` | `str` | The type of prediction task being evaluated. For example: 'sound_event_detection', 'acoustic_scene_classification', etc. | required
`tags` | `list[Tag]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`model_runs` | `list[ModelRun]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`user_runs` | `list[UserRun]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`evaluation_set_annotations` | `list[ForwardRef(EvaluationSetAnnotation)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`evaluation_set_tags` | `list[ForwardRef(EvaluationSetTag)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`evaluation_set_model_runs` | `list[ForwardRef(EvaluationSetModelRun)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`
`evaluation_set_user_runs` | `list[ForwardRef(EvaluationSetUserRun)]` | Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. | `<dynamic>`

#### `` `whombat.models.EvaluationSetTag`

Bases: `Base`

Evaluation Set Tag model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_set_id` | `int` |  | required
`tag_id` | `int` |  | required

Attributes:

Name | Type | Description
--- | --- | ---
`evaluation_set` | `EvaluationSet` |
`tag` | `Tag` |

#### `` `whombat.models.EvaluationSetAnnotation`

Bases: `Base`

Evaluation Set Annotation Model.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_set_id` | `int` |  | required
`clip_annotation_id` | `int` |  | required

Attributes:

Name | Type | Description
--- | --- | ---
`evaluation_set` | `EvaluationSet` |
`clip_annotation` | `ClipAnnotation` |