Ravgr {fungible}

Generate a random R matrix with an average rij

Description

Ravgr(Rseed, NVar = NULL, u = NULL, rdist = "U", alpha = 4, beta = 2, SEED = NULL)

Usage

Ravgr(
  Rseed,
  NVar = NULL,
  u = NULL,
  rdist = "U",
  alpha = 4,
  beta = 2,
  SEED = NULL
)

Arguments

Rseed

(matrix or scalar) This argument can take one of two alternative inputs. The first input is an n \times n R matrix with a known, average rij. The second type of input is a scalar \bar{r}_{ij}.

NVar

(integer) If Rseed is a scalar then the user must specify NVar, the number of variables in the desired R matrix. Default(NVar = NULL).

u

(scalar). A scalar \in [0,1]. Higher values of u will produce R matrices with more variable off-diagonal elements.

rdist

(character). A character that controls the variance of the off diagonal elements of the generated R. If u = NULL and rdist="U" then the R matrices are uniformly sampled from the space of all n\times n R matrices with a fixed average rij. If u = NULL and rdist = "B" then the R matrices are selected as a function of the alpha and beta arguments of a Beta distribution. Default rdist= "U". See Waller (2024) for details.

alpha

(numeric) The shape1 parameter of a beta distribution.

beta

(numeric) The shape2 parameter of a beta distribution.

SEED

(numeric) The initial seed for the random number generator. If SEED is not supplied then the program will generate (and return) a randomly generated seed.

Value

• R A random R matrix with a known, average off-diagonal element rij.

• Rseed The input R matrix or scalar with the desired average rij.

• u A random number \in [0,1].

• s Scaling factor for hollow matrix H.

• H A hollow matrix used to create a fungible R matrix.

• alpha First argument of the beta distribution. If rdist= "U" then alpha = NULL.

• beta Second argument of the beta distribution. If rdist= "U" then beta = NULL.

• SEED The initial value for the random number generator.

Author(s)

Niels G. Waller

References

Waller, N. G. (2024). Generating correlation matrices with a user-defined average correlation. Manuscript under review.

Examples

 # Example 1
  R <- matrix(.35, 6, 6)
  diag(R) <- 1
  
  Rout <- Ravgr(Rseed = R, 
               rdist = "U", SEED = 123)$R
               
  Rout |> round(3)            
  mean( Rout[upper.tri(Rout, diag = FALSE)] )
  
  # Example 2 
  Rout <- Ravgr(Rseed = .35, NVar = 6, 
               rdist = "U", SEED = 123)$R
               
  Rout |> round(3)            
  mean( Rout[upper.tri(Rout, diag = FALSE)] )   
  
  # Example 3
  # Generate an R matrix with a larger var(rij)
  Rout <- Ravgr(Rseed = .35,
               NVar = 6, 
               rdist = "B",
               alpha = 7,
               beta = 2)$R
               
  Rout |> round(3)            
  mean( Rout[upper.tri(Rout, diag = FALSE)] )
  
  # Example 4: Demonstrate the function of u
  sdR <- function(R){
    sd(R[lower.tri(R, diag = FALSE)])
  }
  
  Rout <- Ravgr(Rseed = .35,
               NVar = 6, 
               u = 0,
               SEED = 123)
  sdR(Rout$R)  
  
  Rout <- Ravgr(Rseed = .35,
               NVar = 6, 
               u = .5,
               SEED = 123)
  sdR(Rout$R)   
  
  Rout <- Ravgr(Rseed = .35,
               NVar = 6, 
               u = 1,
               SEED = 123)
  sdR(Rout$R)