onsetsync

onsetsync: An R Package for Onset Synchrony Analysis - Published in JOSS (2024)

https://github.com/tuomaseerola/onsetsync

Repository

Onset synchrony functions

README.Rmd

---
output: github_document
---



```{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


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


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

For documentation, see [ Quick Guide](https://tuomaseerola.github.io/onsetsync/articles/onsetsync.html).

## 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",force = TRUE)
```

## Usage

```{r, message=FALSE, warning=FALSE,echo=TRUE}
library(onsetsync)
library(dplyr)
library(ggplot2)
packageVersion("onsetsync")
```
### Reading in data

Read onsets of one Cuban Son performance titled _Palo Santo_ from _IEMP_ dataset at [https://osf.io/sfxa2/](https://osf.io/sfxa2/). This song has the onsets and the annotations about the metric cycles already extracted and defined and **comes with the package**.

Go and listen to the song at OSF.

```{r message=FALSE,warning=FALSE,eval=TRUE,results='asis'}
CSS_Song2 <- onsetsync::CSS_IEMP[[2]]  # Read one song from internal data
CSS_Song2 <- dplyr::select(CSS_Song2,Label.SD,SD,Clave,Bass,Guitar,Tres,
                           CycleTime,Cycle,Isochronous.SD.Time) # Select some columns
print(knitr::kable(head(CSS_Song2),format = "simple",digits = 2))
```

Reading data from is easy either from CSV files in your computer or directly from OSF using `get_OSF_csv` function.

### Visualise onsets structures

As an overview, we can visualise the onsets across the beat sub-divisions for each instrument and do this across the time. Note that time run vertically (from bottom to up) here.

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

### Calculate asynchronies

To what degree are the pairs of instruments synchronised to each other? Let's visualise the synchrony of all pairings of the instruments in this example.

```{r fig2,warning=FALSE,fig.width=7.4, fig.asp=.7}
inst <- c('Clave','Bass','Guitar','Tres')              # Define instruments 
dn <- sync_execute_pairs(CSS_Song2, inst, beat = 'SD') # Calculate ansychr.
fig2 <- plot_by_pair(dn)                               # Plot
print(fig2)  
```

As we saw in the first figure, 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 often varies dramatically. Comparison of mean asynchronies across sub-divisions can be facilitated by taking random samples of the joint onsets. Here we choose a random 200 matching onsets and re-calculate the comparison of asynchrony with this subset 1000 times.

```{r paired1}
set.seed(1234) # set random seed
N <- 200 # Let's select 200 onsets
Bootstrap <- 100 # Let's bootstrap this 100 times
d1 <- sync_sample_paired(df=CSS_Song2,
                         instr1 = 'Clave',
                         instr2 = 'Bass',
                         n = N,
                         bootn = Bootstrap,
                         beat = 'SD')
dplyr::summarise(data.frame(d1), N=n(), M = mean(asynch*1000), SD = sd(asynch*1000))
```

There are other measures to summarise the asynchronies and visualise them. 

For more examples, see [Get started](https://tuomaseerola.github.io/onsetsync/articles/onsetsync.html).

Read the [community guidelines](CONTRIBUTING.md) for contributing to the package or asking questions.

Owner

JOSS Publication

onsetsync: An R Package for Onset Synchrony Analysis

Published

January 06, 2024

DOI

10.21105/joss.05395

Volume 9, Issue 93, Page 5395

Authors

Tuomas Eerola
Department of Music, Durham University

Martin Clayton
Department of Music, Durham University

Editor

Fabian-Robert Stöter

Tags

music entrainment periodicity synchrony

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago