fungible (version 2.2.2)

CompleteRmap: 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
)

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.

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.

Author

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

if (FALSE) {
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)
}