cov_from_biallelic: Genetic covariance from biallelic allele counts

In landgraph: Graphs and Covariance for Landscape Genetics

Genetic covariance from biallelic allele counts

Description

Computes a sample covariance matrix from counts of the derived allele across biallelic (SNP) markers. Rows may be individuals, populations, or any other sampled genetic unit. The result is directly suitable as the response S in wishart_covariance.

Usage

cov_from_biallelic(
  Y,
  N = NULL,
  ploidy = 2,
  monomorphic = c("drop", "error"),
  tol = sqrt(.Machine$double.eps)
)

Arguments

Y	Numeric matrix of derived-allele counts with sampled units in rows and loci in columns. For diploid individuals genotyped as 0/1/2, this is the standard dosage matrix.
N	Optional haploid sample-size specification. Controls how many chromosomes were sampled at each locus for each unit: NULL: use ploidy for all cells. A scalar: recycled to all cells. A vector of length nrow(Y): row-specific sample sizes (same at every locus for that row). A vector of length ncol(Y): locus-specific sample sizes (same across all rows). A matrix matching dim(Y): fully general cell-level sizes.
ploidy	Haploid chromosome count per unit, used when N = NULL. The default 2 corresponds to diploid individuals with dosage coding 0/1/2 (so each individual contributes two chromosomes at each locus).
monomorphic	How to handle loci with pooled allele frequency 0 or 1 (fixed across all rows). "drop" (default) removes them and emits a warning; "error" stops with an error to preserve historical strict behavior.
tol	Tolerance for identifying monomorphic loci. A locus is treated as monomorphic when its pooled frequency is within tol of 0 or 1.

Details

Let p_\ell = \sum_i Y_{i\ell} / \sum_i N_{i\ell} be the pooled derived-allele frequency at locus \ell. The normalized allele dosage is:

Z_{i\ell} = \frac{Y_{i\ell} - N_{i\ell} p_\ell} {\sqrt{N_{i\ell} p_\ell (1 - p_\ell)}}

The function returns Z Z^\top / L, where L is the number of retained (polymorphic) loci. The resulting matrix is the sample covariance in normalized allele-frequency space, analogous to the genomic relationship matrix of Yang et al. (2010).

Per-locus standardization gives greater weight to rare variants, including their contribution to the diagonal. Filter loci by minor allele frequency before constructing the covariance and report the filtering rule. Unequal chromosome counts also imply unequal sampling variance. With unequal counts across rows, pooled-frequency centering does not generally produce zero row sums in the covariance.

To convert the covariance to a pairwise distance matrix, use dist_from_cov. For non-biallelic or multiallelic data, use cov_from_genetic_data.

Value

A symmetric positive-semidefinite numeric matrix of pairwise genetic covariances. Row and column names match those of Y when present. The diagonal attribute is "normalized_dosage". The centered attribute is "sites" when chromosome counts are equal across rows at every retained locus; otherwise it is "pooled_allele_frequency". These labels describe the construction without changing the returned numerical values.

References

Yang J, Benyamin B, McEvoy BP, Gordon S, Henders AK, Nyholt DR, Madden PA, Heath AC, Martin NG, Montgomery GW, Goddard ME, Visscher PM. 2010. Common SNPs explain a large proportion of the heritability for human height. Nature Genetics 42(7):565-569. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1038/ng.608")}

See Also

cov_from_genetic_data, fst_from_biallelic, dist_from_biallelic, dist_from_cov, wishart_covariance

Examples

# Individual diploid dosage matrix: 3 individuals, 3 SNPs
Y <- matrix(c(2, 1, 0,
              1, 1, 1,
              0, 1, 2), nrow = 3, byrow = TRUE)
cov_from_biallelic(Y)          # ploidy = 2 by default

# Population-level counts with unequal sampling
Y2 <- matrix(c(10, 4, 1,
               5,  5, 3), nrow = 2, byrow = TRUE)
N2 <- matrix(c(20, 20, 10,
               10, 10, 6), nrow = 2, byrow = TRUE)
cov_from_biallelic(Y2, N = N2)

landgraph documentation built on Sept. 26, 2026, 1:08 a.m.