Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Annotation Tools

Authors
Affiliations
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley

The annotation form element adds interactive tools for marking time positions and frequency-time regions. Five annotation tools are available:

Without an annotation element in the form config, the spectrogram has no click/drag interaction. When multiple tools are listed, a dropdown appears in the form panel to switch between them.

Time Select

A single vertical line spanning the full spectrogram height. Click anywhere to place it, or drag the handle at the top to reposition.

annotation:
    start_time:
        label: start
        column: start_time
        source_value: start_time
    tools: time_select

When tools is a string instead of a list, no dropdown is shown — the tool is used directly.

Start/End Time Select

Two vertical lines — green for start, pink for end — with a shaded region between them. The lines are constrained so they cannot cross each other. Click near a line to grab and drag it.

annotation:
    start_time:
        label: start
        column: start_time
        source_value: start_time
    end_time:
        label: end
        column: end_time
        source_value: end_time
    tools: start_end_time_select

Bounding Box

A rectangle defined by time (x-axis) and frequency (y-axis). Click and drag on empty space to draw a new box. Individual edges can be dragged to resize.

annotation:
    start_time:
        label: start
        column: start_time
        source_value: start_time
    end_time:
        label: end
        column: end_time
        source_value: end_time
    min_frequency:
        label: min freq
        column: min_freq
    max_frequency:
        label: max freq
        column: max_freq
    tools: bounding_box

Multibox

Draw multiple bounding boxes on a single spectrogram. Each box is color-coded and can have its own form values (e.g. a species label per box). On submit, one output row is written per box.

annotation:
    start_time:
        label: start
        column: start_time
        source_value: start_time
    end_time:
        label: end
        column: end_time
        source_value: end_time
    min_frequency:
        label: min freq
        column: min_freq
    max_frequency:
        label: max freq
        column: max_freq
    tools:
        - bounding_box
        - multibox
    form: label_form
dynamic_forms:
    label_form:
        - select:
              label: species
              column: common_name
              required: true
              items:
                  path: data/categories-small.csv
                  value: common_name

The form key references a section in dynamic_forms. For multibox, each box gets its own instance of that form. For all other tools, a single instance is shown alongside the annotation inputs.

Fixed Duration

A time region of a set length, centred where you click. Drag it to reposition, use the arrow keys to nudge it, and Delete to remove it. Give the length either as a fixed number of seconds (fixed_duration: 3 or {window: 3}), or as initial_window that the user can change in the form panel, optionally within min/max in steps of step.

annotation:
    tools:
        - fixed_duration:
              min: 0.5
              max: 10
              step: 0.5
              initial_window: 3

Combining Tools

List multiple tools to let the user switch between them from a dropdown:

tools:
    - time_select
    - start_end_time_select
    - bounding_box
    - multibox
    - fixed_duration

Values for all configured fields are always written to the output regardless of which tool is active.

Configuration Fields

Each annotation field accepts:

KeyDescription
labelDisplay label next to the numeric input
columnOutput column name
source_valueColumn from the input row to initialize the value

min_frequency and max_frequency can also be specified as a simple string (the output column name) instead of a dictionary:

min_frequency: min_freq
max_frequency: max_freq

Full Example

The Data Collection notebook demonstrates all five tools with per-annotation species labeling:

data-collection-example.yaml
title:
  value: ANNOTATE CLIP
  progress_tracker: true
pass_value:
  source_column: id
  column: detection_id
annotation:
  tools:
    - multibox
    - bounding_box
    - start_end_time_select
    - time_select
    - fixed_duration:
        min: 0.5
        step: 0.5
        max: 10
        initial_window: 3
  form: species_form
dynamic_forms:
  species_form:
    - select:
        label: species
        column: annotated_common_name
        required: true
        items:
          path: data/species_counts.N-dse.csv
          value: common_name
          filter_box: true
          custom_value: true
          not_available:
            label: Unknown Species
            value: unknown
submission_buttons:
  line: true
  next:
    label: Skip
  submit:
    label: Submit