popkin (version 1.0.5)

rescalePopkin: 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 phiMin are provided, only phiMin is used. If both subpops and phiMin are omitted, the adjustment is equivalent to phiMin=min(Phi).

Usage

rescalePopkin(Phi, subpops = NULL, phiMin = NA)

Arguments

Phi

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

subpops

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

phiMin

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
Phi <- 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!
Phi2 <- rescalePopkin(Phi, subpops)
## prev is faster but otherwise equivalent to re-estimating Phi from scratch with subpops:
## Phi2 <- popkin(X, subpops) 

## can also manually set the level of relatedness phiMin we want to be zero:
phiMin <- min(Phi) # a naive choice for example
Phi2 <- rescalePopkin(Phi, phiMin=phiMin)

## lastly, omiting both subpops and phiMin sets the minimum value in Phi to zero
Phi3 <- rescalePopkin(Phi2)
## equivalent to both of:
## Phi3 <- popkin(X)
## Phi3 <- rescalePopkin(Phi2, phiMin=min(Phi))

# }