popkin_af: Estimate coancestry from an allele frequency matrix and...

In StoreyLab/popkin: Estimate Kinship and FST under Arbitrary Population Structure

Estimate coancestry from an allele frequency matrix and subpopulation assignments

Description

Given the individual-specific allele frequencies of n individuals, this function returns the n-by-n coancestry matrix. This function is the analog of popkin() for allele frequencies rather than genotypes, and as a consequence estimates coancestry instead of kinship. These coancestry estimates are unbiased if the true allele frequencies are provided, but may be less accurate when the allele frequencies themselves are estimated. This function is intended for cases where allele frequencies, but not individual genotypes, are available; otherwise it is best to use the individual genotypes and popkin(). An application of interest is the allele frequency matrices from admixture models, in which case the columns correspond to subpopulations rather than individuals, and subpops = NULL is an acceptable choice.

Usage

popkin_af(
  P,
  subpops = NULL,
  loci_on_cols = FALSE,
  mem_factor = 0.7,
  mem_lim = NA,
  want_M = FALSE,
  m_chunk_max = 1000
)

Arguments

P	m-by-n matrix of individual-specific allele frequencies, which should have values between [0, 1] (range is not strictly required) or NA for missing data.
subpops	The length-n vector of subpopulation assignments for each individual. If NULL, every individual is effectively treated as a different population.
loci_on_cols	If TRUE, P has loci on columns and individuals on rows; if FALSE (default), loci are on rows and individuals on columns.
mem_factor	Proportion of available memory to use loading and processing data. Ignored if mem_lim is not NA.
mem_lim	Memory limit in GB, used to break up data into chunks for very large datasets. Note memory usage is somewhat underestimated and is not controlled strictly. Default in Linux is mem_factor times the free system memory, otherwise it is 1GB (Windows, OSX and other systems).
want_M	If TRUE, includes the matrix M of non-missing pair counts in the return value, which are sample sizes that can be useful in modeling the variance of estimates. Default FALSE is to return the relatedness matrix only.
m_chunk_max	Sets the maximum number of loci to process at the time. Actual number of loci loaded may be lower if memory is limiting.

Value

If want_M = FALSE, returns the estimated n-by-n coancestry matrix only. If P has names for the individuals, they will be copied to the rows and columns of this coancestry matrix. If want_M = TRUE, a named list is returned, containing:

• coancestry: the estimated n-by-n coancestry matrix

• M: the n-by-n matrix of non-missing pair counts (see want_M option).

See Also

popkin() for kinship estimation from genotype matrices.

Examples

# a matrix of random uniform allele frequencies
# (unstructured, unlike real data)
P <- matrix( runif( 9 ), nrow = 3 )

coancestry <- popkin_af( P )

StoreyLab/popkin documentation built on Jan. 10, 2023, 1:39 p.m.