README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "75%"
)
```

# onsetsync - Analysis and Visualisation of Synchronisation of Music Onset Data


<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

`onsetsync` is a R package for musical dynamics involving synchrony. There are functions for common operations such as adding isochronous beats based on metrical structure, adding annotations, calculating classic measures of synchrony between two performers, and assessing periodicity of the onsets, and visualising synchrony across cycles, time, or another property. 

## Installation

You can install the current version of `onsetsync` from Github by
entering the following commands into R:

```{r,eval=FALSE}
if (!require(devtools)) install.packages("devtools")
devtools::install_github("tuomaseerola/onsetsync")
```

## Usage

Note that `onsetsync` is not dedicated to extraction of onsets from audio as that can be done in other packages (e.g. [Librosa](https://librosa.org), or [Mir Toolbox for Matlab](https://www.jyu.fi/hytk/fi/laitokset/mutku/en/research/materials/mirtoolbox), or [Sonic Visualiser](https://www.sonicvisualiser.org) using well-known onset detection algorithms. Here we take it as granted that we have extracted the onsets in some of these programs, probably checked them by hand, and we have the onset times recorded into csv files. 

```{r, message=FALSE, warning=FALSE,echo=TRUE}
library(onsetsync)
library(httr)
library(dplyr)
library(ggplot2)
```

```{r message=FALSE,warning=FALSE,eval=TRUE,results='asis'}
CSS_Song2_Onset <- get_OSF_csv('8a347') # Onsets
knitr::kable(head(CSS_Song2_Onset[,1:8,]),format = "simple")

CSS_Song2_Metre <- get_OSF_csv('4cdpr') # Annotations
CSS_Song2_Onset <- dplyr::select(CSS_Song2_Onset,
                                 Label.SD,SD,Clave,Bass,Guitar,Tres) 
```

As the onsets and annotations are in different files, let's first combine the raw onset and annotation with `onsetsync`. Here we first add annotations (using `add_annotation` function) about the cycles into the onset data. We then add isochronous beat times to the data frame using `add_isobeats`, since these are useful reference points for synchrony calculations.

```{r message=FALSE,warning=FALSE,eval=TRUE,results='asis'}
# Add annotations about the cycle to the data frame
CSS_Song2 <- add_annotation(df = CSS_Song2_Onset,
                            annotation = CSS_Song2_Metre$Cycle,
                            time = CSS_Song2_Metre$Time,
                            reference = 'Label.SD')
# Add isochronous beats to the data frame
CSS_Song2 <- add_isobeats(df = CSS_Song2, 
                          instr = 'CycleTime', 
                          beat = 'SD')

print(knitr::kable(head(CSS_Song2),format = "simple",digits = 2))
```


Before moving onto the analysis, let's summarise the onset structures in this piece.

```{r message=FALSE,warning=FALSE,eval=TRUE,results='asis'}
tab1 <- summarise_onsets(df = CSS_Song2, 
                         instr = c('Clave','Bass','Guitar','Tres'))
print(knitr::kable(tab1,digits = 1,
     caption = 'Descriptives for the onset time differences (ms).'))
```

As a broad overview, we can visualise the relative synchrony to equal division subdivision of the beat for each instrument across the time. 

```{r synch2isochron,fig.width=9, fig.height=7.0}
fig1 <- plot_by_beat(df = CSS_Song2, 
                     instr = c('Bass','Clave','Guitar','Tres'), 
                     beat = 'SD', 
                     virtual='Isochronous.SD.Time',
                     pcols=2)
print(fig1)
```

There are several variants of this summary that create different summaries of the onsets across the beats, but let's move on. 

To what degree are the pairs of instruments synchronised in this example? Since the instruments usually play widely different amounts of onsets in a piece, and these are bound to be at different beats sub-divisions, the mutual amount of comparable onsets for each pair varies often dramatically. In order to keep the mean and standard deviations comparable, we will randomly sample joint onsets for both instruments.

```{r paired1}
set.seed(1201) # set random seed
N <- 200 # Let's select 200 onsets
d1 <- sync_sample_paired(CSS_Song2,'Clave','Bass',N,1,'SD',TRUE)
print(paste('Mean asynchrony of',round(mean(d1$asynch*1000),1),
    'ms & standard deviation of',round(sd(d1$asynch*1000),1),'ms'))
```
Let's visualise the synchrony of all pairings of the instruments in this example.

```{r fig4,warning=FALSE}
inst<-c('Clave','Bass','Guitar','Tres') # Define instruments 
dn <- sync_execute_pairs(CSS_Song2,inst,N,10,'SD')
fig2 <- plot_by_pair(dn)  # plot
print(fig2)  
```

For more examples, see [docs IN PROGRESS](https://tuomaseerola.github.io/onsetsync/) and associated [paper IN PROGRESS](http://).