Ctrl+K

crowsetta.formats.seq.birdsongrec.BirdsongRec

crowsetta.formats.seq.birdsongrec.BirdsongRec#

class crowsetta.formats.seq.birdsongrec.BirdsongRec(sequences: List[BirdsongRecSequence], annot_path, wav_path=None)[source]#

Bases: object

Class that represents annotations from the BirdsongRecognition dataset [1]_. This dataset was first used in Koumura and Okanoya 2016 [2].

name#

Shorthand name for annotation format: 'birdsong-recognition-dataset'.

Type:

str

ext#

Extension of files in annotation format: '.xml'.

Type:

str

sequences#

List of BirdsongRecSequence instances.

Type:

list

annot_path#

Path to file from which annotations were loaded. Typically with filename ‘Annotation.xml’.

Type:

pathlib.Path

wav_path#

Path to directory containing .wav files annotated by the .xml file. If not specified, defaults to directory “Wave”, relative to the parent of xml_path. E.g., if xml_path is ‘Bird0/Annotation.xml’ as shown below, then wav_path defaults to ‘Bird0/Wave’.

├── Bird0
│   ├── Annotation.xml
│   └── Wave
│       ├── 0.wav
│       ├── 100.wav
│       ├── 101.wav
...

Used to obtain sampling rates, to convert onset and offset times from sample number to seconds, when converting annotations to crowsetta.Sequence.

Type:

pathlib.Path

Notes

This class uses the Python package birdsong-recognition-dataset to load the annotations. NickleDave/birdsong-recognition-dataset That package creates Python objects from .xml files that obey this XML schema document: NickleDave/birdsong-recognition-dataset

References

__init__(sequences: List[BirdsongRecSequence], annot_path, wav_path=None) → None#

Method generated by attrs for class BirdsongRec.

Methods

__init__(sequences, annot_path[, wav_path])

Method generated by attrs for class BirdsongRec.

from_file(annot_path[, wav_path, ...])

Load BirdsongRecognition annotations from an .xml file.

to_annot([round_times, decimals, samplerate])

Convert this set of 'birdsong-recognition-dataset' annotations to a list of crowsetta.Annotation instances.

to_seq([round_times, decimals, samplerate])

Convert this set of 'birdsong-recognition-dataset' annotations to a list of crowsetta.Sequence instances.

Attributes

sequences

annot_path

wav_path

ext

name

classmethod from_file(annot_path: PathLike, wav_path: PathLike | None = None, concat_seqs_into_songs: bool = True) → Self[source]#

Load BirdsongRecognition annotations from an .xml file.

Parameters:

  • annot_path (str, pathlib.Path) – Path to xml file from BirdsongRecognition dataset that contains annotations.

  • wav_path (str, pathlib.Path) –

    Path in which wav files listed in Annotation.xml file are found. Defaults to a directory Wave that is located in the parent directory of the Annotation.xml file, which matches the structure of the dataset from [1]_.

    ├── Bird0
│   ├── Annotation.xml
│   └── Wave
│       ├── 0.wav
│       ├── 100.wav
│       ├── 101.wav
...

  • concat_seqs_into_songs (bool) – If True, concatenate sequences from annot_path, so that one sequence = one song / .wav file. Default is True.

Examples

>>> example = crowsetta.data.get('birdsong-recognition-dataset')
>>> birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(example.annot_path)
to_annot(round_times: bool = True, decimals: int = 3, samplerate: int | None = None) → List[Annotation][source]#

Convert this set of 'birdsong-recognition-dataset' annotations to a list of crowsetta.Annotation instances.

Parameters:

  • round_times (bool) – If True, round times of onsets and offsets. Default is True.

  • decimals (int) – Number of decimals places to round floating point numbers to. Only meaningful if round_times is True. Default is 3, so that times are rounded to milliseconds.

  • samplerate – Sampling rate for wave files. Used to convert position and length attributes of BirdsongRecSyllable from sample number to seconds. Default is None, in which ths function tries to open each .wav file and determine the actual sampling rate. If this does not work, then the onsets_s and offsets_s attributes of the crowsetta.Sequence are left as None.

Returns:

annots – A list of crowsetta.Annotation instances.

Return type:

list

Examples

>>> example = crowsetta.data.get('birdsong-recognition-dataset')
>>> birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(example.annot_path)
>>> annots = birdsongrec.to_annot()

Notes

The round_times and decimals arguments are provided to reduce differences across platforms due to floating point error, e.g., when loading annotation files and then sending them to a csv file, the result should be the same on Windows and Linux.

The samplerate argument is provided to make it possible to convert onset and offset times from sample number to seconds, even without the original audio files. By default it is None, and the default location for the .wav files is used. If you need to specify some other location for the .wav files, pass in the wavpath argument when you first load the annotations:

>>> birdsongrec = crowsetta.formats.BirdsongRec.from_file(annot_path, wav_path='./actually/wavs/are/here')
to_seq(round_times: bool = True, decimals: int = 3, samplerate: int | None = None) → List[Sequence][source]#

Convert this set of 'birdsong-recognition-dataset' annotations to a list of crowsetta.Sequence instances.

Parameters:

  • round_times (bool) – If True, round times of onsets and offsets. Default is True.

  • decimals (int) – Number of decimals places to round floating point numbers to. Only meaningful if round_times is True. Default is 3, so that times are rounded to milliseconds.

  • samplerate (int) – Sampling rate for wave files. Used to convert position and length attributes of BirdsongrecSyllable from sample number to seconds. Default is None, in which ths function tries to open each .wav file and determine the actual sampling rate. If this does not work, then the onsets_s and offsets_s attributes of the crowsetta.Sequence are left as None.

Returns:

seqs – A list of crowsetta.Sequence instances.

Return type:

list

Examples

>>> example = crowsetta.data.get('birdsong-recognition-dataset')
>>> birdsongrec = crowsetta.formats.seq.BirdsongRec.from_file(example.annot_path)
>>> seqs = birdsongrec.to_seq()

Notes

The round_times and decimals arguments are provided to reduce differences across platforms due to floating point error, e.g., when loading annotation files and then sending them to a csv file, the result should be the same on Windows and Linux.

The samplerate argument is provided to make it possible to convert onset and offset times from sample number to seconds, even without the original audio files. By default it is None, and the default location for the .wav files is used. If you need to specify some other location for the .wav files, pass in the wavpath argument when you first load the annotations:

>>> birdsongrec = crowsetta.formats.BirdsongRec.from_file(annot_path, wav_path='./actually/wavs/are/here')
Contents