CompleteRmap: Complete a Partially Specified Correlation Matrix by the...

In fungible: Psychometric Functions from the Waller Lab

Complete a Partially Specified Correlation Matrix by the Method of Alternating Projections

Description

This function completes a (possibly) partially specified correlation matrix by a modified alternating projections algorithm.

Usage

CompleteRmap(
  Rna,
  NMatrices = 1,
  RBounds = FALSE,
  LB = -1,
  UB = 1,
  delta = 1e-16,
  MinLambda = 0,
  MaxIter = 1000,
  detSort = FALSE,
  Parallel = FALSE,
  ProgressBar = FALSE,
  PrintLevel = 0,
  Digits = 3,
  Seed = NULL
)

Arguments

Rna	(matrix) An n x n incomplete correlation matrix. Missing entries must be specified by NA values. If all off diagonal values are NA then the function will generate a random correlation matrix.
NMatrices	(integer) CompleteRmap will complete NMatrices correlation matrices.
RBounds	(logical) If RBounds = TRUE then the function will attempt to produce a matrix on the surface of the associated elliptope (i.e., the space of all possible PSD R matrices of a given dimension). When RBounds = FALSE, during each cycle of the alternating projections algorithm all negative eigenvalues of the provisional R matrix are replaced by (sorted) uniform random numbers between the smallest positive eigenvalue and zero (inclusive) of the indefinite matrix. Default RBounds = FALSE.
LB	(numeric) The lower bound for the random number generator when generating initial estimates for the missing elements of a partially specified correlation matrix.
UB	(numeric) The upper bound for the random number generator when generating initial estimates for the missing elements of a partially specified correlation matrix. Start values (for missing correlations) are sampled from a uniform distribution with bounds [LB, UB].
delta	(numeric) A small number that controls the precision of the estimated solution. Default delta = 1E-16.
MinLambda	(numeric) A small value greater than or equal to 0 used to replace negative eigenvalues during the modified alternating projections algorithm.
MaxIter	(integer) The maximum number of cycles of the alternating projections algorithm. Default MaxIter = 1000.
detSort	(logical). If detSort = TRUE then all results will be sorted according to the sizes of the matrix determinants (det(Ri)). Default detSort = FALSE
Parallel	(logical). If Parallel = TRUE parallel processing will be used to generate the completed correlation matrices. Default: Parallel = FALSE.
ProgressBar	(logical). If Parallel = TRUE and ProgressBar = TRUE a progress bar will be printed to screen. Default ProgressBar = FALSE.
PrintLevel	(integer) The PrintLevel argument can take one of three values: 0 No output will be printed. Default (PrintLevel = 0). 1 Print Delta and the minimum eigenvalue of the currently completed correlation matrix. 2 Print convergence history.
Digits	(integer) Controls the number of printed significant digits if PrintLevel = 2.
Seed	(integer) Initial random number seed. If reproducible results are desired then it is necessary to specify ProgressBar = FALSE. Default Seed = NULL.

Value

• CALL The function call.

• NMatrices The number of completed R matrices.

• Rna The input partially specified R matrix.

• Ri A list of the completed R matrices.

• RiEigs A list of eigenvalues for each Ri.

• RiDet A list of the determinants for each Ri.

• converged The convergence status (TRUE/FALSE) for each Ri.

Author(s)

Niels G. Waller

References

Higham, N. J. (2002). Computing the nearest correlation matrix: A problem from finance. IMA Journal of Numerical Analysis, 22(3), 329–343.

Waller, N. G. (2020). Generating correlation matrices with specified eigenvalues using the method of alternating projections. The American Statistician, 74(1), 21-28.

Examples

## Not run: 
Rna4 <- matrix(c( 1,  NA,  .29, .18,
                  NA, 1,   .11, .24,
                 .29, .11, 1,   .06,
                 .18, .24, .06, 1), 4, 4)

Out4  <- CompleteRmap(Rna = Rna4,
                      NMatrices = 5,
                      RBounds = FALSE,
                      LB = -1,
                      UB = 1,
                      delta = 1e-16,
                      MinLambda = 0,
                      MaxIter = 5000,
                      detSort = FALSE,
                      ProgressBar = TRUE,
                      Parallel = TRUE,
                      PrintLevel = 1,
                      Digits = 3,
                      Seed = 1)

summary(Out4,
        PrintLevel = 2,
        Digits = 5)

## End(Not run)

fungible documentation built on May 29, 2024, 8:28 a.m.