rolwincor_heatmap: Estimate the Rolling Window Correlation for the bi-variate...

Description Usage Arguments Details Value Author(s) References Examples

View source: R/rolwincor_heatmap.R

Description

The rolwincor_heatmap function estimates the rolling window correlation coefficients and their respective p-values between TWO time series (bi-variate case) sampled on identical time points for all the possible (i.e. from 3 to the number of elements of the time series under analysis) window-lengths (time-scales) or for a band of window-lengths to be plotted as a heat map. To carry out the computational implementation we extend the works of Telford (2013), Polanco-Martínez (2019), and Polanco-Martínez (2020). The rolwincor_heatmap function is highly flexible since this contains several parameters to control the estimation of correlation. A list of parameters are described in the following lines.

Usage

1
2
3
4
rolwincor_heatmap(inputdata, varX="", varY="", CorMethod="pearson", 
                  typewidthwin="FULL", widthwin_1=3, 
                  widthwin_N=dim(inputdata)[1], Align="center", 
                  pvalcorectmethod="BH", rmltrd=TRUE, Scale=TRUE)

Arguments

inputdata

Matrix of 3 columns: time, first variable (e.g. X), and second variable (e.g. Y).

varX, varY

Names of the first (e.g. X) and second (e.g. Y) variable. Please note that the names of these two variables MUST be defined.

CorMethod

The method used to estimate the correlations, by default is “pearson” but other options (“spearman” and “kendall”) are available (please look at: R>?cor.test).

typewidthwin

“FULL” is to estimate the windows from 2, 4, ..., to dim(inputdata)[1]) if Align is equal to “left” or “right”, or from 3, 5,..., to dim(inputdata)[1]) if Align is “center”. The other option is “PARTIAL”, please you should take into account that widthwin_1 and widthwin_1 MUST be ODD if the Align option is “center”.

widthwin_1

First value for the size (length) of the windows when the option typewidthwin=“PARTIAL” is selected, the minimum value is 3 (the default value), but you must define this parameter (please note that widthwin_1 < widthwin_N).

widthwin_N

Last value for the size (length) of the windows when the option typewidthwin=“PARTIAL” is selected, by default is dim(inputdata)[1], but you must define this parameter (please note that widthwin_1 < widthwin_N).

Align

To align the rolling object, RolWinMulCor uses three options: “left”, “center”, and “right” (please look at: R>?running). However, there are some restrictions, which have been described lines above. We recommend to use the “center” option to ensure that variations in the correlations are aligned with the variations in the relationships of the variables under study, rather than being shifted to left or right (Polanco-Martínez 2019, 2020), but this imply that the window-lengths MUST be ODD.

pvalcorectmethod

The p-value correction method to be used, by default the method of Benjamini and Hochberg (BH) (1995) is used since this is less conservative and performs much better than Bonferroni, but other five methods (Holm, Hochberg, Bonferroni, Hommel, and Benjamini and Yekutieli) are available (please look at: R>?p.adjust). Moreover, pvalcorectmethod admits a pass-through option named “none” (p-values will not be corrected).

rmltrd

Remove (by default is “TRUE”; “FALSE” otherwise) the linear trend in the time series under analysis.

Scale

Scale (by default is “TRUE”; “FALSE” otherwise) is used to “normalize” or “standardize” the time series under analysis.

Details

The rolwincor_heatmap function estimates the rolling window correlation between TWO time series (bi-variate case) sampled on identical time points for all the possible (i.e. from 3 to the number of elements of the time series under analysis) window-lengths (time-scales) or for a band of window-lengths to be plotted the rolling correlation coefficients and their respective p-values as a heat map. rolwincor_heatmap uses the functions running (package:gtools), the native R functions cor, cor.test, and p.adjust (package:stats), and some pieces of code written specifically to our R RolWinMulCor package.

Value

Outputs:

Numerical output: three lists matcor, pvalscor, and pvalNOTcor containing the correlation matrix and their corresponding corrected and not corrected p-values, as well as NoWindows and Windows that contains the number of windows and the window-lengths (time-scales), and CorMethod, left_win, and righ_win, which have been previously described.

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
DeustoTech - Deusto Institute of Technology,
Faculty of Engineering, University of Deusto,
Avda. Universidades, 24, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue_Polanco-Martinez.
Email: josue.m.polanco@gmail.com, josue.polanco@deusto.es

References

Benjamini, Y., and Hochberg, Y. (1995). Controlling the false discovery rate: a practical and powerful approach to multiple testing. Journal of the Royal Statistical Society Series B, 57 (1), 289-300. <URL: https://rss.onlinelibrary.wiley.com/doi/10.1111/j.2517-6161.1995.tb02031.x>.

Polanco-Martínez, J. M. (2019). Dynamic relationship analysis between NAFTA stock markets using nonlinear, nonparametric, non-stationary methods. Nonlinear Dynamics, 97(1), 369-389. <URL: https://doi.org/10.1007/s11071-019-04974-y>.

Polanco-Martínez, J. M. (2020). RolWinMulCor : an R package for estimating rolling window multiple correlation in ecological time series. Ecological Informatics (Ms. ECOINF-D-20-00263 accepted for publication, 19/08/2020).

Telford, R.: Running correlations – running into problems (2013). <URL:
https://quantpalaeo.wordpress.com/2013/01/04/running-correlations-running-into-problems/>.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Testing the function rolwincor_heatmap
#  typewidthwin="PARTIAL," window lengths from 21 to 31 and plot output in screen format 
test_rolwincor_heatmap <- rolwincor_heatmap(syntDATA, varX="X", varY="Y", 
                            CorMethod="spearman", typewidthwin="PARTIAL", widthwin_1=11, 
                            widthwin_N=101, Align="center", pvalcorectmethod="BH", 
                            rmltrd=TRUE, Scale=TRUE)
# This example could takes a long time since typewidthwin="FULL" 
test2_rolwincor_heatmap <- rolwincor_heatmap(syntDATA, varX="X", varY="Y",
                             CorMethod="spearman", typewidthwin="FULL", Align="center", 
                             pvalcorectmethod="BH", rmltrd=TRUE, Scale=TRUE)
 

RolWinMulCor documentation built on Aug. 31, 2020, 5:06 p.m.