Data Upload Workflow & IEN Annotation Standard - chimarkhi/bioac_annotations GitHub Wiki
Indian Eco-Acoustics Network (IEN) working group 2025, sent out a bio acoustics data inventory survey to rough size the amount of data present with individuals and institutions (data owners) and gauge their interest in contributing to crowdsourced data for India's first bio acoustics database. 50+ data owners are interested in sharing bio-acoustics data for Indian taxa for the centralized database.
The working group proposes an IEN annotation standard
described in sections below: a combination of folder/file structure and labeling schema that the contributors can follow.This wiki details out the workflow for data upload of media with varying degrees of labels. In following sections annotation templates that make it easy for data owners to both upload and annotate their data at scale are shared. Multiple options are provided to data owners to help them balance the trade-off between upload effort and compliance to annotation best practices. As a result the onus of adherence to a strict data-model of labels is offloaded to data engineering exercise.
The workflow will be first tested with a smaller sample of data owners to collect feedback and iterate. We will use Git wiki questions and zoom sessions to take questions and feedback.
Data upload workflows
Data owners are allowed to choose from the following options while uploading their data:
- Type A [Preferred] : Uploaded data will adhere to IEN annotation standard. This may require them to re-structure data labels to some extent
- Type B: Uploaded data will be annotated but NOT adhere to the IEN annotation standard. Missing columns and custom file formats are accepted.
- Type C: Uploaded data lacks meta-data or acoustic annotations or both. While not immediately useful, such data is a prime candidate for crowd-sourcing annotations and can be used for unsupervised learning and creating augmented training data-sets.
An owner can choose any combination of the above options to categorize their media during the upload process. Data engineering pipeline integrating LLM apis will be used to restructure Type B
and Type C
annotations to IEN's data model. For the uploaded data to be useful Type A
uploads are preferred, so the group will create training docs and videos to educate the contributors.
IEN Annotation Standard
Folder Structure
Primary and metadata information of the media is suggested to be split into two different kind of files, i.e. metadata and acoustic labels. Audio, metadata and annotation files should follow the following file structure. An example of the project structure is example_project[https://github.com/chimarkhi/bioac_annotations/tree/main/Examples/projects/example_project]
root_folder
├── project_1
│ ├── media
| │ ├── audio_file_1.wav
| │ ├── audio_file_2.wav
| │ ├── audio_file_3.flac
| │ └── audio_file_4.mp3
│ ├── meta
| │ ├── meta_0012.txt
| │ └── meta_0014.csv
│ ├── annotation
| │ ├── annotation_1.csv
| │ └── annotation_0235.csv
├── project_2
│ ├── media
| │ ├── audio_file_1.wav
| │ ├── audio_file_2.wav
| │ ├── audio_file_15.wav
| │ └── audio_file_4.mp3
│ ├── meta
| │ ├── meta_1242.txt
| │ └── meta_0254.csv
│ ├── annotation
| │ ├── annotation_4.csv
| │ └── annotation_as13.csv
While sharing the data, it is recommended that each cloud upload be limited to less than 10Mb size and should contain all meta/annotation/media files being referenced within. This can be done by structuring data into separate projects
with all three type of file self contained within it and making sure that the zipped size of a project is not greater that 10Mb.
Media Metadata:
A metadata file name must start with meta
(eg. meta_20jan25.csv
) and contain information about the recording event(s). csv
, tsv
, xls
, xlsx
formats are accepted. There can be one or more metadata files describing any number of media files.
A meta data file should have the following keys/columns:
Column Name | Internal Name | Mandatory | Description |
---|---|---|---|
Media File Name/Media URL | media_file_url |
Yes | unique name of the media file or downloadable url, if the media is uploaded on an open access platform |
Location | location |
Yes | recording location geo-coords (latitude, longitude) eg. (40.7812, 71.2552) |
Recording Datetime | recording_datetime |
Yes | datetime of recording in ISO_8601 format, eg. '2024-11-20T10:23:00+5:30` |
Authors | authors |
Yes | name of the contributor/data-owner |
Data License | license |
Yes | One of the data licensing options described here |
Location Name | location_name |
No | free text location name |
Recording Type | recording_type |
No | PAM/focal recording |
Channels | channels |
No | # Channels in acoustic file |
Is Annotated? | is_annotated |
Yes | Yes/No based on whether the file has accompanying acoustic annotations |
Sampling Interval | sampling_interval |
No | free text description of sampling rate (eg. 10mins every hour) |
Recording Event Description | event_description |
No | description of the recording event |
Notes | notes |
No | location/event/climate information in free text or json |
Acoustic Annotations:
An annotation file name must start with annotation
(eg. annotation_rec123_20jan25_morning.csv
) and contains acoustic labels identifying specific calls. csv
, tsv
, xls
, xlsx
formats are accepted.
A single file can contain information about multiple media files and should have the following keys/columns:
Column Name | Mandatory | Description |
---|---|---|
media_file |
Yes | unique name of the media file |
Begin Time (s) |
Yes | Start time of selection in seconds |
End Time (s) |
Yes | End time of selection in seconds |
LowFreq (kHz) |
No | Lower frequency bound of selection |
HighFreq (kHz) |
No | Upper frequency bound |
Common Name |
Yes | List of identified species common names separated with | |
Species ID |
No | List of identified species scientific names separated with | |
Notes |
Yes | Elaborate free text notes on species, behavior, call type, etc. |
Data upload web-page (TBU)
Below is a tentative wireframe of the data-upload page, containing the above described 3 upload options. On hitting the submit button, the page will analyse the attached annotation
and meta
files to flag any inconsistencies with the prescribed data model if Type A upload option is chosen by the contributor.