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('3d67459d-e772-42fd-b869-f14e99f79669')
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('aa01fba7-924a-485b-a170-831b803c492e')

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('a92cc1f3-d338-40dd-bfaa-4fbf7865c4d6')
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('8c54e96b-2397-4116-8147-4adced350f97')
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('5ef98127-de48-4c0b-9549-cf7ecb7c97e5')
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('d8942679-6675-4e32-9f67-33e9b52d8bc0')
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('cc8d374a-b48a-4436-a7e8-e83a3ac71dcc')
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('9c91f35c-0939-4304-91b5-6a6fcac297a2')
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('293c8815-becc-41ec-9375-534001650b1f')

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('8036dfda-9a7d-4919-8db6-7c9dcff5a76b')
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('a1b8f1ba-4028-44cb-8e6c-10b36c025b54')
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('e8048501-fc45-4c35-8bce-e1d68b232859')
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('98e07611-4c49-44e9-8f20-061a250a8b31')
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('ff64f891-60a8-4f75-bf1d-ed474b3580d6')
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('a9d2dec9-614b-439a-8e2b-a1f2b0c51165')
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('8379ac85-0124-4930-a5b2-910a16615611')
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('810226a2-ac21-459f-aed8-58d60edd4f6f')
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('de0d1847-a7fb-4795-853c-f2aceb781f11')
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