README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- 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-",
  fig.align = "center",
  out.width = "70%",
  warning = FALSE
)
```

# timevarcorr

<!-- badges: start -->
[![CRAN
status](https://www.r-pkg.org/badges/version/timevarcorr)](https://CRAN.R-project.org/package=timevarcorr)
[![R-CMD-check](https://github.com/courtiol/timevarcorr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/courtiol/timevarcorr/actions/workflows/R-CMD-check.yaml)
[![test-coverage](https://github.com/courtiol/timevarcorr/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/courtiol/timevarcorr/actions/workflows/test-coverage.yaml)
[![Lifecycle:
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

This R package aims at measuring how the correlation between 2 time-series changes over time, following the method described in Choi & Shin (2021):

Choi, JE., Shin, D.W. Nonparametric estimation of time varying correlation coefficient.
J. Korean Stat. Soc. 50, 333–353 (2021). <doi:10.1007/s42952-020-00073-6>

The chief idea is to perform a non-parametric kernel smoothing (using a common bandwidth) of all underlying components required for the computation of a correlation coefficient (i.e., $x$, $y$, $x^2$, $y^2$, $x*y$).

The automatic selection procedure for the bandwidth parameter proposed in the paper is implemented in this package.
The same goes for the computation of confidence intervals.

We also implemented the possibility to use Epanechnikov, Gaussian, or box kernels, as well as to estimate either the Pearson or the Spearman correlation coefficient.


## Installation

You can install the CRAN version of **timevarcorr** with:

```{r CRAN_install, eval=FALSE}
install.packages("timevarcorr")
```

You can install the development version of **timevarcorr** from GitHub with:

```{r GH_install, eval=FALSE}
# install.packages("remotes") ## uncomment and run if you don't have this package installed
remotes::install_github("courtiol/timevarcorr")
```

That should suffice!

Note that this package relies so far on only one direct dependency -- [**lpridge**](https://github.com/cran/lpridge) -- which itself depends on nothing but a plain R install.

Nonetheless, in some of the examples below, we also rely on [**dplyr**](https://dplyr.tidyverse.org) and  [**ggplot2**](https://ggplot2.tidyverse.org), so you would need to install these packages as well to reproduce the content of this README:

``` r
install.packages("dplyr")
install.packages("ggplot2")
```


## Examples

The main function of this package is called `tcor` and its documentation is available here:

```{r help, eval=FALSE}
help(tcor, package = timevarcorr)
```

Here is a very simple example using base-R syntax:

```{r example}
library(timevarcorr)

d <- stockprice[1:500, ]
example1 <- with(d, tcor(x = SP500, y = FTSE100, t = DateID, kernel = "normal"))
plot(example1, type = "l")
```

Here is the same example using tidyverse syntax (with confidence interval):

```{r example2, message=FALSE}
library(dplyr)
library(ggplot2)

d |> 
  reframe(tcor(x = SP500, y = FTSE100, t = DateID,
               kernel = "normal", CI = TRUE)) |>
  ggplot() +
    aes(x = t, y = r, ymin = lwr, ymax = upr) +
    geom_ribbon(fill = "grey") +
    geom_line() +
    labs(title = "SP500 vs FTSE100", x = "Time", y = "Correlation") +
    theme_classic()
```

And now, the same example showing gaps of observations in the time series:

```{r example3}
d |> 
  reframe(tcor(x = SP500, y = FTSE100, t = DateID,
               kernel = "normal", CI = TRUE, keep.missing = TRUE)) |>
  ggplot() +
    aes(x = t, y = r, ymin = lwr, ymax = upr) +
    geom_ribbon(fill = "grey") +
    geom_line() +
    labs(title = "SP500 vs FTSE100", x = "Time", y = "Correlation") +
    theme_classic()
```

You can do more. For example, you can use other kernels, fix the bandwidth manually, or use the Spearman's rather than the Pearson's correlation coefficient:

```{r example4}
example2 <- with(d, tcor(x = SP500, y = FTSE100, t = DateID,
                 cor.method = "spearman", kernel = "box", h = 10))
plot(example2, type = "l")
```

You can also test the difference in correlation coefficients between two time points:

```{r example5}
example3 <- with(d, tcor(x = SP500, y = FTSE100, t = DateID, kernel = "normal", CI = TRUE))
test_equality(example3, t1 = "2000-05-02", t2 = "2001-05-02")
```

Or you can test if specific time points (or all) differ from a reference value:

```{r example6}
test_ref(example3, t = c("2000-05-02", "2001-05-02"), r_ref = 0.5)
```


## Devel corner

This README file has been compiled using `devtools::build_readme()`, with the following setup:

```{r sessioninfo}
devtools::session_info()
```