popkin (version 1.3.13)

popkin_A_min_subpops: Estimate the minimum expected value of a matrix A using subpopulations

Description

This function averages the values of a square matrix A between every subpopulation pair and returns the minimum of these averages. The return value can be used to adjust an A matrix to yield the kinship matrix.

Usage

popkin_A_min_subpops(A, subpops = NULL)

Arguments

A

A symmetric n-by-n matrix with values between every individual pair, including self comparisons.

subpops

A length-n vector of subpopulation assignments for each individual. If missing, every individual is effectively treated as a different population.

Value

The minimum of the average between-subpopulation A values, which estimates the minimum expected value of A

Details

If no subpopulation partition is provided, the function returns the minimum value of A. This default choice may be appropriate in some settings, but is susceptible to bias when there are few loci and many pairs of individuals with zero kinship (taking the most extreme estimate is clearly worse than averaging these values). This default is provided for convenience, to explore the data when a correct choice of subpopulations is not clear, but is not recommended as a final approach.

See Also

popkin_A() to generate the A matrix usually inputted into this function (popkin_A_min_subpops). popkin() is the wrapper function around both of these.

Examples

# NOT RUN {
# Construct toy data
X <- matrix(c(0,1,2,1,0,1,1,0,2), nrow=3, byrow=TRUE) # genotype matrix
subpops <- c(1,1,2) # subpopulation assignments for individuals

# NOTE: for BED-formatted input, use BEDMatrix!
# "file" is path to BED file (excluding .bed extension)
## library(BEDMatrix)
## X <- BEDMatrix(file) # load genotype matrix object

# calculate A from genotypes
A <- popkin_A(X)$A

# the recommended form using appropriate subpopulation labels
A_min_est <- popkin_A_min_subpops( A, subpops )

# this recovers the popkin estimate
kinship <- 1 - A / A_min_est
stopifnot( kinship == popkin( X, subpops ) )

# a simple default for exploratory analysis, equals min( A )
A_min_est <- popkin_A_min_subpops( A )
stopifnot( A_min_est == min( A ) )

# }