---
title: "A Guide for the R Package `rhythm.metrics`"
author: "Cong Zhang, Newcastle University"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    number_sections: true
vignette: >
  %\VignetteIndexEntry{rhythm.metrics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
fontsize: 11pt
---

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

 
\newpage
# List of Functions 

## Calculations
+ delta_cv
+ varco_cv
+ percentage_v
+ rpvi_c 
+ npvi_v

## Plotting
+ plot_delta_cv
+ plot_varco_cv
+ plot_percentage_v
+ plot_rpvi
+ plot_npvi
 
 
# Installation
```{r setup, eval = FALSE}
install.packages("devtools")
devtools::install_github("congzhang365/rhythm.metrics")
```

# Import packages
```{r import libraries, warning=F, message=FALSE}
library(rhythm.metrics)
library(dplyr)
library(ggplot2)
```
\newpage

# Examples

## Create dataframe

```{r}
df <- data.frame (cv_label  = c("consonant", "vowel", "consonant", "vowel",
                                "consonant", "vowel", "consonant", "vowel",
                                "consonant", "vowel", "consonant", "vowel",
                                "consonant", "vowel", "consonant", "vowel"),
                  utterance_id = c("utt_1", "utt_1", "utt_1", "utt_1",
                                   "utt_2", "utt_2", "utt_2", "utt_2",
                                   "utt_3", "utt_3", "utt_3", "utt_3",
                                   "utt_4", "utt_4", "utt_4", "utt_4"),
                  cv_duration = c(0.1, 0.8, 0.2, 0.5, 
                                  0.3, 0.3, 0.4, 0.7,
                                  0.3, 0.88, 0.5, 0.9, 
                                  0.3, 0.57, 0.4, 0.97),
                  utterance_duration = c(2.4, 2.4, 2.4, 2.4,
                                         2.7, 2.7, 2.7, 2.7,
                                         3.4, 3.4, 3.4, 3.4,
                                         1.8, 1.8, 1.8, 1.8))
df
```

\newpage
## delta_cv

Delta C and Delta V are rhythm metrics based on Ramus, F., Nespor, M., & Mehler, J. (1999). Correlates of linguistic rhythm in the speech signal. Cognition, 73(3), 265-292.

`Delta C: SD of total C duration`  
`Delta V: SD of total V duration`


```{r}
delta_cv(df, cv_label, utterance_id, cv_duration)
```


```{r}
plot_delta_cv(df, cv_label, utterance_id, cv_duration)
```

\newpage
## varco_cv

Varco C and Varco V are rhythm metrics based on Dellwo, Volker (2006). Rhythm and Speech Rate: A Variation Coefficient for deltaC. In: Karnowski, P; Szigeti, I. Language and language-processing. Frankfurt/Main: Peter Lang, 231-241.

`Varco C: Delta C / mean(C duration) * 100`  
`Varco V: Delta V / mean(V duration) * 100`


```{r}
varco_cv(df, cv_label, utterance_id, cv_duration)
```


```{r}
plot_varco_cv(df, cv_label, utterance_id, cv_duration)
```

\newpage
## percentage_v

%V is a rhythm metrics based on Ramus, F., Nespor, M., & Mehler, J. (1999). Correlates of linguistic rhythm in the speech signal. Cognition, 73(3), 265-292. It calculates the percentage of an utterance occupied by vocalic material.

`%V: (total V duration / total utterance duration) * 100`


```{r}
percentage_v(df, v_label = "vowel", utterance_id, cv_duration, utterance_duration)
```


```{r}
plot_percentage_v(df, cv_label, label_name = "vowel", 
                  utterance_id, cv_duration, utterance_duration)
```

\newpage
## rpvi_c

rPVI C is a rhythm metrics based on Grabe, E., & Low, E. L. (2002). Durational variability in speech and the rhythm class hypothesis. In Laboratory phonology 7 (pp. 515-546). De Gruyter Mouton.

It calculates the sum of the absolute differences between pairs of consecutive consonantal intervals divided by the number of pairs in the speech sample.


```{r}
rpvi_c(df, cv_label, label_name = "consonant", utterance_id, cv_duration)
```


```{r}
plot_rpvi(df, cv_label, label_name = "consonant", utterance_id, cv_duration)
```

\newpage
## npvi_v

nPVI V is a rhythm metrics based on Grabe, E., & Low, E. L. (2002). Durational variability in speech and the rhythm class hypothesis. In Laboratory phonology 7 (pp. 515-546). De Gruyter Mouton.

It calculates the normalised sum of the absolute differences between pairs of consecutive vocalic intervals divided by the number of pairs in the speech sample.


```{r}
npvi_v(df, cv_label, label_name = "vowel", utterance_id, cv_duration)
```



```{r}
plot_npvi(df, cv_label, label_name = "vowel", utterance_id, cv_duration)
```