ResidCorrMxPlot: ResidCorrMx-Plot: Plot of residual correlation matrix...

In rebeccakuiper/CTmeta: Continuous-time meta-analysis (CTmeta) on standarized lagged effects taking into account the various time-intervals used in the primary studies

ResidCorrMx-Plot: Plot of residual correlation matrix (corresponding to Psi / SigmaVAR)

Description

This function makes a plot of ResidCorrMx(DeltaT), the residual correlation matrix of the discrete-time model, for a range of time intervals based on its underlying drift matrix. There is also an interactive web application on my website to create a Phi-plot: Phi-and-Psi-Plots and Find DeltaT (https://www.uu.nl/staff/RMKuiper/Websites%20%2F%20Shiny%20apps).

Usage

ResidCorrMxPlot(
  DeltaT = 1,
  Phi = NULL,
  SigmaVAR = NULL,
  Drift = NULL,
  Sigma = NULL,
  Gamma = NULL,
  AddGamma = 1,
  Stand = 0,
  Min = 0,
  Max = 10,
  Step = 0.05,
  WhichElements = NULL,
  Labels = NULL,
  Col = NULL,
  Lty = NULL,
  Title = NULL,
  Diag = FALSE
)

Arguments

DeltaT	Optional. The time interval used. By default, DeltaT = 1.
Phi	Matrix of size q times q of (un)standardized lagged effects of the first-order discrete-time vector autoregressive (DT-VAR(1)) model; with q > 1, otherwise (nl if q=1) there is only one correlation which is always 1. It also takes a fitted object from the classes "varest" (from the VAR() function in vars package) and "ctsemFit" (from the ctFit() function in the ctsem package); see example below. From such an object, the (standardized) Phi/Drift and SigmaVAR/Sigma matrices are calculated/extracted.
SigmaVAR	Residual covariance matrix of the first-order discrete-time vector autoregressive (DT-VAR(1)) model.
Drift	Optional (either Phi or Drift). Underling first-order continuous-time lagged effects matrix (i.e., Drift matrix) of the discrete-time lagged effects matrix Phi(DeltaT).
Sigma	Optional (either SigmaVAR, Sigma, or Gamma). Residual covariance matrix of the first-order continuous-time (CT-VAR(1)) model, that is, the diffusion matrix.
Gamma	Optional (either SigmaVAR, Sigma, or Gamma). Stationary covariance matrix, that is, the contemporaneous covariance matrix of the data. Note that if Phi and SigmaVAR (or Drift and Sigma) are known, Gamma can be calculated; hence, only one out of SigmaVAR, Sigma, and Gamma is needed as input.
AddGamma	Optional. Indicator (0/1) for including horizontal lines at the values for Gamma in the plot. By default, AddGamma = 1. Note that SigmaVAR converges to Gamma, so the time-interval dependent curves of SigmaVAR will converge for large time-intervals to the Gamma-lines.
Stand	Optional. Indicator for whether Phi (or Drift) and SigmaVAR (or Sigma) should be standardized (1) or not (0). By default, Stand = 0. Notably, both choices render the same plot, since we inspect correlations here.
Min	Optional. Minimum time interval used in the Phi-plot. By default, Min = 0.
Max	Optional. Maximum time interval used in the Phi-plot. By default, Max = 10.
Step	Optional. The step-size taken in the time intervals. By default, Step = 0.05. Hence, using the defaults, the Phi-plots is based on the values of Phi(DeltaT) for DeltaT = 0, 0.05, 0.10, ..., 10. Note: Especially in case of complex eigenvalues, this step size should be very small (then, the oscillating behavior can be seen best).
WhichElements	Optional. Matrix of same size as Drift denoting which element/line should be plotted (1) or not (0). By default, WhichElements selects the unique off-diagonal elements (since the diagonals are all 1). Note that even though not all lines have to be plotted, the full Phi/Drift and Sigma(VAR)/Gamma matrices are needed to determine the selected lines.
Labels	Optional. Vector with (character) labels of the lines to be plotted. The length of this vector equals the number of 1s in WhichElements (or equals q*(q+1)/2). Note, if AddGamma = 1, then twice this number is needed. By default, Labels = NULL, which renders labels with Greek letter of SigmaVAR (as a function of the time-interval); and, if AddGamma = 1, also for Gamma.
Col	Optional. Vector with color values (integers) of the lines to be plotted. The length of this vector equals the number of 1s in WhichElements (or equals q*(q+1)/2, the unique elements in the symmetric matrix SigmaVAR). By default, Col = NULL, which renders the same color for effects that belong to the same outcome variable (i.e. a row in the SigmaVAR matrix). See https://www.statmethods.net/advgraphs/parameters.html for more information about the values.
Lty	Optional. Vector with line type values (integers) of the lines to be plotted. The length of this vector equals the number of 1s in WhichElements (or equals q*(q+1)/2). By default, Lty = NULL, which renders solid lines for the variances and the same type of dashed line for the covariances. See https://www.statmethods.net/advgraphs/parameters.html for more information about the values.
Title	Optional. A character or a list consisting of maximum 3 character-strings or 'expression' class objects that together represent the title of the Phi-plot. By default, Title = NULL, then the following code will be used for the title: as.list(expression(Sigma[VAR](Delta[t])~plot), "How do the VAR(1) (co)variance parameters vary", "as a function of the time-interval").
Diag	Optional. An indicator (TRUE/FALSE) whether a vertical line for the DeltaT for which the residual correlation matrix is diagonal should be added to the plot (TRUE) or not (FALSE). This value is obtained by the function DiagDeltaT(). By default, Diag = FALSE; hence, by default, no vertical line is added.

Value

This function returns a ResidCorrMx-plot for a range of time intervals.

Examples

# library(CTmeta)

### Make ResidCorrMx-plot ###

## Example 1 ##

# Phi(DeltaT)
DeltaT <- 1
Phi <- myPhi[1:2,1:2]
q <- dim(Phi)[1]
SigmaVAR <- diag(q) # for ease
#
# or
Drift <- myDrift
q <- dim(Drift)[1]
Sigma <- diag(q) # for ease. Note that this is not the CT-equivalent of SigmaVAR.

# Example 1.1: unstandardized Phi&SigmaVAR #
#
# Make plot of SigmaVAR (3 examples):
ResidCorrMxPlot(DeltaT, Phi, SigmaVAR)
ResidCorrMxPlot(DeltaT, Phi, SigmaVAR, Min = 0, Max = 6, Step = 0.01)                # Specifying range x-axis and precision
ResidCorrMxPlot(DeltaT, Drift = Drift, Sigma = Sigma, Min = 0, Max = 6, Step = 0.01) # Using Drift&Sigma instead of Phi&SigmaVAR


# Example 1.2: standardized Phi&SigmaVAR #
ResidCorrMxPlot(DeltaT, Phi, SigmaVAR, Stand = 1)
# Which renders the same as above, since we inspect correlations.


## Example 2: input from fitted object of class "varest" ##

DeltaT <- 1
data <- myData
if (!require("vars")) install.packages("vars")
library(vars)
out_VAR <- VAR(data, p = 1)

# (unstandardized) Phi #
ResidCorrMxPlot(DeltaT, out_VAR)

rebeccakuiper/CTmeta documentation built on Nov. 2, 2024, 4:42 p.m.