Help for package VisualDom

Type:

Package

Title:

Visualize Dominant Variables in Wavelet Multiple Correlation

Version:

0.8.0

Maintainer:

Josué M. Polanco-Martínez <josue.m.polanco@gmail.com>

Depends:

R (≥ 3.6.0), waveslim, wavemulcor, plot3D

Description:

Estimates and plots as a heat map the correlation coefficients obtained via the wavelet local multiple correlation 'WLMC' (Fernández-Macho 2018) and the 'dominant' variable/s, i.e., the variable/s that maximizes the multiple correlation through time and scale (Polanco-Martínez et al. 2020, Polanco-Martínez 2022). We improve the graphical outputs of WLMC proposing a didactic and useful way to visualize the 'dominant' variable(s) for a set of time series. The WLMC was designed for financial time series, but other kinds of data (e.g., climatic, ecological, etc.) can be used. The functions contained in 'VisualDom' are highly flexible since these contains several parameters to personalize the time series under analysis and the heat maps. In addition, we have also included two data sets (named 'rdata_climate' and 'rdata_Lorenz') to exemplify the use of the functions contained in 'VisualDom'. Methods derived from Fernández-Macho (2018) <doi:10.1016/j.physa.2017.11.050>, Polanco-Martínez et al. (2020) <doi:10.1038/s41598-020-77767-8> and Polanco-Martínez (2023, in press).

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Repository:

CRAN

Encoding:

UTF-8

LazyData:

true

Date/Publication:

2023-01-06 11:30:05 UTC

NeedsCompilation:

Packaged:

2022-12-23 23:05:39 UTC; jomopo

Author:

Josué M. Polanco-Martínez

[aut, cph, cre]

Visualize Dominant Variables in Wavelet Multiple Correlation

Description

'VisualDom' estimates and plots as a heat map the correlation coefficients obtained via the wavelet local multiple correlation 'WLMC' (Fernández-Macho 2018). We improve the graphical outputs of WLMC proposing a didactic and useful way to visualize the 'dominant' variable(s) that the maximizes the multiple correlation through time for a set of time series (Polanco-Martínez et al. 2020; Polanco-Martínez 2023). The WLMC was designed for financial time series, but other kinds of data (e.g., climatic, ecological, etc.) can be used. 'VisualDom' contains three functions: (1) 'estim_WLMC': estimates the wavelet local multiple correlation; (2) 'plot_estim_WLMC': plots the time series under analysis and a heat map the correlation coefficients obtained via 'estim_WLMC'; (3) 'plot_dominant_WLMC': this function also plot the time series under study and a heat maps of the dominant variable/s using the outputs of 'estim_WLMC'. The functions contained in 'VisualDom' are highly flexible since these contains several parameters to personalize the time series under analysis and the heat maps. In addition, we have also included two data sets (named 'rdata_climate' and 'rdata_Lorenz') to exemplify the use of the functions contained in 'VisualDom'.

Details

Package:	VisualDom
Type:	Package
Version:	0.8
Date:	2022-12-21
License:	GPL (>= 2)
LazyLoad:	yes

VisualDom package contains three functions: (1) estim_WLMC that estimates the wavelet local multiple correlation (WLMC); (2) plot_estim_WLMC that plots the time series under analysis and the correlation coefficients as a heat map obtained via estim_WLMC; and (3) plot_dominant_WLMC that plots the time series under study and the dominant variable/s as a heat maps, this function also use the output of estim_WLMC.

Note

Dependencies: wavemulcor, waveslim, plot3D.

Author(s)

Josué M. Polanco-Martínez (a.k.a. jomopo).
Excellence Unit GECOS, IME, Universidad de Salamanca, Salamanca, SPAIN.
BC3 - Basque Centre for Climate Change, Leioa, 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
Acknowledgement:
We acknowledge to the Excellence Unit GECOS (reference number CLU-2019-03), Universidad de Salamanca for its funding support.

References

Fernández-Macho, J. (2018). Time-localized wavelet multiple regression and correlation. Physica A: Statistical Mechanics and its Applications, 492, 1226-1238. <URL: doi: 10.1016/j.physa.2017.11.050>.

Polanco-Martínez, J. M., Fernández-Macho, J., & Medina-Elizalde, M. (2020). Dynamic wavelet correlation analysis for multivariate climate time series. Scientific Reports, 10(1), 1-11. <URL: doi: 10.1038/s41598-020-77767-8>.

Polanco-Martínez, J.M. (2023, in press). A computational and gaphical approach to analyze the dynamic wavelet correlation among components of a nonlinear dynamical system. Journal of Applied Nonlinear Dynamics, 1-13.

Whitcher, B., Guttorp, P., & Percival, D. B. (2000). Wavelet analysis of covariance with application to atmospheric time series. Journal of Geophysical Research: Atmospheres, 105(D11), 14941-14962. <URL: doi: 10.1029/2000JD900110>.

Estimates the wavelet local multiple correlation

Description

The estim_WLMC function estimates the wavelet local multiple correlation (WLMC) for a set of multivariate time series. The function is based mainly on the work of Fernández-Macho (2018) and to lesser extent in the work of Polanco-Martínez et al. (2020).

Usage

estim_WLMC(inputdata, wf="la8", J, window, M, Ymaxr=NULL)

Arguments

inputdata

A matrix of N columns by P rows: the first column is time (regular/evenly spaced) and the other columns are the variables under study.

wf

Name of the wavelet filter used in the wavelet transform (MODWT) decomposition. There are several wavelet filters to be used, but we use by default the Daubechies orthonormal compactly supported wavelet of length L=8, that is, “la8”.

J

The maximum level of the MODWT decomposition. It is recommended to use log2(N) - 3, where N is the number of rows or elements of inputdata (Fernández-Macho 2018, Polanco-Martínez et al. 2020).

window

Weight or window function, by the default is the Gaussian window (gaussian) but other five window functions can be used, e.g., uniform, Bartlett's triangular, Cleveland's tricube, Wendland's truncated power or Epanechnikov's parabolic. Please look at the function wave.local.multiple.correlation from the R package wavemulcor (Fernandez-Macho 2018).

M

The length of the weight/window function, it is recommended to use N/8, where N is the number of rows or columns (Fernández-Macho 2018, Polanco-Martínez et al. 2020).

Ymaxr

This parameter is used to indicate which variable will be used to maximize the multiple correlation for each wavelet scale, by default is 'NULL', that is, we do not define a priori an specific variable but instead let the WLMC select one (Fernández-Macho 2018, Polanco-Martínez et al. 2020).

Details

The estim_WLMC function estimates the WLMC for multivariate time series including the correlation coefficients and their statistical significance. The estim_WLMC function uses the function wave.local.multiple.correlation (package:wavemulcor) to estimate the wavelet local multiple correlation, and the functions modwt and brick.wall (package:waveslim) to carry out the wavelet decomposition of the time series under study.

Value

Outputs: A list named LISTvals that contains four elements: CORCOEF that contains the correlation coefficients, CIlo and CIup are the lower and upper confidence intervals (CI), and YmaxR contains the indices (numbers from 1 to the number of columns or variables) of the corresponding variables whose correlation is calculated against a linear combination of the rest.

Author(s)

References

Examples


# We reproduce Figure 3 left presented in Polanco-Martínez et al. (2020). 
inputdata  <- rdata_climate
N          <- nrow(inputdata)
wf         <- "la8"               
window     <- "gaussian"          
J          <- 7 
M          <- 168 

output_WLMC <- estim_WLMC(inputdata, wf=wf, J=J, window=window, M=M, Ymaxr=NULL)

Plot as a heat map the 'dominant' variable/s contained in the output of the function 'estim_WLMC'

Description

The plot_dominant_WLMC function plots as a heat map the 'dominant' (that is, the variable/s that maximizes the multiple correlation through time and scale) variable/s of the time series analysed. This function also plots the time series under analysis and discern the correlation coefficients that are not statistically significant, which are plotted as blanks.

Usage

plot_dominant_WLMC(inputdata, LISTvals, J, fac=1, FLAG=TRUE, FLAGNA=1, 
                   COLS=c(1:5), LTY=c(rep(1,5)), LWD=c(rep(1.2,5)), 
                   DIST=c(seq(0,10,2)))

Arguments

inputdata

A matrix of N columns by P rows: the first column is time (regular/evenly spaced) and the other columns are the variables under study.

LISTvals

Output of the function estim_WLMC. This is a list that contains: (1) CORCOEF (correlation coefficients), (2) CIlo (CI lower bounds), (3) CIup (CI upper bounds), and (4) YmaxR (the index numbers, from 1 to number of variables, of the variable whose correlation is calculated against a linear combination of the rest).

J

The maximum level of the MODWT decomposition. It is recommended to use log2(N) - 3, where N is the number of rows or elements of inputdata (Fernández-Macho 2018, Polanco-Martínez et al. 2020).

fac

This factor is used to scale the wavelet time-scales or 'periods' when the time scale is not the unit, by the default is 1.

FLAG

This 'flag' is used to plot the Y axis of the multivariate time series if the number of these series is less than four, by default is TRUE.

FLAGNA

This is used to plot (by the default is 1) or not (please us 0) the correlation coefficients that are/not statistically significant.

COLS

The colors used to plot the multivariate time series.

LTY

The type of lines used to plot the multivariate time series.

LWD

The tick sizes used to plot the multivariate time series.

DIST

This parameter is used to define the distances between the Y axis when the multivariate time series are plotted.

Details

The plot_dominant_WLMC function plots as a heat map the 'dominant' variable/s, that is, the variable/s that maximizes the multiple correlation through time and scale of the variables (time series) analysed. This function also plot the time series under analysis and discern the correlation coefficients that are not statistically significant, we use blanks to plot these coefficients.

Value

A plot of the time series under analysis and a heat map (a multi-plot via screen) of the dominant variable/s whose correlation coefficients are statistically significant. This multi-plot can be saved in your preferred format.

Author(s)

References

Polanco-Martínez, J.M. (2023, in press), A computational and graphical approach to analyze the dynamic wavelet correlation among components of a nonlinear dynamical system, Journal of Applied Nonlinear Dynamics, 1-13.

Examples

# We reproduce Figure 3 below presented in Polanco-Martínez (2023). 
#\donttest{
inputdata  <- rdata_Lorenz 
N          <- nrow(inputdata)
wf         <- "la8"               
window     <- "gaussian"          
J          <- 6 
M          <- 20 

LISTvals <- estim_WLMC(inputdata, wf=wf, J=J, window=window, M=M, Ymaxr=NULL) 

plot_dominant_WLMC(inputdata, LISTvals=LISTvals, J=J, fac=0.05, 
  FLAG=TRUE, FLAGNA=1, COLS=c("blue", "green", "red"), 
  LTY=c(rep(1,5)), LWD=c(rep(1.2,5)), DIST=c(seq(0, 10, 2.75)))
#}

Plot as a heat map the correlation coefficients contained in the output of the function 'estim_WLMC'

Description

The plot_estim_WLMC function plots as a heat map the output of the estim_WLMC function. One of the features of plot_estim_WLMC is that this function discern the correlation coefficients that are not statistically significant, which use blanks to plot these coefficients.

Usage

plot_estim_WLMC(inputdata, LISTvals, J, fac=1, FLAG=TRUE, FLAGNA=1, 
                COLS=c(1:5), LTY=c(rep(1,5)), LWD=c(rep(1.2,5)), 
                DIST=c(seq(0,10,2)))

Arguments

inputdata

A matrix of N columns by P rows: the first column is time (regular/evenly spaced) and the other columns are the variables under study.

LISTvals

Output of the function estim_WLMC. This is a list that contains: (1) CORCOEF (correlation coefficients), (2) CIlo (CI lower bounds ), (3) CIup (CI upper bounds), and (4) YmaxR (the index numbers, from 1 to number of variables, of the variable whose correlation is calculated against a linear combination of the rest).

J

The maximum level of the MODWT decomposition. It is recommended to use log2(N) - 3, where N is the number of rows or elements of inputdata (Fernández-Macho 2018, Polanco-Martínez et al. 2020).

fac

This factor is used to scale the wavelet time-scales or 'periods' when the time scale is not the unit, by the default is 1.

FLAG

This 'flag' is used to plot the Y axis of the multivariate time series if the number of these series is less than four, by default is TRUE.

FLAGNA

This is used to plot (by the default is 1) or not (please us 0) the correlation coefficients that are/not statistically significant.

COLS

The colors used to plot the multivariate time series.

LTY

The type of lines used to plot the multivariate time series.

LWD

The tick sizes used to plot the multivariate time series.

DIST

This parameter is used to define the distances between the Y axis when the multivariate time series are plotted.

Details

The plot_estim_WLMC function plots as a heat map the output of the estim_WLMC function. This function plot the multivariate time series under analysis and the aforementioned heat map. Another feature of plot_estim_WLMC is that this function plot the correlation coefficients that are/not statistically significant, which use blanks to plot the coefficients that are not significant.

Value

Outputs: A plot of the time series under analysis and a heat map (a multi-plot via screen) of the wavelet correlation coefficients statistically significant. This multi-plot can be saved in your preferred format.

Author(s)

References

Examples


# We reproduce Figure 3 left presented in Polanco-Martínez et al. (2020). 
inputdata  <- rdata_climate
N          <- nrow(inputdata)
wf         <- "la8"               
window     <- "gaussian"          
J          <- 7 
M          <- 168 

LISTvals <- estim_WLMC(inputdata, wf=wf, J=J, window=window, M=M, Ymaxr=NULL) 

plot_estim_WLMC(inputdata, LISTvals=LISTvals, J=J, fac=1, FLAG=TRUE, 
  FLAGNA=1, COLS=c("blue", "green", "red"), LTY=c(rep(1,5)), 
  LWD=c(rep(1.2,5)), DIST=c(seq(0, 10, 2.75)))

Data set generated via the Lorenz system and used to exemplify the functions contained in VisualDom

Description

The data set rdata_Lorenz contains four columns: the first column is time (unitless) and the following three columns are the X, Y, Z components of the Lorenz system. The Lorenz system consists of three coupled first-order ordinary differential equations and is without a doubt one of the most famous nonlinear dynamical mathematical models, and represents a paradigmatic example for both theoretical and numerical investigations in checking some results in chaos theory (Polanco-Martínez 2022). For more details on how the rdata_Lorenz was created see Polanco-Martínez (2023).

Usage

data(rdata_Lorenz)

Format

One file in ASCII format containing 4 columns and 500 rows, columns are separated by spaces.

Source

Climate data set to exemplify the use of the functions contained in VisualDom

Description

The data set rdata_climate contains four columns: the first one (named 'Time') are years from 500 to 1850, the following three columns are the MDRSST (Sea Surface Temperatures anomalies from the Main Developed Region for tropical cyclones) (Mann et al. 2009a), the ENSO (El Niño-Southern Oscillation SST anomalies, el Niño 3 region) (Mann et al. 2009b) and the AMO (The North Atlantic Multidecadal Oscillation SST anomalies) (Mann et al. 2009b).

Usage

data(rdata_climate)

Format

One file in ASCII format containing 4 columns and 1350 rows, columns are separated by spaces.

Source

Mann, M.E., Woodruff, J.D., Donnelly, J.P. and Zhang, Z. (2009a). Atlantic hurricanes and climate over the past 1,500 years. Nature 460, 880-883. <URL: doi: 10.1038/nature08219>.

Mann, M.E. Ghang, Z., Rutherford, S., Bradley, R.S., Hughes, M.K., Shindel, Ammann, C., Faluvegi, G. and Ni, F. (2009b). 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, M.E. (2022), Supplemental Information for Mann et al (2009) Nature Article, <URL: http://www.meteo.psu.edu/holocene/public_html/Nature09/index.htm>, accessed: 2022-09-20.