Validate genotype matrix for GLOW tests

Source: R/validate_inputs.R

This function performs comprehensive validation of genotype data to ensure it meets the requirements for GLOW variant-set tests. It checks:

  • Matrix structure (non-empty, numeric)

  • Missing values (optionally allowed or disallowed)

  • Genotype encoding (0/1/2 for additive, or continuous dosages)

  • Variant variation (at least some variants must be polymorphic)

validate_genotype_matrix(G, allow_na = FALSE, discrete = TRUE, min_sd = 1e-06)

Arguments

G

Genotype matrix (samples x variants). Rows are individuals, columns are genetic variants. Expected encoding: 0/1/2 for discrete genotypes, or \([0,2]\) for dosages.

allow_na

Logical; if TRUE, allow missing values (NA). Default: FALSE

discrete

Logical; if TRUE, require discrete 0/1/2 encoding. If FALSE, allow continuous dosages in \([0,2]\). Default: TRUE

min_sd

Minimum standard deviation required for at least one variant. Ensures sufficient genetic variation. Default: 1e-6

Value

A list with elements:

valid

Logical; TRUE if all checks pass

message

Character string with validation result or error message

n_samples

Number of samples (rows)

n_variants

Number of variants (columns)

n_missing

Number of missing values (if allow_na=TRUE)

n_monomorphic

Number of monomorphic variants (SD < min_sd)

warnings

Character vector of non-fatal warnings

Details

Checks that a genotype matrix meets basic requirements for variant-set association testing. This includes checking dimensions, missing values, valid genotype encoding, and sufficient variation.

Validation checks performed:

  1. Matrix structure:

    • Must be a matrix or coercible to matrix

    • Must have at least 1 sample and 1 variant

    • Must contain numeric values

  2. Missing values:

    • If allow_na=FALSE: No missing values allowed

    • If allow_na=TRUE: Missing values are permitted but counted

  3. Genotype encoding:

    • If discrete=TRUE: All non-NA values must be in 0, 1, 2

    • If discrete=FALSE: Any numeric values in \([0, 2]\) are allowed (dosages)

  4. Variation check:

    • At least one variant must have standard deviation > min_sd

    • This ensures at least some genetic variation exists

    • Monomorphic variants (all 0s or all same value) are flagged

Computational Complexity: O(n * p) where n=samples, p=variants

Returns: List with validation status and diagnostic information

Examples

# Valid genotype matrix (discrete, no missing)
G <- matrix(sample(0:2, 100, replace=TRUE), nrow=10, ncol=10)
result <- validate_genotype_matrix(G)
result$valid  # TRUE
#> [1] TRUE

# Genotype matrix with missing values
G_na <- G
G_na[1:3, 1] <- NA
result_na <- validate_genotype_matrix(G_na, allow_na=TRUE)
result_na$n_missing  # 3
#> [1] 3

# Continuous dosages
G_dosage <- matrix(runif(100, 0, 2), nrow=10, ncol=10)
result_dosage <- validate_genotype_matrix(G_dosage, discrete=FALSE)

# Invalid: all monomorphic
G_mono <- matrix(0, nrow=10, ncol=10)
result_mono <- validate_genotype_matrix(G_mono)
result_mono$valid  # FALSE
#> [1] FALSE