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`

Model for a user.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[UUID]` | The unique identifier for the user.
`email` | `Mapped[str]` | The email address of the user.
`hashed_password` | `Mapped[str]` | The hashed password of the user.
`username` | `Mapped[str]` | The username of the user.
`name` | `Mapped[Optional[str]]` | The full name of the user.
`is_active` | `Mapped[bool]` | Whether the user is active. Inactive users cannot log in.
`is_superuser` | `Mapped[bool]` | Whether the user is a superuser. Superusers have all permissions.
`is_verified` | `Mapped[bool]` | Whether the user is verified.

Notes

We are using the fastapi-users package to handle user authentication. This package is built on top of SQLAlchemy. The User class inherits from the SQLAlchemyBaseUserTableUUID class, which provides the id, email, hashed_password, is_active, and is_superuser attributes. The username and name attribute is added to the User class.

Do not instantiate this class directly. Instead, use the create_user function of the `whombat.api.users` module.

### Tags

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

Bases: `Base`

Tag model for tag table.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the tag.
`key` | `Mapped[str]` | The key of the tag. The key serves as a way to group tags into coherent categories, similar to a namespace.
`value` | `Mapped[str]` | The value of the tag, the actual content of the tag.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`key` | `str` | The key of the tag. | required
`value` | `str` | The value of the tag. | required

### Features

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

Bases: `Base`

Feature model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the feature name.
`name` | `Mapped[str]` | The feature name.

Parameters:

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

### Notes

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

Bases: `Base`

Note model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the note.
`uuid` | `Mapped[UUID]` | The UUID of the note.
`message` | `Mapped[str]` | Textual message of the note.
`is_issue` | `Mapped[bool]` | Whether the note is an issue.
`created_by` | `Mapped[User]` | The user who created the note.
`created_on` |  | The date and time when the note was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message` | `str` | Textual message of the note. | required
`is_issue` | `bool` | Whether the note is an issue. Defaults to False. | required
`created_by_id` | `int` | The database id of the user who created the note. | required
`uuid` | `UUID` | The UUID of the note. | required

## 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.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the recording.
`uuid` | `Mapped[UUID]` | The UUID of the recording.
`hash` | `Mapped[str]` | The md5 hash of the recording.
`path` | `Mapped[Path]` | The path of the dataset, relative to the base audio directory.
`duration` | `Mapped[float]` | The duration of the recording in seconds.
`samplerate` | `Mapped[int]` | The samplerate of the recording in Hz.
`channels` | `Mapped[int]` | The number of channels of the recording.
`date` | `Mapped[date | None]` | The date at which the recording was made.
`time` | `Mapped[time | None]` | The time at which the recording was made.
`latitude` | `Mapped[float | None]` | The latitude of the recording site.
`longitude` | `Mapped[float | None]` | The longitude of the recording site.
`time_expansion` | `Mapped[float]` | The time expansion factor of the recording.
`rights` | `Mapped[str | None]` | A string describing the usage rights of the recording.

Notes

    A list of notes associated with the recording.

tags A list of tags associated with the recording. features A list of features associated with the recording. owners The list of users who have ownership over the recording.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `Path` | The path to the recording file relative to the base audio directory. | required
`hash` | `str` | The md5 hash of the recording. If not provided, it is computed from the recording file. | 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` | The date at which the recording was made. | required
`time` | `time` | The time at which the recording was made. | required
`latitude` | `float` | The latitude of the recording site. | required
`longitude` | `float` | The longitude of the recording site. | required
`time_expansion` | `float` | The time expansion factor of the recording. Defaults to 1.0. | required
`rights` | `str` | A string describing the usage rights of the recording. | required

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.

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

Bases: `Base`

Recording Tag Model.

Attributes:

Name | Type | Description
--- | --- | ---
`tag` | `Mapped[Tag]` | The tag associated with the recording.
`created_on` |  | The date and time at which the tag was created.

Parameters:

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

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

Bases: `Base`

Recording Note Model.

Attributes:

Name | Type | Description
--- | --- | ---
`note` | `Mapped[Note]` | The note associated with the recording.
`created_on` |  | The date and time at which the note was created.

Parameters:

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

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

Bases: `Base`

Recording Feature Model.

Attributes:

Name | Type | Description
--- | --- | ---
`feature_name` | `Mapped[FeatureName]` | The name of the feature.
`value` | `Mapped[float]` | The value of the feature.
`created_on` |  | The date and time at which the feature was created.

Parameters:

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

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

Bases: `Base`

RecordingOwner model for recording_owner table.

Attributes:

Name | Type | Description
--- | --- | ---
`user` | `Mapped[User]` | The user who owns the recording.
`created_on` |  | The date and time at which the user became the owner of the recording.

Parameters:

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

### Datasets

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

Bases: `Base`

Dataset model for dataset table.

This model represents the dataset table in the database.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the dataset.
`uuid` | `Mapped[UUID]` | The UUID of the dataset.
`name` | `Mapped[str]` | The name of the dataset.
`description` | `Mapped[str]` | A textual description of the dataset.
`audio_dir` | `Mapped[Path]` | The path to the audio directory of the dataset.
`created_on` |  | The date and time the dataset was created.
`recording_count` |  | The number of recordings associated with the dataset.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`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
`uuid` | `UUID` | The UUID of the dataset. If not provided, a new UUID will be generated. | required

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.

#### `` `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.

Attributes:

Name | Type | Description
--- | --- | ---
`path` | `Mapped[Path]` | The path to the recording within the dataset.
`recording` | `Mapped[Recording]` | The recording.
`created_on` |  | The date and time the dataset recording was created.

Parameters:

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

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.

## Acoustic Objects

### Sound Events

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

Bases: `Base`

Sound Event model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the sound event.
`uuid` | `Mapped[UUID]` | The UUID of the sound event.
`geometry_type` | `Mapped[str]` | The type of geometry used to mark the RoI of the sound event.
`geometry` | `Mapped[Geometry]` | The geometry of the mark used to mark the RoI of the sound event.
`features` | `Mapped[list[SoundEventFeature]]` | A list of features associated with the sound event.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The id of the recording to which the sound event belongs. | required
`geometry` | `Geometry` | The geometry of the mark used to mark the RoI of the sound event. | required
`uuid` | `UUID` | The UUID of the sound event. If not provided, a new UUID will be generated. | required

Notes

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

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

Bases: `Base`

Sound Event Feature model.

Attributes:

Name | Type | Description
--- | --- | ---
`feature_name` | `Mapped[FeatureName]` | The name of the feature.
`value` | `Mapped[float]` | The value of the feature.

Parameters:

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

### Clips

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

Bases: `Base`

Clip Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the clip.
`uuid` | `Mapped[UUID]` | The UUID of the clip.
`start_time` | `Mapped[float]` | The start time of the clip in seconds.
`end_time` | `Mapped[float]` | The end time of the clip in seconds.
`recording` | `Mapped[Recording]` | The recording to which the clip belongs.
`features` | `Mapped[list[ClipFeature]]` | A list of features associated with the clip.
`created_on` |  | The date and time the clip was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`recording_id` | `int` | The database id of the recording to which the clip belongs. | required
`start_time` | `float` | Start time of the clip in seconds, with respect to the start of the recording. | required
`end_time` | `float` | End time of the clip in seconds, with respect to the start of the recording. | required
`uuid` | `UUID` | The UUID of the clip. | required

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

Bases: `Base`

Clip Feature Model.

Attributes:

Name | Type | Description
--- | --- | ---
`value` | `float` | The value of the feature.
`feature_name` | `FeatureName` | The name of the feature.

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. | required
`value` | `float` | The value of the feature. | required

## Annotation

### Sound Event Annotation

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

Bases: `Base`

Annotation model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the annotation.
`uuid` | `Mapped[UUID]` | The UUID of the annotation.
`created_by` | `Mapped[Optional[User]]` | The user who created the annotation.
`sound_event` | `Mapped[SoundEvent]` | The sound event annotated by the annotation.
`tags` | `Mapped[list[Tag]]` | A list of tags associated with the annotation.

Notes

    A list of notes associated with the annotation.

clip_annotation The clip annotation to which the annotation belongs.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_id` | `int` | The id of the sound event annotated by the annotation. | required
`clip_annotation_id` | `int` | The id of the clip annotation to which the annotation belongs. | required
`created_by_id` | `int` | The id of the user who created the annotation. | required
`uuid` | `UUID` | The UUID of the annotation. If not provided, a new UUID will be generated. | required

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

Bases: `Base`

Annotation tag model.

Attributes:

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

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` | The id of the user who created the annotation tag. | required

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

Bases: `Base`

Sound Event Annotation Note Model.

Attributes:

Name | Type | Description
--- | --- | ---
`note` | `Mapped[Note]` | The note associated with the annotation.
`created_on` |  | The date and time when the note was created.

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

### Clip Annotation

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

Bases: `Base`

Clip Annotation Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the annotation.
`uuid` | `Mapped[UUID]` | The uuid of the annotation.
`sound_events` | `Mapped[list[SoundEventAnnotation]]` | The sound events annotated in the clip.
`tags` | `Mapped[list[Tag]]` | The tags attached to the annotation.

Notes

    The notes attached to the annotation.

clip The clip to which the annotation belongs. created_on The date and time the annotation was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_id` | `int` | The database id of the clip to which the annotation belongs. | required
`uuid` | `UUID` | The UUID of the annotation. | required

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

Bases: `Base`

Clip Annotation Tag Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the annotation tag.
`tag` | `Mapped[Tag]` | The tag attached to the annotation.
`created_by` | `Mapped[Optional[User]]` | The user who created the annotation tag.
`created_on` |  | The date and time the annotation tag was created.

Parameters:

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

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

Bases: `Base`

Clip Annotation Note Model.

Attributes:

Name | Type | Description
--- | --- | ---
`note` | `Mapped[Note]` | The note attached to the annotation.
`created_on` |  | The date and time the annotation note was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_annotation_id` | `int` | The database id of the annotation to which the annotation 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` | `Mapped[int]` | The database id of the task.
`uuid` | `Mapped[UUID]` | The UUID of the task.
`project` |  | The annotation project to which the task belongs.
`clip` | `Mapped[Clip]` | The audio clip to be annotated.
`clip_annotation` | `Mapped[ClipAnnotation]` | The clip annotation created for the task.
`created_on` |  | The date and time the task was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`project_id` | `int` | The database id of the annotation project to which the task belongs. | required
`clip_id` | `int` | The database id of the audio clip to be annotated. | required
`uuid` | `UUID` | The UUID of the task. | required

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

Bases: `Base`

Annotation status badge model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the status badge.
`state` | `Mapped[AnnotationState]` | The annotation status to which the badge refers.
`task` |  | The task to which the status badge belongs.
`user` | `Mapped[Optional[User]]` | The user to whom the status badge refers.
`created_on` |  | The date and time the status badge was created.

Parameters:

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

### Annotation Project

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

Bases: `Base`

Annotation Project model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the annotation project.
`uuid` | `Mapped[UUID]` | The UUID of the annotation project.
`name` | `Mapped[str]` | The name of the annotation project.
`description` | `Mapped[str]` | The description of the annotation project.
`annotation_instructions` | `Mapped[str | None]` | The instructions for annotators.
`tags` | `Mapped[list[Tag]]` | A list of tags associated with the annotation project. Annotations created for this project can only use these tags.
`annotation_tasks` | `Mapped[list[AnnotationTask]]` | The list of annotation tasks associated with the annotation project.
`created_on` |  | The date and time the annotation project was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`name` | `str` | The name of the annotation project. | required
`description` | `str` | The description of the annotation project. | required
`annotation_instructions` | `str` | The instructions for annotators. | required
`uuid` | `UUID` | The UUID of the annotation project. | required

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

Bases: `Base`

Annotation Project Tag model.

Attributes:

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

Parameters:

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

## Prediction

### Sound Event Prediction

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

Bases: `Base`

Predicted Sound Event model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the sound event prediction.
`uuid` | `Mapped[UUID]` | The UUID of the sound event prediction.
`sound_event` | `Mapped[SoundEvent]` | The sound event to which the sound event prediction belongs.
`score` | `Mapped[float]` | The confidence score assigned to the sound event prediction by the model.
`tags` | `Mapped[list[SoundEventPredictionTag]]` | A list of predicted tags associated with the sound event prediction.
`created_on` |  | The date and time when the sound event prediction was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`sound_event_id` | `int` | The id of the sound event to which the sound event prediction belongs. | required
`clip_prediction_id` | `int` | The id of the clip prediction to which the sound event prediction belongs. | required
`score` | `float` | The confidence score assigned to the sound event prediction by the model. | required
`uuid` | `UUID` | The UUID of the sound event prediction. If not provided, a new UUID will be generated. | required

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

Bases: `Base`

Sound Event Prediction Tag model.

Attributes:

Name | Type | Description
--- | --- | ---
`tag` | `Mapped[Tag]` | The tag associated with the sound event prediction.
`score` | `Mapped[float]` | The confidence score assigned to the tag by the model.
`created_on` |  | The date and time when the tag was created.

Parameters:

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

### Clip Prediction

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

Bases: `Base`

Prediction Clip model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the clip prediction.
`uuid` | `Mapped[UUID]` | The UUID of the clip prediction.
`clip` | `Mapped[Clip]` | The clip to which the prediction belongs.
`tags` | `Mapped[list[ClipPredictionTag]]` | A list of predicted tags.
`sound_events` | `Mapped[list[SoundEventPrediction]]` | A list of predicted sound events.
`created_on` |  | The date and time the clip prediction was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_id` | `int` | The database id of the clip to which the prediction belongs. | required
`uuid` | `UUID` | The UUID of the clip prediction. | required

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

Bases: `Base`

Clip Prediction Tag model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the clip prediction tag.
`tag` | `Mapped[Tag]` | The predicted tag.
`score` | `Mapped[float]` | The confidence score of the prediction.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_prediction_id` | `int` | The database id of the clip prediction. | required
`tag_id` | `int` | The database id of the tag. | required
`score` | `float` | The confidence score of the prediction. | required

### Model Run

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

Bases: `Base`

Model Run Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the model run.
`uuid` | `Mapped[UUID]` | The uuid of the model run.
`name` | `Mapped[str]` | The name of the model used to generate the predictions.
`version` | `Mapped[str]` | The version of the model used to generate the predictions.
`description` | `Mapped[str]` | A description of the model.
`clip_predictions` | `Mapped[list[ClipPrediction]]` | The predictions generated by the model.
`created_on` |  | The date and time the model run was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`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` | A description of the model. | required
`uuid` | `UUID` | The uuid of the model run. | required

### User Run

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

Bases: `Base`

User Run User.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the model run.
`uuid` | `Mapped[UUID]` | The uuid of the model run.
`user` | `Mapped[User]` | The user that created the run.
`clip_predictions` | `Mapped[list[ClipPrediction]]` | The predictions generated by the user.
`created_on` |  | The date and time the user run was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`user_id` | `int` | The id of the user that created the run. | required
`uuid` | `UUID` | The uuid of the model run. | required

## Evaluation

### Sound Event Evaluation

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

Bases: `Base`

Evaluated Sound Event model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the sound event evaluation.
`uuid` | `Mapped[UUID]` | The UUID of the sound event evaluation.
`source` | `Mapped[Optional[SoundEventPrediction]]` | The sound event prediction to which the sound event evaluation belongs.
`target` | `Mapped[Optional[SoundEventAnnotation]]` | The sound event annotation to which the sound event evaluation belongs.
`affinity` | `Mapped[float]` | The affinity between the sound event prediction geometry and the sound event annotation geometry. Does not take into account any semantic information.
`score` | `Mapped[float]` | The overall score of the sound event evaluation.
`metrics` | `Mapped[list[SoundEventEvaluationMetric]]` | A list of metrics associated with the sound event evaluation.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_evaluation_id` | `int` | The id of the clip evaluation to which the sound event evaluation belongs. | required
`source_id` | `int` | The id of the sound event prediction to which the sound event evaluation belongs. | required
`target_id` | `int` | The id of the sound event annotation to which the sound event evaluation belongs. | required
`affinity` | `float` | The affinity between the sound event prediction geometry and the sound event annotation geometry. Does not take into account any semantic information. | required
`score` | `float` | The overall score of the sound event evaluation. | required
`uuid` | `UUID` | The UUID of the sound event evaluation. If not provided, a new UUID will be generated. | required

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

Bases: `Base`

Sound Event Evaluation Metric model.

Attributes:

Name | Type | Description
--- | --- | ---
`feature_name` | `Mapped[FeatureName]` | The name of the feature.
`value` | `Mapped[float]` | The value of the feature.

Parameters:

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

### Clip Evaluation

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

Bases: `Base`

Clip Evaluation Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the clip evaluation.
`uuid` | `Mapped[UUID]` | The UUID of the clip evaluation.
`clip_annotation` | `Mapped[ClipAnnotation]` | The clip annotations to use as ground truth for the evaluation.
`clip_prediction` | `Mapped[ClipPrediction]` | The clip prediction to be evaluated.
`score` | `Mapped[float]` | The overall score of the evaluation.
`metrics` | `Mapped[list[ClipEvaluationMetric]]` | A list of metrics associated with the evaluation.
`sound_event_evaluations` | `Mapped[list[SoundEventEvaluation]]` | A list of sound event evaluations associated with the clip evaluation.
`created_on` |  | The date and time the clip evaluation was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`clip_annotation_id` | `int` | The database id of the clip annotation to use as ground truth. | required
`clip_prediction_id` | `int` | The database id of the clip prediction to be evaluated. | required
`evaluation_id` | `int` | The database id of the evaluation to which the clip evaluation belongs. | required
`score` | `float` | The overall score of the evaluation. | required
`uuid` | `UUID` | The UUID of the clip evaluation. | required

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

Bases: `Base`

Clip Evaluation Metric Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `int` | The database id of the metric.
`value` | `float` | The value of the metric.
`feature_name` | `FeatureName` | The name of the metric.
`created_on` | `datetime` | The date and time the metric was created.

Parameters:

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

Notes

We are reusing the FeatureName model for the metric name.

### Evaluation

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

Bases: `Base`

Evaluation model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the evaluation.
`uuid` | `Mapped[UUID]` | The UUID of the evaluation.
`score` | `Mapped[float]` | The overall score of the evaluation.
`metrics` | `Mapped[list[EvaluationMetric]]` | A list of metrics associated with the evaluation.
`clip_evaluations` | `Mapped[list[ClipEvaluation]]` | A list of clip evaluations associated with the evaluation.
`created_on` |  | The date and time the evaluation was created.
`task` | `Mapped[str]` | The evaluated task.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`score` | `float` | The overall score of the evaluation. | required
`uuid` | `UUID` | The UUID of the evaluation. | required

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

Bases: `Base`

Evaluation metric model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the metric.
`feature_name` | `Mapped[FeatureName]` | The feature name of the metric.
`value` | `Mapped[float]` | The value of the metric.
`created_on` |  | The date and time the metric was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_id` | `int` | The database id of the evaluation. | required
`feature_name_id` | `int` | The database id of the feature name. | required
`value` | `float` | The value of the metric. | required

### Evaluation Set

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

Bases: `Base`

Evaluation Set Model.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `Mapped[int]` | The database id of the evaluation set.
`uuid` | `Mapped[UUID]` | The UUID of the evaluation set.
`name` | `Mapped[str]` | The name of the evaluation set.
`description` | `Mapped[str]` | A textual description of the evaluation set.
`task` | `Mapped[str]` | The name of the task the evaluation set is for. For example, Sound Event Detection. The task name should be linked to a precise way of evaluating the model.
`tags` | `Mapped[list[Tag]]` | The tags to focus on for this evaluation set.
`clip_annotations` | `Mapped[list[ClipAnnotation]]` | The clip annotations to use as ground truth for the evaluation.
`created_on` |  | The date and time the evaluation set was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`name` | `str` | The name of the evaluation set. | required
`description` | `str` | A textual description of the evaluation set. Include information about the goal of the evaluation set. | required
`uuid` | `UUID` | The UUID of the evaluation set. | required

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

Bases: `Base`

Evaluation Set Tag model.

Attributes:

Name | Type | Description
--- | --- | ---
`tag` | `Mapped[Tag]` | The tag to focus on for this evaluation set.
`created_on` |  | The date and time the evaluation set tag was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_set_id` | `int` | The database id of the evaluation set. | required
`tag_id` | `int` | The database id of the tag. | required

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

Bases: `Base`

Evaluation Set Annotation Model.

Attributes:

Name | Type | Description
--- | --- | ---
`clip_annotation` | `Mapped[ClipAnnotation]` | The clip annotation to use as ground truth for the evaluation.
`created_on` |  | The date and time the evaluation set clip annotation was created.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`evaluation_set_id` | `int` | The database id of the evaluation set. | required
`clip_annotation_id` | `int` | The database id of the clip annotation. | required