Schemas¶
whombat.schemas
¶
Schemas for Whombat data models.
The Whombat Python API returns these schemas to the user, and they are the main way that the user interacts with the data.
Schemas are defined using Pydantic, and are used to validate data before it is inserted into the database, and also to validate data before it is returned to the user.
Most database models have multiple schemas, a main schema that is used to return data to the user, and a create and update schema that is used to validate data before it is inserted into the database.
Attributes¶
Scale = Literal['amplitude', 'power', 'dB']
module-attribute
¶
Window = Literal['boxcar', 'triang', 'bartlett', 'flattop', 'parzen', 'bohman', 'blackman', 'blackmanharris', 'nuttall', 'barthann', 'hamming', 'hann', 'kaiser']
module-attribute
¶
Classes¶
AmplitudeParameters
¶
Bases: BaseModel
Parameters for amplitude clamping.
Attributes¶
clamp: bool = False
class-attribute
instance-attribute
¶
Whether to clamp amplitude values.
max_dB: float = 0
class-attribute
instance-attribute
¶
Maximum amplitude value.
min_dB: float = -100.0
class-attribute
instance-attribute
¶
Minimum amplitude value.
normalize: bool = True
class-attribute
instance-attribute
¶
Whether to normalize spectrogram before amplitude scaling.
If True, the spectrogram will be normalized to the range [0, 1] before
amplitude scaling. In particular dB values are relative to the maximum
amplitude value in the spectrogram, and not the maximum possible amplitude
value of the recorder.
This can have the effect of making the spectrogram appear noisier than it actually is, since the maximum amplitude value in the spectrogram may be much lower than the maximum possible amplitude value of the recorder.
Also, when visualizing spectrograms in clips, the amplitude scale will be relative to the maximum amplitude value in the clip, and not the maximum of the recording as a whole. This can make it difficult to compare amplitude levels across clips, and will create artificial seams between clips when visualizing spectrograms in recordings.
scale: Scale = 'dB'
class-attribute
instance-attribute
¶
Scale to use for spectrogram computation.
Functions¶
check_db_are_negative(value)
classmethod
¶
Check that min_dB and max_dB are non positive.
check_min_dB_and_max_dB()
¶
Check that min_dB is less than max_dB.
AnnotationProject
¶
Bases: BaseSchema
Schema for an annotation project.
Attributes¶
annotation_instructions: str | None = None
class-attribute
instance-attribute
¶
Project instructions for annotating.
description: str
instance-attribute
¶
A description of the annotation project.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the annotation project.
name: str
instance-attribute
¶
Name of the annotation project.
tags: list[Tag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Tags to be used throughout the annotation project.
uuid: UUID
instance-attribute
¶
UUID of the annotation project.
AnnotationProjectUpdate
¶
Bases: BaseModel
Schema for updating an annotation project.
Attributes¶
annotation_instructions: str | None = None
class-attribute
instance-attribute
¶
Project instructions for annotating.
description: str | None = None
class-attribute
instance-attribute
¶
A description of the annotation project.
name: str | None = None
class-attribute
instance-attribute
¶
Name of the annotation project.
AnnotationStatusBadge
¶
AnnotationStatusBadgeUpdate
¶
AnnotationTask
¶
Bases: BaseSchema
Schema for a task.
Attributes¶
clip: Clip
instance-attribute
¶
Clip of the task.
clip_annotation: ClipAnnotation
instance-attribute
¶
Clip annotation for the task.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the task.
status_badges: list[AnnotationStatusBadge]
instance-attribute
¶
Status badges for the task.
uuid: UUID
instance-attribute
¶
UUID of the task.
AnnotationTaskUpdate
¶
AudioParameters
¶
Bases: ResamplingParameters, FilteringParameters
Parameters for audio loading.
Clip
¶
Bases: BaseSchema
Schema for Clip objects returned to the user.
Attributes¶
end_time: float
instance-attribute
¶
The end time of the clip.
features: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The features associated with the clip.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The database id of the clip.
recording: Recording
instance-attribute
¶
Recording information for the clip.
start_time: float
instance-attribute
¶
The start time of the clip.
uuid: UUID
instance-attribute
¶
The unique identifier of the clip.
ClipAnnotation
¶
Bases: BaseSchema
Schema for an ClipAnnotation.
Attributes¶
clip: Clip
instance-attribute
¶
Clip this annotation is attached to.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of this annotation.
notes: list[Note] = Field(default_factory=list, description='Notes attached to this annotation.')
class-attribute
instance-attribute
¶
sound_events: list[SoundEventAnnotation] = Field(default_factory=list, description='Annotated sound events attached to this clip.')
class-attribute
instance-attribute
¶
tags: list[Tag] = Field(default_factory=list, description='Tags attached to this annotation.', alias_priority=10000)
class-attribute
instance-attribute
¶
uuid: UUID
instance-attribute
¶
ClipAnnotationCreate
¶
ClipAnnotationTag
¶
ClipAnnotationUpdate
¶
ClipCreate
¶
ClipEvaluation
¶
Bases: BaseSchema
Attributes¶
clip_annotation: ClipAnnotation
instance-attribute
¶
Clip annotation used for the evaluation.
clip_prediction: ClipPrediction
instance-attribute
¶
Clip prediction being evaluated.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the evaluation.
metrics: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Evaluation metrics.
score: float
instance-attribute
¶
Overall score of the evaluation.
sound_event_evaluations: list[SoundEventEvaluation] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The evaluation of the sound events within the clip.
uuid: UUID
instance-attribute
¶
UUID of the Clip Evaluation.
ClipEvaluationCreate
¶
ClipEvaluationUpdate
¶
ClipPrediction
¶
Bases: BaseSchema
Schema for a clip prediction.
Attributes¶
clip: Clip
instance-attribute
¶
Clip to which this prediction belongs.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the prediction.
sound_events: list[SoundEventPrediction] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Sound event predictions of the clip.
tags: list[ClipPredictionTag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Tags of the prediction.
uuid: UUID
instance-attribute
¶
UUID of the prediction.
ClipPredictionCreate
¶
ClipPredictionTag
¶
ClipPredictionUpdate
¶
ClipUpdate
¶
Dataset
¶
Bases: BaseSchema
Schema for Dataset objects returned to the user.
Attributes¶
audio_dir: Path
instance-attribute
¶
The path to the directory containing the audio files.
description: str | None
instance-attribute
¶
The description of the dataset.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The database id of the dataset.
name: str
instance-attribute
¶
The name of the dataset.
recording_count: int = 0
class-attribute
instance-attribute
¶
The number of recordings in the dataset.
uuid: UUID
instance-attribute
¶
The uuid of the dataset.
DatasetCreate
¶
Bases: BaseModel
Schema for Dataset objects created by the user.
Attributes¶
audio_dir: DirectoryPath
instance-attribute
¶
The path to the directory containing the audio files.
description: str | None = Field(None)
class-attribute
instance-attribute
¶
The description of the dataset.
name: str = Field(..., min_length=1)
class-attribute
instance-attribute
¶
The name of the dataset.
DatasetFile
¶
DatasetRecording
¶
Bases: BaseSchema
Schema for DatasetRecording objects returned to the user.
DatasetRecordingCreate
¶
DatasetUpdate
¶
Bases: BaseModel
Schema for Dataset objects updated by the user.
Attributes¶
audio_dir: DirectoryPath | None = None
class-attribute
instance-attribute
¶
The path to the directory containing the audio files.
description: str | None = None
class-attribute
instance-attribute
¶
The description of the dataset.
name: str | None = Field(default=None, min_length=1)
class-attribute
instance-attribute
¶
The name of the dataset.
Evaluation
¶
Bases: BaseSchema
Evaluation schema.
Attributes¶
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Dataset identifier of the evaluation.
metrics: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
List of metrics of the evaluation.
score: float
instance-attribute
¶
Overall score of the evaluation.
task: str
instance-attribute
¶
Task of the evaluation.
uuid: UUID
instance-attribute
¶
EvaluationCreate
¶
EvaluationSet
¶
Bases: BaseSchema
Schema for EvaluationSet objects returned to the user.
Attributes¶
description: str | None
instance-attribute
¶
The description of the evaluation set.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The id of the evaluation set.
name: str
instance-attribute
¶
The name of the evaluation set.
tags: list[Tag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The tags to use for the evaluation set.
task: str
instance-attribute
¶
The name of the task the evaluation set is used for.
uuid: UUID
instance-attribute
¶
The uuid of the evaluation set.
EvaluationSetCreate
¶
Bases: BaseModel
Schema for creating EvaluationSet objects.
Attributes¶
description: str | None = Field(default=None)
class-attribute
instance-attribute
¶
The description of the evaluation set.
name: str = Field(..., min_length=1)
class-attribute
instance-attribute
¶
The name of the evaluation set.
task: str = Field(..., min_length=1)
class-attribute
instance-attribute
¶
The name of the task the evaluation set is used for.
Feature
¶
FeatureName
¶
FeatureNameCreate
¶
FeatureNameUpdate
¶
FileState
¶
Bases: Enum
The state of a file in a dataset.
Datasets can contain files that are not registered in the database. This can happen if the file was added to the dataset directory after the dataset was registered. Additionally, files can be registered in the database but missing from the dataset directory. This can happen if the file was removed from the dataset directory after the dataset was registered.
The state of a file can be one of the following:
-
missing: The file is not registered in the database and is missing. -
registered: The file is registered in the database and is present. -
unregistered: The file is not registered in the database but is present in the dataset directory.
Attributes¶
MISSING = 'missing'
class-attribute
instance-attribute
¶
If the recording is registered but the file is missing.
REGISTERED = 'registered'
class-attribute
instance-attribute
¶
If the recording is registered and the file is present.
UNREGISTERED = 'unregistered'
class-attribute
instance-attribute
¶
If the recording is not registered but the file is present.
ModelRun
¶
Bases: ModelRunCreate
Schema of a model run as returned to the user.
ModelRunCreate
¶
Bases: BaseSchema
Model Run creation schema.
Attributes¶
description: str | None = None
class-attribute
instance-attribute
¶
A description of the model used to generate the model run.
name: str
instance-attribute
¶
Name of the model used to generate the model run.
version: str
instance-attribute
¶
Version of the model used to generate the model run.
ModelRunUpdate
¶
Bases: BaseSchema
Model Run update schema.
Attributes¶
description: str | None = None
class-attribute
instance-attribute
¶
The description of the model used to generate the model run.
name: str | None = None
class-attribute
instance-attribute
¶
The name of the model used to generate the model run.
version: str | None = None
class-attribute
instance-attribute
¶
The version of the model used to generate the model run.
Note
¶
Bases: BaseSchema
Schema for Note objects returned to the user.
Attributes¶
created_by: SimpleUser | None
instance-attribute
¶
The user who created the note.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The database id of the note.
is_issue: bool
instance-attribute
¶
Whether the note is an issue.
message: str
instance-attribute
¶
The message of the note.
uuid: UUID
instance-attribute
¶
The uuid of the note.
NoteCreate
¶
Bases: BaseModel
Schema for creating notes.
This schema is used when creating notes from the API as the user does not need to provide the id of the user who created the note.
NoteUpdate
¶
Page
¶
PluginInfo
¶
Bases: BaseModel
Plugin information.
Attributes¶
attribution: str | None = Field(default=None, description='Plugin attribution.')
class-attribute
instance-attribute
¶
description: str | None = Field(default=None, description='Plugin description.')
class-attribute
instance-attribute
¶
name: str = Field(..., description='Plugin name.')
class-attribute
instance-attribute
¶
thumbnail: str | None = Field(default=None, description='Plugin thumbnail.')
class-attribute
instance-attribute
¶
url: str = Field(..., description='Route to the plugin pages.')
class-attribute
instance-attribute
¶
version: str | None = Field(default=None, description='Plugin version.')
class-attribute
instance-attribute
¶
PredictedTag
¶
Recording
¶
Bases: BaseSchema
Schema for Recording objects returned to the user.
Attributes¶
channels: int
instance-attribute
¶
The number of channels in the audio file.
date: datetime.date | None
instance-attribute
¶
The date of the recording.
duration: float
instance-attribute
¶
The duration of the audio file in seconds.
This is the duration of the original audio file, not the time expanded version. This can vary depending on the time expansion factor. If the stored file has a duration of 10 seconds and a time expansion factor is 2, this means that the original recording was 5 seconds long. So the duration of the original recording is 5 seconds, not 10.
features: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The features associated with the recording.
hash: str
instance-attribute
¶
The md5 hash of the audio file.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The database id of the recording.
latitude: float | None
instance-attribute
¶
The latitude of the recording.
longitude: float | None
instance-attribute
¶
The longitude of the recording.
notes: list[Note] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The notes associated with the recording.
owners: list[SimpleUser] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The users that own the recording.
path: Path
instance-attribute
¶
The path to the audio file, relative to the audio directory.
rights: str | None
instance-attribute
¶
A text describing the usage rights of the recording.
samplerate: int
instance-attribute
¶
The sample rate of the audio file in Hz.
This is the sample rate of the original audio file, not the time expanded version. This can vary depending on the time expansion factor. If the stored file has a sample rate of 44100 Hz and a time expansion factor is 2, this means that the original recording had a sample rate of 88200 Hz. So the sample rate of the original recording is 88200 Hz, not 44100 Hz.
tags: list[Tag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The tags associated with the recording.
time: datetime.time | None
instance-attribute
¶
The time of the recording.
time_expansion: float
instance-attribute
¶
The time expansion factor of the recording.
uuid: UUID
instance-attribute
¶
The UUID of the recording.
RecordingCreate
¶
Bases: BaseModel
Data for Recording creation.
Attributes¶
date: datetime.date | None = None
class-attribute
instance-attribute
¶
The date of the recording.
latitude: float | None = Field(default=None, ge=-90, le=90)
class-attribute
instance-attribute
¶
The latitude of the recording.
longitude: float | None = Field(default=None, ge=-180, le=180)
class-attribute
instance-attribute
¶
The longitude of the recording.
path: FilePath
instance-attribute
¶
The path to the audio file.
rights: str | None = None
class-attribute
instance-attribute
¶
A text describing the usage rights of the recording.
time: datetime.time | None = None
class-attribute
instance-attribute
¶
The time of the recording.
time_expansion: float = Field(default=1.0, gt=0)
class-attribute
instance-attribute
¶
The time expansion factor of the recording.
Functions¶
is_an_audio_file(v)
¶
Validate that the given path is an audio file.
RecordingTag
¶
RecordingUpdate
¶
Bases: BaseModel
Schema for Recording objects updated by the user.
Attributes¶
date: datetime.date | None = None
class-attribute
instance-attribute
¶
The date of the recording.
latitude: float | None = Field(default=None, ge=-90, le=90)
class-attribute
instance-attribute
¶
The latitude of the recording.
longitude: float | None = Field(default=None, ge=-180, le=180)
class-attribute
instance-attribute
¶
The longitude of the recording.
path: FilePath | None = None
class-attribute
instance-attribute
¶
New path to the audio file.
rights: str | None = None
class-attribute
instance-attribute
¶
A text describing the usage rights of the recording.
time: datetime.time | None = None
class-attribute
instance-attribute
¶
The time of the recording.
time_expansion: float | None = Field(default=None, gt=0)
class-attribute
instance-attribute
¶
New time expansion factor of the recording.
STFTParameters
¶
Bases: BaseModel
Parameters for STFT computation.
Attributes¶
hop_size: float = Field(default=0.5, gt=0.0, le=1.0)
class-attribute
instance-attribute
¶
Hop size as a fraction of window size.
window: Window = 'hann'
class-attribute
instance-attribute
¶
Window function.
window_size: float = 0.025
class-attribute
instance-attribute
¶
Size of FFT window in seconds.
Functions¶
check_positive(value)
classmethod
¶
Check that window size and hop size are positive.
SimpleUser
¶
Bases: BaseSchema
Schema for User objects returned to the user.
Attributes¶
email: EmailStr | None = None
class-attribute
instance-attribute
¶
id: uuid.UUID
instance-attribute
¶
is_active: bool | None = False
class-attribute
instance-attribute
¶
is_superuser: bool | None = False
class-attribute
instance-attribute
¶
is_verified: bool | None = False
class-attribute
instance-attribute
¶
name: str | None = None
class-attribute
instance-attribute
¶
username: str
instance-attribute
¶
SoundEvent
¶
Bases: BaseSchema
Public schema for handling sound events.
Attributes¶
features: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
The features associated with the sound event.
geometry: Geometry = Field(..., discriminator='type')
class-attribute
instance-attribute
¶
geometry_type: GeometryType
instance-attribute
¶
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
The id of the sound event.
uuid: UUID
instance-attribute
¶
The uuid of the sound event.
SoundEventAnnotation
¶
Bases: BaseSchema
Schema for an SoundEventAnnotation.
Attributes¶
created_by: SimpleUser | None
instance-attribute
¶
User who created this annotation.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of this annotation.
notes: list[Note] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Notes attached to this annotation.
sound_event: SoundEvent
instance-attribute
¶
Sound event this annotation is attached to.
tags: list[Tag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Tags attached to this annotation.
uuid: UUID
instance-attribute
¶
UUID of this annotation.
SoundEventAnnotationCreate
¶
Bases: BaseModel
Schema for data required to create an SoundEventAnnotation.
SoundEventAnnotationTag
¶
SoundEventAnnotationUpdate
¶
SoundEventEvaluation
¶
Bases: BaseSchema
Schema for a sound event evaluation.
Attributes¶
affinity: float
instance-attribute
¶
Affinity of the match between the source and target.
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the evaluation.
metrics: list[Feature] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Evaluation metrics.
score: float
instance-attribute
¶
Overall score of the evaluation.
source: SoundEventPrediction | None
instance-attribute
¶
Source sound event prediction.
target: SoundEventAnnotation | None
instance-attribute
¶
Target sound event annotation.
uuid: UUID
instance-attribute
¶
SoundEventEvaluationCreate
¶
SoundEventEvaluationUpdate
¶
Bases: BaseSchema
Schema for updating a sound event evaluation.
Attributes¶
affinity: float | None = None
class-attribute
instance-attribute
¶
Affinity of the match between the source and target.
score: float | None = None
class-attribute
instance-attribute
¶
Overall score of the evaluation.
uuid: UUID | None = None
class-attribute
instance-attribute
¶
UUID of the Sound Event Evaluation.
SoundEventPrediction
¶
Bases: BaseSchema
Schema for a sound event prediction.
Attributes¶
id: int = Field(..., exclude=True)
class-attribute
instance-attribute
¶
Database ID of the prediction.
score: float
instance-attribute
¶
Overall score of the prediction.
sound_event: SoundEvent
instance-attribute
¶
Sound event to be predicted.
tags: list[SoundEventPredictionTag] = Field(default_factory=list)
class-attribute
instance-attribute
¶
Tags of the prediction.
uuid: UUID
instance-attribute
¶
UUID of the prediction.
SoundEventPredictionCreate
¶
SoundEventPredictionTag
¶
SoundEventPredictionUpdate
¶
SoundEventUpdate
¶
SpectrogramParameters
¶
Bases: STFTParameters, AmplitudeParameters
Parameters for spectrogram computation.
Tag
¶
TagCreate
¶
User
¶
UserCreate
¶
UserRun
¶
Bases: BaseSchema
Schema of a user run as returned to the user.