---
title: "Annotations: handling labelled audio data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Annotations: handling labelled audio data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, message=FALSE}
library(sonicscrewdriver)
```

## Managing labelled audio data in R with SonicScrewdriveR

### Setting annotation boundaries

SonicScrewdriveR provides a set of functionality to read, generate, manage and write label data for audio files. This `Annotation` class is used to consistently handle annotations to audio files. Annotations are delimited in the time domain (seconds) and frequency domain (Hz).

```{r}
a1 <- annotation(
  start = 0,
  end = 1
)

a2 <- annotation(
  low = 0,
  high = 1000
)
```

`Inf` can be used as a value to `end` or `high` to indicate that the annotation extends to the limits of the file.

```{r}
a3 <- annotation(
  start = 0,
  end = Inf
)

a4 <- annotation(
  low = 0,
  high = Inf
)
```

### Handling metadata

Objects of the `Annotation` class have inbuilt character slots for storing the file name (`file`) and the `source`, `type` and `value` of the annotation. A list slot `metadata` is provided for storing additional metadata.

The `file`, `source`, `type` and `value` slots are used by SonicScrewdriveR. For example, the `merge_annotations` function uses these slots to appropriately merge overlapping annotations.

When using tools from SonicScrewdriveR these slots may be pre-populated. The example below creates an `Annotation` object equivalent to one generated by the function `birdNetAnalyse`.

```{r}
a5 <- annotation(
  start=27,
  end=30,
  file = "example.wav",
  source = "BirdNet-Analyzer",
  type = "birdnet-detection",
  value = "sparrow",
  metadata = list(
    confidence = 0.9
  )
)
```

### Reading annotations

#### From audioblast database

```{r, results=FALSE}
# Fetch annotations from audioBlast as `Annotation` objects
a <- audioblast("data", "annomate", source="bio.acousti.ca", id=10754, output="Annotations")
```

### Generating annotations

#### Using BirdNET

```{r, eval=FALSE}
# Analyse sound files using BirdNET-Analyzer
f <- system.file("extdata", "AUDIOMOTH.WAV", package="sonicscrewdriver")
annotations <- birdNetAnalyse(f, output="Annotation")
```

### Merging annotations

The `merge_annotations` function can be used to merge overlapping annotations. The function will merge annotations with overlapping time extents with the same `file`, `type`, `value` and optionally `source` slots.

```{r}
a <- list(
  annotation(
    start=27,
    end=30,
    file = "example.wav",
    source = "BirdNet-Analyzer",
    type = "birdnet-detection",
    value = "sparrow",
    metadata = list(
      confidence = 0.9
    )
  ),
  annotation(
    start=30,
    end=33,
    file = "example.wav",
    source = "BirdNet-Analyzer",
    type = "birdnet-detection",
    value = "sparrow",
    metadata = list(
      confidence = 0.8
    )
  )
)

merge_annotations(a)
```

The two annotations in the list `a` overlap in time and have the same `file`, `type` and `value` slots. The `merge_annotations` function has merged these into a single annotation with the time extent from 27 to 33 seconds.

### Writing annotations

#### Audacity label file

```{r eval=FALSE}
# Convert the annotations to an Audacity label file
writeAudacityLabels(annotations, "birdnet_annotations.txt")
```