vak.common.annotation.map_annotated_to_annot#

vak.common.annotation.map_annotated_to_annot(annotated_files: list | array, annot_list: list[Annotation], annot_format: str, annotated_ext: str | None = None) → dict[source]#

Map annotated files, i.e. audio or spectrogram files, to their corresponding annotations.

This function implements the three different ways that vak can map annotated files to their annotations. The first is when a single annotation file contains multiple annotations, and so the format by necessity must include the file annotated by each annotation. The second assumes that the annotated file can be determined programmatically by removing the extension from the annotation file, e.g. ‘bird1.wav.csv’ -> ‘bird1.wav’. The third assumes that the annotated file can be determined by replacing the extension of the annotation file with the extension of the annotated file, e.g. ‘bird1.csv’ -> ‘bird1.wav’.

Returns a dict where each key is a path to an annotated file, and the value for each key is a crowsetta.Annotation.

Mapping is done with two helper functions, _map_using_notated_path() and _map_using_ext().

The function _map_using_notated_path() is used for annotation formats that include the name of the annotated file. The names of these formats (in :module:`crowsetta`) are: {‘birdsong-recognition-dataset’, ‘generic-seq’, ‘yarden’}.

The other function is are used for all other formats, and it assumes a one-to-one mapping from annotation file to annotated file. It assumes that the name of the annotated file can be found by removing the extension of the annotation format, e.g., ‘bird1.wav.csv` -> ‘bird1.wav’. The second, that is used if the first fails, assumes the name of the annotated file can be found by replacing the extension of the annotation format with the extension of the annotated files.

Parameters:

  • annotated_files (list) – Of paths to audio or spectrogram files.

  • annot_list (list) – Of Annotations corresponding to files in annotated_files

  • annotated_ext (str) – Extension of annotated files. Default is None, in which case this function will look for extensions of any valid audio format (listed as vak.constants.VALID_AUDIO_FORMAT). Specifying the format provides a slight speed up.

Notes

For more detail, please see the page on file naming conventions in the reference section of the documentation: https://vak.readthedocs.io/en/latest/reference/filenames.html