Validate correlation matrix

Source: R/validate_inputs.R

Validates that a matrix can serve as a correlation matrix for variant-set tests. Correlation matrices are used to account for linkage disequilibrium among genetic variants.

validate_correlation_matrix(M, n_variants = NULL, tol = 1e-08)

Arguments

M

Matrix to validate as correlation matrix

n_variants

Expected dimension (optional). If provided, checks that nrow(M) == ncol(M) == n_variants

tol

Numerical tolerance for symmetry and positive definiteness checks. Default: 1e-8

Value

A list with elements:

valid

Logical; TRUE if all checks pass

message

Character string with validation result or error message

dimension

Dimension of the matrix

is_symmetric

Logical; TRUE if symmetric within tolerance

min_eigenvalue

Smallest eigenvalue (for PSD check)

warnings

Character vector of non-fatal warnings

Details

Checks that a matrix is a valid correlation matrix suitable for use in GLOW tests. This includes checking symmetry, diagonal values, positive semi-definiteness, and appropriate dimensions.

Validation checks performed:

  1. Basic structure:

    • Must be a square matrix

    • Must be numeric

  2. Correlation properties:

    • Must be symmetric (M = t(M) within tolerance)

    • Diagonal must be all 1s (within tolerance)

    • Off-diagonal values must be in \([-1, 1]\)

  3. Positive semi-definiteness:

    • All eigenvalues must be >= -tol

    • Required for valid correlation matrices

    • Small negative eigenvalues (< tol) are acceptable due to numerical error

  4. Dimension matching (if n_variants provided):

    • Matrix dimension must match expected number of variants

Computational Complexity: O(n^3) for eigenvalue check where n=dim(M)

Returns: List with validation status and diagnostic information

Examples

# Valid correlation matrix
M <- diag(10)
result <- validate_correlation_matrix(M)
result$valid  # TRUE
#> [1] TRUE

# Valid with correlation structure
M_cor <- matrix(0.3, 5, 5) + diag(0.7, 5)
result_cor <- validate_correlation_matrix(M_cor)

# Invalid: not symmetric
M_bad <- matrix(runif(25), 5, 5)
result_bad <- validate_correlation_matrix(M_bad)
result_bad$valid  # FALSE
#> [1] FALSE

# Check dimension matching
result_dim <- validate_correlation_matrix(M_cor, n_variants=5)
result_dim$valid  # TRUE
#> [1] TRUE