popkin (version 1.2.2)

rescale_popkin: Rescale kinship matrix to set a given kinship value to zero.

Description

Rescales the input kinship matrix \(\Phi^T\) so that the value \(\phi_{\mbox{min}}^T\) in the original kinship matrix becomes zero, using the formula $$\Phi^{T'} = \frac{\Phi^T - \phi_{\mbox{min}}^T}{1 - \phi_{\mbox{min}}^T}.$$ This is equivalent to changing the ancestral population \(T\) into \(T'\) such that \(\phi_{\mbox{min}}^{T'} = 0\). If subpopulation labels subpops are provided, they are used to estimate \(\phi_{\mbox{min}}^T\). If both subpops and min_kinship are provided, only min_kinship is used. If both subpops and min_kinship are omitted, the adjustment is equivalent to min_kinship=min(kinship).

Usage

rescale_popkin(kinship, subpops = NULL, min_kinship = NA)

Arguments

kinship

An \(n \times n\) kinship matrix.

subpops

The length-\(n\) vector of subpopulation assignments for each individual.

min_kinship

A scalar kinship value to define the new zero kinship.

Value

The rescaled \(n \times n\) kinship matrix, with the desired level of relatedness set to zero.

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
subpops2 <- 1:3 # alternate labels treat every individual as a different subpop

# 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

# suppose we first estimate kinship without subpopulations, which will be more biased
kinship <- popkin(X) # calculate kinship from genotypes, WITHOUT subpops
# then we visualize this matrix, figure out a reasonable subpopulation partition

# now we can adjust the kinship matrix!
kinship2 <- rescale_popkin(kinship, subpops)
# prev is faster but otherwise equivalent to re-estimating kinship from scratch with subpops:
# kinship2 <- popkin(X, subpops) 

# can also manually set the level of relatedness min_kinship we want to be zero:
min_kinship <- min(kinship) # a naive choice for example
kinship2 <- rescale_popkin(kinship, min_kinship = min_kinship)

# lastly, omiting both subpops and min_kinship sets the minimum value in kinship to zero
kinship3 <- rescale_popkin(kinship2)
# equivalent to both of:
# kinship3 <- popkin(X)
# kinship3 <- rescale_popkin(kinship2, min_kinship = min(kinship))

# }