IO Module

soundevent.io

The IO module of the soundevent package.

This module contains the classes and functions for reading and writing sound event data.

Functions:

Name	Description
save	Save a data object to a file.
load	Load data from a file.

Attributes:

Name	Type	Description
DataCollections		Type alias for all data collection types.

DataCollections = Union[data.Dataset, data.AnnotationSet, data.AnnotationProject, data.PredictionSet, data.ModelRun, data.EvaluationSet, data.Evaluation, data.RecordingSet] module-attribute

Type alias for all data collection types.

save(obj, path, audio_dir=None, format='aoef', **kwargs)

Save a data object to a file.

This function saves a data object to a file in a format that can be loaded by the load function. The following object types are supported:

• RecordingSet
• Dataset
• AnnotationSet
• AnnotationProject
• EvaluationSet
• PredictionSet
• ModelRun
• Evaluation

Parameters:

Name	Type	Description	Default
obj	DataCollections	The data object to save.	required
path	PathLike	Path to the file to save to.	required
audio_dir	Optional[PathLike]	All path to audio files will be stored relative to this directory. This is useful to avoid storing absolute paths which are not portable. If None, audio paths will be stored as absolute paths.	None
format	Optional[str]	Format to save the data in. If None, the format will be inferred from the file extension.	'aoef'

load(path, audio_dir=None, format='aoef', type=None)

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['recording_set'] = 'recording_set') -> data.RecordingSet

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['dataset'] = 'dataset') -> data.Dataset

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['annotation_set'] = 'annotation_set') -> data.AnnotationSet

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['annotation_project'] = 'annotation_project') -> data.AnnotationProject

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['prediction_set'] = 'prediction_set') -> data.PredictionSet

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['model_run'] = 'model_run') -> data.ModelRun

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['evaluation_set'] = 'evaluation_set') -> data.EvaluationSet

load(path: data.PathLike, audio_dir: Optional[data.PathLike] = None, format: Optional[str] = 'aoef', type: Literal['evaluation'] = 'evaluation') -> data.Evaluation

Load data from a file.

Parameters:

Name	Type	Description	Default
path	PathLike	Path to the file to load.	required
audio_dir	Optional[PathLike]	Path to the directory containing the audio files. Often, the audio path is stored relative to some directory to avoid storing absolute paths, which are not portable. In this case, the audio_dir argument is used to resolve the relative paths.	None
format	Optional[str]	Format of the file to load. If not specified, the format is inferred.	'aoef'
type	Optional[DataType]	Type of the data to load. If not specified, the type is inferred. This argument is mainly used for letting the type system know what type of object is returned by the function and can be omitted in most cases.	None

soundevent.io.crowsetta

Crowsetta Module.

This module provides a set of functions to facilitate the export and import of data in the soundevent format to and from the Crowsetta format.

Modules:

Name	Description
annotation	Module for converting between ClipAnnotation and Crowsetta annotation formats.
bbox	Module for converting between SoundEvent annotations and Crowsetta bounding boxes.
labels	Crowsetta label conversion functions.
segment	crowsetta.segment module.
sequence	Module for converting between SoundEvent annotations and Crowsetta sequences.

Functions:

Name	Description
annotation_from_clip_annotation	Convert a ClipAnnotation to a Crowsetta annotation.
annotation_to_clip_annotation	Convert a Crowsetta annotation to a ClipAnnotation.
bbox_from_annotation	Convert a soundevent annotation to a Crowsetta bounding box.
bbox_to_annotation	Convert a crowsetta bounding box annotation to a soundevent annotation.
label_from_tag	Convert a soundevent tag to a crowsetta label.
label_from_tags	Convert a sequence of soundevent tags to a crowsetta label.
label_to_tags	Convert a crowsetta label to a list of soundevent tags.
segment_from_annotation	Convert a soundevent annotation to a crowsetta segment.
segment_to_annotation	Convert a crowsetta segment to a soundevent time interval annotation.
sequence_from_annotations	Convert a sequence of soundevent annotations to a Crowsetta sequence.
sequence_to_annotations	Convert a Crowsetta sequence to a list of soundevent annotations.

Functions

annotation_from_clip_annotation(annot, annot_path, annotation_fmt, ignore_errors=True, cast_geometry=True, **kwargs)

Convert a ClipAnnotation to a Crowsetta annotation.

This function transforms a ClipAnnotation object into a Crowsetta annotation (crowsetta.Annotation). The choice of annotation format (bbox for bounding boxes or seq for sequences) determines the type of Crowsetta annotation created. Each sound event within the ClipAnnotation is individually converted into either a sequence or a bounding boxes using the corresponding conversion functions.

Parameters:

Name	Type	Description	Default
annot	ClipAnnotation	The ClipAnnotation object to convert.	required
annot_path	PathLike	The path to the annotation file.	required
annotation_fmt	Union[Literal['bbox'], Literal['seq']]	The desired Crowsetta annotation format: 'bbox' for bounding boxes or 'seq' for sequences.	required
ignore_errors	bool	If True, ignore errors during conversion and continue with the next sound event, otherwise this function will raise an error if a sound event cannot be converted, by default True.	True
cast_geometry	bool	If True, cast non-matching geometries to the expected type, otherwise raise an error if the geometry does not match the expected type, by default True.	True
**kwargs		Additional keyword arguments passed to the corresponding conversion functions.	{}

Returns:

Type	Description
Annotation	A Crowsetta annotation representing the converted ClipAnnotation.

annotation_to_clip_annotation(annot, recording=None, tags=None, notes=None, adjust_time_expansion=True, created_by=None, recording_kwargs=None, **kwargs)

Convert a Crowsetta annotation to a ClipAnnotation.

This function transforms a Crowsetta annotation (crowsetta.Annotation) into a ClipAnnotation object. Depending on the annotation format, the Crowsetta annotation is converted into a list of sound event annotations or sequence annotations, or both, and included in the resulting ClipAnnotation.

Parameters:

Name	Type	Description	Default
annot	Annotation	The Crowsetta annotation to convert.	required
recording	Optional[Recording]	The original recording associated with the annotations, if not provided, it is loaded based on the path of the notated recording, by default None.	None
tags	Optional[List[Tag]]	Tags associated with the clip annotation, by default None.	None
notes	Optional[List[Note]]	Notes associated with the clip annotation, by default None.	None
adjust_time_expansion	bool	If True, adjust the onset and offset times based on the recording's time expansion factor, by default True.	True
created_by	Optional[User]	User information representing the creator of the converted clip annotation, by default None.	None
recording_kwargs	Optional[dict]	Additional keyword arguments passed when loading the recording, by default None. You can use this to set the recording metadata such as time_expansion, latitude, longitude, etc.	None
**kwargs		Additional keyword arguments passed to the conversion functions.	{}

Returns:

Type	Description
ClipAnnotation	A ClipAnnotation representing the converted Crowsetta annotation.

bbox_from_annotation(obj, cast_to_bbox=True, raise_on_time_geometries=True, **kwargs)

Convert a soundevent annotation to a Crowsetta bounding box.

This function transforms a SoundEventAnnotation object into a Crowsetta bounding box (BBox). The SoundEvent's geometry is used to determine the onset, offset, low frequency, and high frequency values of the bounding box, and the associated tags are converted into a Crowsetta label using the convert_tags_to_label function.

Parameters:

Name	Type	Description	Default
obj	SoundEventAnnotation	The SoundEventAnnotation object to convert.	required
cast_to_bbox	bool	If True, cast the geometry to a bounding box, otherwise, keep it as is, by default True.	True
raise_on_time_geometries	bool	If True, raise an exception if the geometry is a TimeInterval or TimeStamp, otherwise, cast it to a bounding box with a lowest frequency of 0 and a highest frequency of the recording's Nyquist frequency. By default True.	True
**kwargs		Additional keyword arguments passed to the convert_tags_to_label function.	{}

Returns:

Type	Description
BBox	A Crowsetta bounding box representing the converted soundevent annotation, with onset, offset, low frequency, high frequency, and associated label.

bbox_to_annotation(bbox, recording, adjust_time_expansion=True, notes=None, created_by=None, **kwargs)

Convert a crowsetta bounding box annotation to a soundevent annotation.

This function transforms a crowsetta bounding box annotation (BBox) into a SoundEventAnnotation object. The onset, offset, low frequency, and high frequency values of the bounding box are used to create a BoundingBox geometry. The label associated with the bounding box is converted into a list of soundevent tags using the convert_label_to_tags function.

Parameters:

Name	Type	Description	Default
bbox	BBox	The bounding box annotation to convert.	required
recording	Recording	The original recording from which the bounding box annotation was derived.	required
adjust_time_expansion	bool	If True, adjust the onset, offset, and frequency values based on the recording's time expansion factor, by default True.	True
notes	List[Note]	Additional notes associated with the converted soundevent annotation, by default None.	None
created_by	User	User information representing the creator of the converted soundevent annotation, by default None.	None
**kwargs		Additional keyword arguments passed to the convert_label_to_tags function.	{}

Returns:

Type	Description
SoundEventAnnotation	A SoundEventAnnotation object representing the converted bounding box annotation, containing a SoundEvent with the bounding box geometry, associated tags, notes, and creator information.

label_from_tag(tag, label_fn=None, label_mapping=None, value_only=False, separator=':')

Convert a soundevent tag to a crowsetta label.

This function facilitates the conversion of a soundevent tag into a crowsetta label. Users can customize this conversion using the following options:

1. If a custom mapping function (label_fn argument) is provided, it will be used to directly convert the tag to a label.
2. If a mapping dictionary (label_mapping argument) is provided, the function will attempt to look up the label for the tag in the mapping. If found, it returns the label; otherwise, it proceeds to the next option.
3. If the value_only argument is set to True, the function returns only the value of the tag.
4. If none of the above conditions are met, the function constructs the label by combining the tag's key and value with the specified separator.

Parameters:

Name	Type	Description	Default
tag	Tag	The soundevent tag to convert to a label.	required
label_fn	Optional[Callable[[Tag], str]]	A function to convert tags to labels.	None
label_mapping	Optional[Dict[Tag, str]]	A dictionary mapping tags to labels.	None
value_only	bool	If True, return only the value of the tag, by default False.	False
separator	str	The separator to use between the key and value when constructing the label, by default ":".	':'

Returns:

Type	Description
str	The crowsetta label corresponding to the soundevent tag.

label_from_tags(tags, seq_label_fn=None, select_by_key=None, index=None, separator=',', empty_label=EMPTY_LABEL, **kwargs)

Convert a sequence of soundevent tags to a crowsetta label.

This function facilitates the conversion of a sequence of soundevent tags into a Crowsetta label. Users can customize the conversion process using the following options:

1. If a custom sequence label function (seq_label_fn argument) is provided, it will be used to directly convert the sequence of tags to a label.
2. If the sequence of tags is empty, the function returns the specified empty_label.
3. If the select_by_key argument is provided, the function will attempt to find the first tag in the sequence with a matching key. If found, it returns the label converted from that tag using convert_tag_to_label, otherwise it returns the empty_label.
4. If the index argument is provided, it will be used to select a tag from the sequence based on the index. If the index is out of bounds, it wraps around to the valid range. The label converted from the selected tag is then returned.
5. If none of the above conditions are met, the function constructs a label by joining the labels of all tags in the sequence with the specified separator.

Parameters:

Name	Type	Description	Default
tags	Sequence[Tag]	The sequence of soundevent tags to convert to a label.	required
seq_label_fn	Optional[Callable[[Sequence[Tag]], str]]	A function to convert sequences of tags to labels.	None
select_by_key	Optional[str]	If provided, select the first tag with a matching key for label conversion.	None
index	Optional[int]	If provided, use it as the index to select a tag from the sequence for label conversion. The index is wrapped around if it exceeds the bounds.	None
separator	str	The separator to use between the labels when constructing the final label.	','
empty_label	str	The label to return when the sequence of tags is empty. By default "empty".	EMPTY_LABEL
**kwargs		Additional keyword arguments passed to the convert_tag_to_label function.	{}

Returns:

Type	Description
str	The Crowsetta label corresponding to the sequence of soundevent tags.

label_to_tags(label, tag_fn=None, tag_mapping=None, term_mapping=None, key_mapping=None, key=None, term=None, fallback='crowsetta', empty_labels=(EMPTY_LABEL))

Convert a crowsetta label to a list of soundevent tags.

Parameters:

Name	Type	Description	Default
label	str	The Crowsetta label to convert.	required
tag_fn	Optional[LabelToTagFn]	A function to directly convert labels to a list of tags.	None
tag_mapping	Optional[LabelToTagMap]	A dictionary mapping labels to lists of tags or a single tag.	None
term_mapping	Optional[Dict[str, Term]]	A dictionary mapping labels directly to soundevent.data.Term objects	None
key_mapping	Optional[Dict[str, str]]	A dictionary mapping labels to keys (deprecated, use term_mapping instead).	None
key	Optional[str]	The key to use for the tag (deprecated, use term instead).	None
term	Optional[Term]	The soundevent.data.Term to use for the tag	None
fallback	str	The key to use if no other key is provided (deprecated, use term instead).	'crowsetta'
empty_labels	Sequence[str]	Labels considered empty, resulting in an empty list of tags.	(EMPTY_LABEL)

Returns:

Type	Description
List[Tag]	The list of soundevent tags corresponding to the Crowsetta label.

Notes

This is the default conversion process:

1. If label is in empty_labels, return an empty list.
2. If tag_fn is provided, use it to convert the label.
3. If term_mapping is provided and the label is found, use the corresponding term.
4. If tag_mapping is provided and the label is found, return the corresponding tags.
5. If key_mapping is provided and the label is found, use the corresponding key (deprecated).
6. If key is provided, use it (deprecated). Otherwise, use fallback (deprecated).
7. If term is not yet set, derive it from the key (deprecated).
8. Return a list containing a single Tag with the determined term and the original label as the value.

segment_from_annotation(obj, cast_to_segment=True, **kwargs)

Convert a soundevent annotation to a crowsetta segment.

This function transforms a SoundEventAnnotation object into a Crowsetta segment. The SoundEvent's geometry is used to determine the onset and offset times of the segment, and the associated tags are converted into a Crowsetta label using the convert_tags_to_label function.

Parameters:

Name	Type	Description	Default
obj	SoundEventAnnotation	The SoundEventAnnotation object to convert.	required
cast_to_segment	bool	If True, any geometry that is not a TimeInterval will be cast to a TimeInterval, otherwise a ValueError will be raised. By default True.	True
**kwargs		Additional keyword arguments passed to the convert_tags_to_label function.	{}

Returns:

Type	Description
Segment	A Crowsetta Segment representing the converted soundevent segment, with onset and offset times, sample indices, and associated label.

Raises:

Type	Description
ValueError	If the sound event has no geometry, or if the geometry is not a TimeInterval and cast_to_segment is False.

segment_to_annotation(segment, recording, adjust_time_expansion=True, notes=None, created_by=None, **kwargs)

Convert a crowsetta segment to a soundevent time interval annotation.

This function transforms a Crowsetta segment into a SoundEvent time interval annotation. The segment's onset and offset times are used to create a time interval, and the label is converted into a list of soundevent tags using the convert_label_to_tags function.

Parameters:

Name	Type	Description	Default
segment	Segment	The Crowsetta segment to convert.	required
recording	Recording	The original recording associated with the segment.	required
adjust_time_expansion	bool	If True, adjust the segment's onset and offset times based on the recording's time expansion factor, by default True.	True
notes	List[Note]	Additional notes associated with the converted time interval, by default None.	None
created_by	User	User information representing the creator of annotation. By default None.	None
**kwargs		Additional keyword arguments passed to the convert_label_to_tags function.	{}

Returns:

Type	Description
SoundEventAnnotation	A SoundEventAnnotation object representing the converted time interval, containing a SoundEvent with the time interval, associated tags, notes, and creator information.

sequence_from_annotations(annotations, cast_to_segment=True, ignore_errors=False, **kwargs)

Convert a sequence of soundevent annotations to a Crowsetta sequence.

This function transforms a sequence of SoundEventAnnotation objects into a Crowsetta sequence (crowsetta.Sequence). Each annotation is individually converted into a Crowsetta segment using the to_crowsetta_segment function.

Parameters:

Name	Type	Description	Default
annotations	Sequence[SoundEventAnnotation]	The sequence of SoundEventAnnotation objects to convert.	required
cast_to_segment	bool	If True, cast the annotations to Crowsetta segments, otherwise, keep them as is, by default True.	True
ignore_errors	bool	If True, ignore errors during conversion and continue with the next annotation, otherwise this function will raise an error if an annotation cannot be converted, by default False.	False
**kwargs		Additional keyword arguments passed to the to_crowsetta_segment function.	{}

Returns:

Type	Description
Sequence	A Crowsetta sequence representing the converted soundevent annotations.

Raises:

Type	Description
ValueError	If an annotation cannot be converted and ignore_errors is False.

sequence_to_annotations(sequence, recording, adjust_time_expansion=True, created_by=None, **kwargs)

Convert a Crowsetta sequence to a list of soundevent annotations.

This function transforms a Crowsetta sequence (crowsetta.Sequence) into a list of SoundEventAnnotation objects. Each segment in the Crowsetta sequence is individually converted into a soundevent annotation using the to_time_interval_annotation function.

Parameters:

Name	Type	Description	Default
sequence	Sequence	The Crowsetta sequence to convert.	required
recording	Recording	The original recording associated from which the Crowsetta sequence was annotated.	required
adjust_time_expansion	bool	If True, adjust the onset and offset times based on the recording's time expansion factor, by default True.	True
created_by	User	User information representing the creator of the converted soundevent annotations, by default None.	None
**kwargs		Additional keyword arguments passed to the to_time_interval_annotation function.	{}

Returns:

Type	Description
List[SoundEventAnnotation]	A list of soundevent annotations representing the converted Crowsetta sequence.