Annotation: External Annotation Data

Working with external annotation

The Firetail annotation exchange format

Firetail provides a conceptually simple exchange file format to visualize 3rd party annoations or external resources in general. It’s documented here:

The Firetail annotation exchange format

BORIS video annotation data

Firetail 10 provides import filters for event data recorded with the BORIS video annotation tool. Tabular csv data exported using the event export (BORIS v7 and v8) can be imported directly.

Note: this feature is experimental. Please notify support@firetail.de if your exported files do not load as expected (possibly attach sample data).

Sample workflow (BORIS v8)

Given you have annotated multiple events

  • point events
  • range events
  • possibly using modifiers

create a csv suitable for import in Firetail as follows:

  1. Open the BORIS annoation project (in BORIS) and select Observations > Export events > Tabular events

Export tabular menu

  1. select the observations to be exported

select observations

  1. select the subjects and behaviors to be exported

select observations

  1. choose a filename and select csv (or tsv - Firetail will rely on the file extension upon read-in)

select observations

  1. switch to Firetail. Select the appropriate acceleration dataset and select File > Annotations > Import BORIS Annotations (CSV)

select observations

Your annotation data will show as category {individual}_{behavior}[{modifier}] on a layer {individual}_{behavior}.

select observations

BORIS v7 files

The tabular export formats of BORIS may differ from verison 7 to 8.

Version 7 exports would start like this:

Observation id,MO34_2021-07-11_16_55_59,,,,,,,,
,,,,,,,,,
Media file(s),,,,,,,,,
,,,,,,,,,
Player #1,O:/A/Video/Folder/the-annotation-file.MP4,,,,,,,,
,,,,,,,,,
Observation date,2021-07-11 16:56:28,,,,,,,,
,,,,,,,,,
Description,FT-sample,,,,,,,,
,,,,,,,,,
Time offset (s),0,,,,,,,,
,,,,,,,,,
independent variables,,,,,,,,,
variable,value,,,,,,,,
,,,,,,,,,
Time,Media file path,Total length,FPS,Subject,Behavior,Behavioral category,Comment,Status

Note that Firetail will use the Observation date to set a frame of reference along with the Time offset (s) information for any subsequent events. The Time column of the observations is then added to the observation date.

In order to reliably load the annotation along with your acceleration data make sure the timestamps are in the same time range. Annotations that happen before the initial or after the last timestamp of the acceleration data will not show.

Firetail’s annotation mechanism relies on bursts. If an annotation start is not covered by a burst it currently (v10) won’t show.