Package 'RolWinMulCor'

Estimate the Rolling Window Multiple Correlation

Description

'RolWinMulCor' estimates the rolling (running) window correlation for the bi- and multi-variate cases between regular (sampled on identical time points) time series, with especial emphasis to ecological data although this can be applied to other kinds of data sets. 'RolWinMulCor' is based on the concept of rolling, running, or sliding window correlation and is useful to evaluate the evolution of correlation through time and time-scales. 'RolWinMulCor' contains six (four for estimations and two for plots) functions. The first two functions focus on the bi-variate case: (1) 'rolwincor_1win' and (2) 'rolwincor_heatmap', which estimate the correlation coefficients and their respective p-values for only one window-length (time-scale) and considering all possible window-lengths or a band of window-lengths, respectively. The second two functions: (3) 'rolwinmulcor_1win' and (4) 'rolwinmulcor_heatmap' are designed to analyze the multi-variate case, following the bi-variate case to visually display the results, but these two approaches are methodologically different. That is, the multi-variate case estimate the adjusted coefficients of determination instead of the correlation coefficients. The last two functions: (5) 'plot_1win' and (6) 'plot_heatmap' are used to plot the time series under study and to represent graphically the outputs of the four aforementioned functions as simple plots or as heat maps. The six functions contained in 'RolWinMulCor' are highly flexible since these contain several parameters to control the estimation of correlation and the features of the plot output, e.g. to remove the linear trend contained in the time series under analysis, to choose different p-value correction methods (which are used to address the multiple comparison problem) or to personalise the plot output. The 'RolWinMulCor' package also provides examples with synthetic and real-life ecological time series to exemplify its use.

Details

Package:	RolWinMulCor
Type:	Package
Version:	1.2
Date:	2020-04-13
License:	GPL (>= 2)
LazyLoad:	yes

RolWinMulCor package contains six functions: (1) rolwincor_1win estimates the rolling window correlation coefficients and their respective p-values for the bi-variate case for only one window-length or time-scale for the time series under study; (2) rolwincor_heatmap estimates the correlation coefficients and their corresponding p-values taking into account all the possible window-lengths that are determined by the number of elements of the time series under analysis or a band of window-lengths; (3) rolwinmulcor_1win estimates the rolling window correlation coefficients and their p-values for the multi-variate case for only one window-length or time-scale for the time series under study; (4) rolwinmulcor_heatmap estimates the correlation coefficients and their corresponding p-values for the multi-variate case taking into account all the possible window-lengths or a band of window-lengths; (5) plot_1win plots the time times under analysis and the correlation coefficients and their respective p-values (corrected or not corrected) as only one selected window-length using the outputs of the functions rolwincor_1win (bi-variate case) and rolwinmulcor_1win (multi-variate case); and (6) plot_heatmap plots the time series under scrutiny and the heat map for the correlation coefficients and their respective p-values (corrected or not corrected) for all possible window-lengths (i.e., from five to the number of elements of the time series under analysis) or for a band of window-lengths using the outputs of the functions rolwincor_heatmap (bi-variate case) and rolwinmulcor_heatmap (multi-variate case). The bi-variate case follow from a methodological point of view to Telford (2013), Polanco-Martínez (2019), and Polanco-Martínez (2020) whereas the multi-variate case follow to Abdi (2007) and Polanco-Martínez (2020).

Note

Dependencies: stat, gtools, zoo, pracma and colorspace.

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

Acknowledgement:
The author acknowledges to the SEPE (Spanish Public Service of Employment) for its funding support. Special thanks to the CRAN team (in particular to Martina Schmirl and Jelena Saf), to Ana-Maria Hereş and Jorge Curie for their helpful comments on the package, and for the three reviewers (this package is described in the paper recently published in Ecological Informatics and that is cited in the References section), in particular Reviewer #2, that provided very useful suggestions to improve RolWinMulCor.

References

Abdi H. Multiple correlation coefficient, in Encyclopedia of Measurement and Statistics, N. J. Salkind, Ed. Sage, Thousand Oaks, CA, USA, 2007; 648-651.
<URL: https://personal.utdallas.edu/~herve/Abdi-MCC2007-pretty.pdf>.

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

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

---

Plot the outputs of rolwincor_1win and rolwinmulcor_1win as a single one window

Description

The plot_1win function plots the time series under study and the correlation coefficients and their respective p-values (corrected or not corrected) as only one selected window-length (time-scale) using the outputs of the functions rolwincor_1win (bi-variate case) or rolwinmulcor_1win (multi-variate case). The plot_1win function is highly flexible since this contains several parameters to control the plot output. We would highlight that only the first 11 parameters must be defined by the users, the other parameters are not strictly necessary since these have been defined by default. A list of parameters are described in the following lines.

Usage

plot_1win(inputdata, corcoefs, pvalues, left_win, righ_win, widthwin, 
          KCASE="", varX="", varY="", coltsX=c("black"), coltsY="blue", 
          rmltrd=TRUE, Scale=TRUE, HeigWin1=2.05, HeigWin2=2.75, 
          colCOEF="black", colPVAL="gray", CEXLAB=1.15, CEXAXIS=1.05, 
          LWDtsX=c(1), LWDtsY=1, LWDcoef=1, LWDpval=1, NUMLABX=5, 
          parcen=c(0.5,25))

Arguments

inputdata	Input data used in the functions rolwincor_1win or rolwinmulcor_1win.
corcoefs, pvalues	Correlation coefficients obtained from the functions rolwincor_1win or rolwinmulcor_1win (named Correlation_coefficients) and p-values obtained from the aforementioned functions (named P_values_corrected or P_values_not_corrected).
left_win, righ_win	These parameters are used to accommodate the times in the rolling window correlations and are obtained from the functions rolwincor_1win or rolwinmulcor_1win, which have the same names.
widthwin	Window size to compute the rolling window correlations. This value can be an even or odd number of at least three (the default value), and this parameter is the same as the one used in rolwincor_1win or rolwinmulcor_1win.
KCASE	This parameter is used to activate the cases: “BIVAR” for the bi-variate or “MULVAR” for the multi-variate, and this must be the same as the one used in rolwincor_1win or rolwinmulcor_1win.
varX	Name of the “first” or independent variable, e.g. “X” (please note that “X” is a vector of one element if KCASE=“BIVAR” and a vector of several elements if KCASE=“MULVAR”). For the multi-variate case the names for “X” (the independent variables) will be defined as: varX=paste(“X1”, “X2”,..., sep=”, ”).
varY	Name of the “second” or dependent variable, e.g. “Y”.
coltsX, coltsY	Colors to be used when the variables are plotted, for the bi-variate case by default are “black” for “X” and “blue” for “Y”, but other colors can be used. For the multi-variate case, colors for the dependent (“Y”) and independent variables (“X”) MUST be provided (e.g. coltsX=c("red","blue",...), coltsY="black").
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.
HeigWin1, HeigWin2	Proportion of window's size to plot the time series under analysis (HeigWin1) and the rolling window correlation coefficients and p-values (HeigWin2) (look at: R>?layout to get more information about “layout”). By default HeigWin1 and HeigWin2 have values of 2.05 and 2.75, but other values can be used.
colCOEF, colPVAL	The colors to be used when the correlation coefficients and their corresponding p-values are plotted, by default the colors are “black” and “gray,” but other colors can be used.
CEXLAB, CEXAXIS	These parameters are used to plot the sizes of the X-axis and Y-axis labels and X- and Y-axis, by default these parameters have values of 1.15 and 1.05, respectively, but it is possible to use other values.
LWDtsX, LWDtsY	Line-widths for the first and the second variable when these are plotted, for the bi-variate case by default these have values of 1, but other values (widths) can be used. For the multi-variate case and for the independent variables the line-widths MUST be provided (e.g. LWDtsX = c(1,2,...)).
LWDcoef, LWDpval	The line-widths to be used when the correlation coefficients and their respective p-values are plotted, by default these parameters have a value of 1, but it is possible to use other values.
NUMLABX	Number of labels for (all) the X's axis, by the default is 5, but it is possible to use other values.
parcen	These parameters contain two values: the first one is to control the position of the title, by default it is 0.5, but you should try with other close values to obtain the title centered, e.g. 0.4 or 0.8 (please avoid to use large values); the second value is to define the spaces between the names of variables, by default is 25 spaces, but you could try other values to fit properly the names of variables in the title. We use “mtext” to produce the title (please loot at R>?mtext for more information).

Details

The plot_1win function plots the correlation coefficients and their respective p-values (corrected or not corrected) as only one selected window-length using the outputs of the functions rolwincor_1win (bi-variate case) and rolwinmulcor_1win (multi-variate case).

Value

Output: a single plot (via screen) of the correlation coefficients and their respective (corrected and not corrected) p-values.

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

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

Examples

#######################################################################
# Testing the bi-variate case (1 window), synthetic data!
#######################################################################
# Fig. 3 in Polanco-Martínez (2020) 
test_fun1 <- rolwincor_1win(syntDATA, varX="X", varY="Y", 
                            CorMethod="spearman", widthwin=21, 
                            Align="center", pvalcorectmethod="BH")
# Plotting the bi-variate case (1 window)
plot_1win(syntDATA, test_fun1$Correlation_coefficients, 
         test_fun1$P_values_corrected, test_fun1$left_win, 
         test_fun1$righ_win, widthwin=21, KCASE="BIVAR", 
         varX="X", varY="Y")
#######################################################################
# Testing the multi-variate case (1 window), real-life ecological data! 
#######################################################################
# Fig. 6 in Polanco-Martínez (2020)
test_fun2 <- rolwinmulcor_1win(YX_ecological_data, widthwin=61,
                            Align="center", pvalcorectmethod="BH")
# Plotting the bi-variate case (1 window), real-life ecological data 
plot_1win(YX_ecological_data, test_fun2$Correlation_coefficients, 
          test_fun2$P_values_corrected, test_fun2$left_win, 
          test_fun2$righ_win, widthwin=61, KCASE="MULVAR", varY="PC1", 
          varX=paste("SST", "TSI", sep=", "), coltsY="black", 
          coltsX=c("red", "orange"), CEXLAB=1.15, CEXAXIS=1.65, 
          LWDtsX=rep(2,2), LWDtsY=2, parcen=c(0.45,15))

---

Plot the outputs of rolwincor_heatmap and rolwinmulcor_heatmap as a heat map

Description

The plot_heatmap function plots the time series under study and the correlation coefficients and their respective p-values (corrected or not corrected) as a heat map for all possible window-lengths (i.e., from five to the number of elements in the time series under analysis) or for a band of window-lengths using the outputs of the functions rolwincor_heatmap (bi-variate case) and
rolwinmulcor_heatmap (multi-variate case). The plot_heatmap function is highly flexible since this contains several parameters to control the plot output. We would highlight that only the first 12 parameters (and LWDtsX for the multi-variate case) must be defined by the users since the others parameters are defined by default. A list of parameters are described in the following lines.

Usage

plot_heatmap(inputdata, corcoefs, pvalues, left_win, righ_win, Rwidthwin, 
     KCASE="", typewidthwin="", widthwin_1=3, widthwin_N=dim(inputdata)[1], 
     varX="", varY="", rmltrd=TRUE, Scale=TRUE, coltsX=c("black"), coltsY="blue", 
     CEXLAB=1.15, CEXAXIS=1.05, LWDtsX=1, LWDtsY=1, NUMLABX=5, parcen=c(0.5,25))

Arguments

inputdata	Input data used in the functions rolwincor_heatmap or rolwinmulcor_heatmap.
corcoefs, pvalues	Correlation coefficients obtained from the functions rolwincor_heatmap or rolwinmulcor_heatmap (named Correlation_coefficients) and p-values obtained from the aforementioned functions (named P_values_corrected or P_values_not_corrected).
left_win, righ_win	These parameters are used to accommodate the times in the rolling window correlations and are obtained from the functions rolwincor_heatmap or rolwinmulcor_heatmap, which have the same names.
Rwidthwin	Contains the window-sizes where the rolling window correlations are estimated by the functions rolwincor_heatmap or rolwinmulcor_heatmap.
KCASE	This parameter is used to activate the cases: “BIVAR” for the bi-variate or “MULVAR” for the multi-variate, and this must be the same label as the one used in rolwincor_1win or rolwinmulcor_1win.
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).
varX	Name of the “first” or independent variable, e.g. “X” (please note that “X” is a vector of one element if KCASE=“BIVAR” and a vector of several elements if KCASE=“MULVAR”. For the multi-variate case the names for “X” (the independent variables) will be defined as: varX=paste(“X1”, “X2”,..., sep=”, ”).
varY	Name of the “second” or dependent variable, e.g. “Y”.
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.
coltsX, coltsY	Colors to be used when the variables are plotted, for the bi-variate case by default are “black” for “X” and “blue” for “Y”, but other colors can be used. For the multi-variate case, colors for the dependent (“Y”) and independent variables (“X”) MUST be provided (e.g. coltsX=c("red","blue",...), coltsY="black").
CEXLAB, CEXAXIS	These parameters are used to plot the sizes of the X-axis and Y-axis labels and X- and Y-axis, by default these parameters have values of 1.15 and 1.05, respectively, but it is possible to use other values.
LWDtsX, LWDtsY	Line-widths for the first and the second variable when these are plotted, for the bi-variate case by default these have values of 1, but other values (widths) can be used. For the multi-variate case and for the independent variables the line-widths MUST be provided (e.g. LWDtsX = c(1,2,...)).
NUMLABX	Number of labels for (all) the X's axis, by the default is 5, but it is possible to use other values.
parcen	These parameters contain two values: the first one is to control the position of the title, by default it is 0.5, but you should try with other close values to obtain the title centered, e.g. 0.4 or 0.8 (please avoid to use large values); the second value is to define the spaces between the names of variables, by default is 25 spaces, but you could try other values to fit properly the names of variables in the title. We use “mtext” to produce the title (please loot at R>?mtext for more information).

Details

The plot_heatmap function plots the time series under study and the heat map for the correlation coefficients and their respective p-values (corrected or not corrected) for all possible window-lengths (i.e., from five to the number of elements in the time series under analysis) or for a band of window-lengths. plot_heatmap uses the outputs of the functions rolwincor_heatmap (bi-variate case) and rolwinmulcor_heatmap (multi-variate case).

Value

Output: a heat map (via screen) of the correlation coefficients and their respective (corrected or not corrected) p-values.

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

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

Examples

######################################################################
# Testing the bi-variate case (heat map). Example: synthetic data! 
# Fig. 4 in Polanco-Martínez (2020) 
test_fun2 <- rolwincor_heatmap(syntDATA, varX="X", varY="Y",
                       CorMethod="spearman", typewidthwin="PARTIAL",
                       widthwin_1=11, widthwin_N=101, Align="center")
# Plotting the bi-variate case (heat map). Example: synthetic data! 
plot_heatmap(syntDATA, test_fun2$matcor, test_fun2$pvalscor, test_fun2$left_win, 
             test_fun2$righ_win, test_fun2$Windows, KCASE="BIVAR", 
             typewidthwin="PARTIAL", varX="X", varY="Y", widthwin_1=11, 
             widthwin_N=101)
######################################################################
# Testing the bi-variate case (heat map). Example: real-life ecological data
######################################################################
# Fig. 5 (left) in Polanco-Martínez (2020)
SST_PC1 <- rolwincor_heatmap(YX_ecological_data[,c(1,3,2)], varX="SST",
                 varY="PC1", CorMethod="spearman", typewidthwin="FULL", 
                 Align="center", pvalcorectmethod="BH")
# Plotting the bi-variate case (heat map). Example: real-life ecological data 
plot_heatmap(YX_ecological_data[,c(1,3,2)], SST_PC1$matcor, SST_PC1$pvalscor,
     SST_PC1$left_win, SST_PC1$righ_win, SST_PC1$Windows, KCASE="BIVAR",
     typewidthwin="FULL", varX="SST", varY="PC1", coltsX="red", CEXLAB=1.15,
     CEXAXIS=1.65, coltsY="black", LWDtsX=2, LWDtsY=2)
######################################################################
# Testing the multi-variate case (heat map). Example: real-life ecological data
######################################################################
# Fig. 6 in Polanco-Martínez (2020)
SST_TSI_PC1 <- rolwinmulcor_heatmap(YX_ecological_data, typewidthwin="FULL",
                                    Align="center", pvalcorectmethod="BH")
# Plotting the multi-variate case (heat map). Example: real-life ecological data
plot_heatmap(YX_ecological_data, SST_TSI_PC1$matcor, SST_TSI_PC1$pvalscor,
      SST_TSI_PC1$left_win, SST_TSI_PC1$righ_win, Rwidthwin=SST_TSI_PC1$Windows,
      KCASE="MULVAR", typewidthwin="FULL", varY="PC1", varX=c("SST", "TSI"),
      coltsY="black", coltsX=c("red", "orange"), CEXLAB=1.15, CEXAXIS=1.65,
      LWDtsX=rep(2,2), LWDtsY=2, parcen=c(0.45,15))

---

Estimate the Rolling Window Correlation for the bi-variate case to plot its outputs as a single one window

Description

The rolwincor_1win function estimates (correlation coefficients and their respective p-values) the rolling (running) window correlation between TWO time series (bi-variate case) sampled on identical time points for ONLY ONE window-length (time-scale). To carry out the computational implementation we follow to Telford (2013), Polanco-Martínez (2019), and Polanco-Martínez (2020). The rolwincor_1win function is highly flexible since this contain several parameters to control the estimation of correlation. For example, rolwincor_1win function contain parameters to remove the (linear) trend contained in the time series under analysis or to choose different p-value correction methods (which are used to address the multiple comparison problem). A list of parameters are described in the following lines.

Usage

rolwincor_1win(inputdata, varX="", varY="", CorMethod="pearson", widthwin=3,
               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$). Please note that time's resolution can be annual, seasonal, monthly, etc, but the format must be in the following form: e.g. for monthly data, year 1 must be repeated 12 times (thus, these times will correspond to 12 rows), year 2 must be also repeated 12 times, and so on. 'Times' must be regular (equally spaced in time and not missing data).
varX, varY	Names of the first (e.g. $X$) and second (e.g. $Y$) variable. Please note that the names of these 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).
widthwin	Window size to compute the rolling window correlations. This value can be an even or odd number of at least three (the default value), and this parameter MUST be provided.
Align	To align the rolling object, RolWinMulCor ONLY uses the “center” option by default (please look at: R>?running) to ensure that variations in the correlation are aligned with the variations in the relationship of the time series under study rather than being shifted (Polanco-Martínez 2019, 2020), but the “left” and “right” options can be used, but if widthwin is an even number it will not be possible to use the “center” option (please look at: R>?running).
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 two 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_1win function estimates the rolling window correlation between TWO time series (bi-variate case) sampled on identical time points for ONLY ONE window-length (time-scale) and plots the rolling correlation coefficients and their respective p-values. rolwincor_1win 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: a list containing Correlation_coefficients, P_values_corrected, and
P_values_not_corrected, which are self-explanatory, as well as CorMethod, left_win, righ_win, and widthwin, which indicate the method used to estimate the correlations, first and last time element of the rolling correlation matrix, and the window-length (time-scale).

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

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

Examples

# Testing the function rolwincor_1win (bi-variate case)
# Window length = 21 and plot output in screen format 
# Estimation to generate the output for Fig. 3 in Polanco-Martínez (2020). 
test_rolwincor_1win <- rolwincor_1win(syntDATA, varX="X", varY="Y", CorMethod="spearman", 
                                      widthwin=21, Align="center", pvalcorectmethod="BH")

---

Estimate the Rolling Window Correlation for the bi-variate case to plot its outputs as a heat map

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

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$). Please note that time's resolution can be annual, seasonal, monthly, etc, but the format must be in the following form: e.g. for monthly data, year 1 must be repeated 12 times (thus, these times will correspond to 12 rows), year 2 must be also repeated 12 times, and so on. 'Times' must be regular (equally spaced in time and not missing data).
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).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

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

Examples

# Testing the function rolwincor_heatmap
# typewidthwin="PARTIAL," window lengths from 11 to 101 and plot output in screen format 
# Code used to produce the outputs to generate the Fig. 4 in Polanco-Martínez (2020). 
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)

---

Estimate the Rolling Window Correlation for the multi-variate case to plot its outputs as a single one window

Description

The rolwinmulcor_1win function estimates the rolling window correlation coefficients and their respective p-values among multiple time series (multi-variate case) sampled on identical time points for ONLY ONE window-length (time-scale). The multi-variate case is based on the concept of multiple regression and generalizes the standard coefficient of correlation (the squared multiple correlation coefficient, or more appropriate, the adjusted coefficient of determination, $R^2$). We follow to Abdi (2007) and Polanco-Martínez (2020) to implement computationally this technique. The rolwinmulcor_1win function is highly flexible since this contains several parameters to control the estimation of correlation. For example, rolwinmulcor_1win function contains parameters to remove the (linear) trend contained in the time series under analysis, to choose different p-value correction methods (which are used to address the multiple comparison problem). A list of parameters are described in the following lines.

Usage

rolwinmulcor_1win(inputdata, varnametsY="", varnametsX="", widthwin=5, 
                  Align="center", pvalcorectmethod="BH", 
                  rmltrd="TRUE", Scale="TRUE")

Arguments

inputdata	Matrix of P columns: time, dependent variable ($Y$), and independent variables ($X_1, X_2,..., X_{P-2}$). Please note that time's resolution can be annual, seasonal, monthly, etc, but the format must be in the following form: e.g. for monthly data, year 1 must be repeated 12 times (thus, these times will correspond to 12 rows), year 2 must be also repeated 12 times, and so on. 'Times' must be regular (equally spaced in time and not missing data).
varnametsY	Name of the dependent variable: $Y$. Please note that the name of this variable MUST be defined.
varnametsX	Name of the independent variables: $X_1, X_2,..., X_{p-2}$. Please note that the names of these variables MUST defined in this way: varnametsX=paste("X1", "X2",..., sep=", ").
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.
widthwin	Window size to compute the rolling window correlations. This value can be an even or odd number of at least three (the default value), and this parameter MUST be provided.
Align	To align the rolling object, RolWinMulCor ONLY uses the “center” option by default (please look at: R>?running) to ensure that variations in the correlation are aligned with the variations in the relationship of the time series under study rather than being shifted (Polanco-Martínez 2019, 2020), but the “left” and “right” options can be used, but if widthwin is an even number it will not be possible to use the “center” option (please look at: R>?running).
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).

Details

The rolwinmulcor_1win function estimates the rolling window correlation coefficients and their respective p-values among multiple time series (multi-variate case) sampled on identical time points for ONLY ONE window-length. rolwinmulcor_1win uses the functions rollapply (package:zoo) that is able to tackle matrices, the native R function p.adjust (package:stats), and some pieces of code and an auxiliary function that we have created specifically for our function
rolwinmulcor_1win and R RolWinMulCor package.

Value

Outputs:

Numerical output: three list containing Correlation_coefficients, P_values_corrected, and
P_values_not_corrected, which are self-explanatory, as well as left_win, righ_win, and widthwin, which indicate the method used to estimate the correlations, first and last time element of the rolling correlation matrix, and the window-length (time-scale).

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

References

Abdi H. Multiple correlation coefficient, in Encyclopedia of Measurement and Statistics, N. J. Salkind, Ed. Sage, Thousand Oaks, CA, USA, 2007; 648-651.
<URL: https://personal.utdallas.edu/~herve/Abdi-MCC2007-pretty.pdf>.

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

Examples

# Testing the function rolwinmulcor_1win (multi-variate case)
 # Estimates the outputs to generate Fig. 6 in Polanco-Martinez (2020). 
 test_rolwinmulcor_1win <- rolwinmulcor_1win(YX_ecological_data, widthwin=61,
                            Align="center", pvalcorectmethod="BH")

---

Estimate the Rolling Window Correlation for the multi-variate case to plot the results as a heat map

Description

The rolwinmulcor_heatmap function estimates the rolling window correlation coefficients and their respective p-values among several time series (multi-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, and the outputs are used to produce a heat map. The multivariate case is based on the concept of multiple regression and generalizes the standard coefficient of correlation (the squared multiple correlation coefficient, or more appropriate, the adjusted coefficient of determination, $R^2$). We follow (and extend) the work of Abdi (2007) and Polanco-Martínez (2020) to implement computationally this technique. The rolwinmulcor_heatmap function is highly flexible since this contains several parameters to control the estimation of correlation and features of the plot output. A list of parameters are described in the following lines.

Usage

rolwinmulcor_heatmap(inputdata, varnametsY="", varnametsX="", 
                     typewidthwin="FULL", widthwin_1=7, 
                     widthwin_N=dim(inputdata)[1], Align="center", 
                     pvalcorectmethod="BH", rmltrd=TRUE, Scale=TRUE)

Arguments

inputdata	Matrix of P columns: time, dependent variable ($Y$), and independent variables ($X_1, X_2,..., X_{P-2}$). Please note that time's resolution can be annual, seasonal, monthly, etc, but the format must be in the following form: e.g. for monthly data, year 1 must be repeated 12 times (thus, these times will correspond to 12 rows), year 2 must be also repeated 12 times, and so on. 'Times' must be regular (equally spaced in time and not missing data).
varnametsY	Name of the dependent variable: $Y$. Please note that the name of this variable MUST be defined.
varnametsX	Name of the independent variables: $X_1, X_2,..., X_{p-2}$. Please note that the names of these variables MUST be defined in this way: varnametsX=c("X1", "X2",..., sep=", ").
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.
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 (time-scales) 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, 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).

Details

The rolwinmulcor_heatmap function estimates the rolling window correlation coefficients and their respective p-values between multiple time series (multi-variate case) sampled on identical time points for all the possible window-lengths (time-scales) or for a band of window-lengths. rolwinmulcor_heatmap uses the functions rollapply (package:zoo) that is able to tackle matrices, the native R function p.adjust (package:stats), and some pieces of code and an auxiliary function that we have created specifically for our function rolwinmulcor_heatmap and R RolWinMulCor package.

Value

Outputs:

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

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
BC3 - Basque Centre for Climate Change, Bilbao, SPAIN.
Web1: https://scholar.google.es/citations?user=8djLIhcAAAAJ&hl=en.
Web2: https://www.researchgate.net/profile/Josue-Polanco-Martinez.
Email: [email protected], [email protected].

References

Abdi H. Multiple correlation coefficient, in Encyclopedia of Measurement and Statistics, N. J. Salkind, Ed. Sage, Thousand Oaks, CA, USA, 2007; 648-651.
<URL: https://personal.utdallas.edu/~herve/Abdi-MCC2007-pretty.pdf>.

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: 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: doi: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, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

Examples

# Testing the function rolwinmulcor_heatmap
test_rolwinmulcor_heatmap <- rolwinmulcor_heatmap(YX_ecological_data, 
                               typewidthwin="PARTIAL", widthwin_1=11, widthwin_N=101, 
                               Align="center", pvalcorectmethod="BH")

---

Synthetic data set to test the functions of RolWinMulCor

Description

The data set syntDATA contains three columns, the first one is the time and the next three columns are sinusoidal time series that contains two periodical signals (at 11 and 21, with a phase of zero and amplitude of 1 — please note that these quantities are dimensionless) contaminated by Gaussian noise (with mean of 0 and standard deviation of 0.25) for the intervals 1–100 (signal at 11) and 200–400 (signal at 21) and Gaussian noise (with mean of 0 and standard deviation of 1) otherwise (more information about syntDATA in Polanco-Martínez (2020)).

Usage

data(syntDATA)

Format

One file in ASCII format and columns are separated by spaces.

Source

Author's own production (Josué M. Polanco-Martínez).

References

Polanco-Martínez, J. M. (2020). RolWinMulCor : an R package for estimating rolling window multiple correlation in ecological time series. Ecological Informatics, 60, 101163. <URL: doi:10.1016/j.ecoinf.2020.101163>.

---

Ecological data set to test the functions of RolWinMulCor

Description

The data set YX_ecological_data contains four columns, the first one (“Years”) is the time (years from 1700 to 1936), the second is the first component principal (“PC1”) of the reconstructed Atlantic Bluefin Tuna (BFT) captures (Ganzedo et al., 2016, Polanco-Martínez et al., 2018), the third are reconstructions of sea surface temperature (“SST”) from the Northern Hemisphere (NH) (Mann et al. 2009), and the fourth column contains reconstructions of total solar irradiance (“TSI”) (Lean 2000).

Usage

data(YX_ecological_data)

Format

One file in ASCII format and columns are separated by spaces.

Source

Ganzedo, U., Polanco-Martínez, J. M., Caballero-Alfonso, A. M., Faria, S. H., Li, J., Castro-Hernández, J. J. (2016). Climate effects on historic bluefin tuna captures in the Gibraltar Strait and Western Mediterranean. Journal of Marine Systems, 158, 84-92.
<URL: doi:10.1016/j.jmarsys.2016.02.002>.

Lean, J. (2000). Evolution of the Sun's spectral irradiance since the Maunder Minimum. Geophysical Research Letters, 27(16), 2425-2428. <URL: doi:10.1029/2000GL000043>. Lean Web TSI data set: <URL: https://www.ncdc.noaa.gov/paleo-search/study/5788>.

Mann, M.E., Zhang, Z., Rutherford, S., Bradley, R.S., Hughes, M.K., Shindell, Ammann, G., Faluvegi, G., Ni, F. (2009). Global signatures and dynamical origins of the little ice age and medieval climate anomaly. Science 326, 1256-1260. <URL: doi:10.1126/science.1177303>. Mann et al. Web SST data set: <URL: http://www.meteo.psu.edu/holocene/public_html/supplements/MultiproxySpatial09/results/nhscr>.

Polanco-Martínez, J. M., Caballero-Alfonso, A. M., Ganzedo, U., Castro-Hernández, J. J. (2018). A reconstructed database of historic bluefin tuna captures in the Gibraltar Strait and Western Mediterranean. Data in Brief, 16, 206-210. <URL: doi:10.1016/j.dib.2017.11.028>.

---