Handling Annotations/Detections

Format-specific Readers and Writers for managing annotations and detections. Currently supported formats include:

Custom Readers/Writers to handle yet-unsupported formats can be implemented, in ways compatible for use within the Koogu ecosystem as a drop-in replacement to existing Readers/Writers, by extending the BaseAnnotationReader and BaseAnnotationWriter classes.

Audacity

class koogu.data.annotations.Audacity.Reader(fetch_frequencies=False)

Reader class for reading Audacity format annotation files.

Parameters:

fetch_frequencies – (boolean; default: False) If True, will also attempt to read annotations’ frequency bounds. NaNs will be returned for any missing values. If False, the respective item in the tuple returned will be set to None.

Example:

>>> # Create a reader instance
>>> reader = Audacity.Reader()
>>>
>>> # Read annotations from file and display
>>> (times, _, tags, _, _) = reader('my_audacity_annots.txt')
>>> print('Start time, End time, Label')
>>> print('----------, --------, -----')
>>> for idx in range(len(times)):
...     print(f'{times[idx][0]}, {times[idx][1]}, {tags[idx]}')
class koogu.data.annotations.Audacity.Writer(write_frequencies=False, **kwargs)

Writer class for writing annotations/detections to Audacity format files.

Parameters:

write_frequencies – Boolean (default: False) directing whether to include bounding (lower and higher) frequency info in the outputs.

Raven Pro

class koogu.data.annotations.Raven.Reader(fetch_frequencies=False, label_column_name=None, **kwargs)

Reader class for reading Raven selection table format files.

Parameters:

  • fetch_frequencies – (boolean; default: False) If True, will also return annotations’ frequency bounds. NaNs will be returned for any missing values in file. If False, the respective return value will be set to None.

  • label_column_name – A string (e.g., “Tags”) identifying the header of the column in the selection table file(s) from which class labels are to be extracted. If None (default), will look for a column with the header “Tags”.

Example:

>>> # Create a reader instance
>>> reader = Raven.Reader(fetch_frequencies=True)
>>>
>>> # Read annotations from file and display
>>> (times, freqs, tags, chs, _) = \
...     reader('20180212_060000.selections.txt')
>>> print('Start time, Upper freq, Channel, Tag')
>>> print('----------, ----------, -------, ---')
>>> for idx in range(len(times)):
...     print(
...         f'{times[idx][0]}, {freqs[idx][1]}, {chs[idx]}, {tags[idx]}'
...     )
classmethod get_annotations_from_file(seltab_file, fields_spec, delimiter='\t')

A generator for reading Raven selection tables. A simple, fast yet efficient way for processing selection tables. Pass in the path to the file and a list containing field specifications, and retrieve table entries iteratively, without having to load the entire selection table file into memory.

Parameters:

  • seltab_file – Path to a Raven selection table file.

  • fields_spec –

    A list of field specifiers. A field specifier must be a tuple containing -

    • the name of the field (column header),

    • the corresponding data type, and

    • optionally, a default value.

    The field names (case-sensitive) should match the actual column headers in the selection table file. If no matching column header is found for aspecified field, then the respective value will be None in every returned output. If an annotation entry is blank for a specified field, then the respective value returned will be set to either the default (if specified) or to None.

  • delimiter – (optional; default is the tab character) The delimiter in the selection table file.

Returns:

The generator iteratively yields tuples containing type-converted values corresponding to the chosen fields from each annotation read. The fields in the tuple will be in the same order as that of fields_spec.

Example:

>>> file_fields_spec = [('Selection', int, 0),
...                     ('Begin Time (s)', float, 0),
...                     ('Tags', str),
...                     ('Score', float)]
...
>>> for entry in Raven.Reader.get_annotations_from_file(
...         'my_annots.selection.txt', file_fields_spec):
...     print(entry[0], entry[1], entry[2], entry[3])
class koogu.data.annotations.Raven.Writer(write_frequencies=False, extra_fields_spec=None, **kwargs)

Writer class for writing annotations/detections to Raven selection table format files.

Parameters:

  • write_frequencies – Boolean (default: False) directing whether to include the “Low Freq (Hz)” and “High Freq (Hz)” fields in the outputs.

  • extra_fields_spec – Optional list of 2-element tuples identifying any additional fields to add to the output and their respective formats. E.g., [(‘Model used’, ‘s’)] will add an extra field named “Model used” and set the values in the fields to be formatted as strings.

  • add_selection_number – Boolean (default: True) directing whether to include the “Selection” field.

  • add_channel – Boolean (default: True) directing whether to include the “Channel” field.

  • add_score – Boolean (default: False) directing whether to include the “Scores” field. Use when saving detections.

Sonic Visualiser

class koogu.data.annotations.SonicVisualiser.Reader(fetch_frequencies=False)

Reader class for reading Sonic Visualiser format annotation files.

Parameters:

fetch_frequencies – (boolean; default: False) If True, will also attempt to read annotations’ frequency bounds. NaNs will be returned for any missing values. If False, the respective item in the tuple returned will be set to None.

Example:

>>> # Create a reader instance
>>> reader = SonicVisualiser.Reader()
>>>
>>> # Read annotations from file and display
>>> (times, _, tags, _, _) = reader('my_annots.svl')
>>> print('Start time, End time, Label')
>>> print('----------, --------, -----')
>>> for idx in range(len(times)):
...     print(f'{times[idx][0]}, {times[idx][1]}, {tags[idx]}')