kingToMatrix {GENESIS} | R Documentation

## Convert KING text output to an R Matrix

### Description

`kingToMatrix` is used to extract the pairwise kinship coefficient estimates from the output text files of KING –ibdseg, KING –kinship, or KING –related and put them into an R object of class `Matrix`. One use of this matrix is that it can be read by the functions `pcair` and `pcairPartition`.

### Usage

    ## S4 method for signature 'character'
    kingToMatrix(king, estimator = c("PropIBD", "Kinship"), sample.include = NULL, thresh = NULL, verbose = TRUE)
    ## S4 method for signature 'snpgdsIBDClass'
    kingToMatrix(king, sample.include = NULL, thresh = 2^(-11/2), verbose = TRUE)

### Arguments

`king` | Output from KING, either a `snpgdsIBDClass` object from `snpgdsIBDKING` or a character vector of one or more file names output from the command-line version of KING; see 'Details'.
`estimator` | Which estimates to read in when using command-line KING output; must be either "PropIBD" or "Kinship"; see 'Details'.
`sample.include` | An optional vector of sample.id indicating all samples that should be included in the output matrix; see 'Details' for usage.
`thresh` | Kinship threshold for clustering samples to make the output matrix sparse block-diagonal. When `NULL`, no clustering is done. See 'Details'.
`verbose` | A logical indicating whether or not to print status updates to the console; the default is TRUE.

### Details

`king` can be a vector of multiple file names if your KING output is stored in multiple files; e.g. KING –kinship run with family IDs returns a .kin and a .kin0 file for pairs within and not within the same family, respectively.

When reading command-line KING output, the `estimator` argument is required to specify which estimates to read in. When reading KING –ibdseg output, only "PropIBD" will be available; when reading KING –kinship output, only "Kinship" will be available; when reading KING –related output, both "PropIBD" and "Kinship" will be available - use this argument to select which to read. See the KING documentation for details on each estimator.

`sample.include` has two primary functions: 1) It can be used to subset the KING output. 2) `sample.include` can include sample.id not in `king`; this ensures that all samples will be in the output matrix when reading KING –ibdseg output, which likely does not contain all pairs. When left `NULL`, the function will determine the list of samples from what is observed in `king`. It is recommended to use `sample.include` to ensure all of your samples are included in the output matrix.

`thresh` sets a threhsold for clustering samples such that any pair with an estimated kinship value greater than `thresh` is in the same cluster. All pairwise estimates within a cluster are kept, even if they are below `thresh`. All pairwise estimates between clusters are set to 0, creating a sparse, block-diagonal matrix. When `thresh` is `NULL`, no clustering is done and all samples are returned in one block. This feature is useful when converting KING –ibdseg or KING –robust estimates to be used as a kinship matrix, if you have a lower threshold that you consider 'related'. This feature should not be used when converting KING –robust estimates to be used as `divobj` in `pcair` or `pcairPartition`, as PC-AiR requires the negative estimates to identify ancestrally divergent pairs.

### Value

An object of class '`Matrix`' with pairwise kinship coefficients by KING –ibdseg or KING –robust for each pair of individuals in the sample. The estimates are on both the upper and lower triangle of the matrix, and the diagonal is arbitrarily set to 0.5. sample.id are set as the column and row names of the matrix.

### Author(s)

Matthew P. Conomos

### References

Conomos M.P., Miller M., & Thornton T. (2015). Robust Inference of Population Structure for Ancestry Prediction and Correction of Stratification in the Presence of Relatedness. Genetic Epidemiology, 39(4), 276-293.

Manichaikul, A., Mychaleckyj, J.C., Rich, S.S., Daly, K., Sale, M., & Chen, W.M. (2010). Robust relationship inference in genome-wide association studies. Bioinformatics, 26(22), 2867-2873.

### See Also

`pcair` and `pcairPartition` for functions that use the output matrix.

### Examples

    # KING --kinship
    file.king <- c(system.file("extdata", "MXL_ASW.kin0", package="GENESIS"),
                   system.file("extdata", "MXL_ASW.kin", package="GENESIS"))
    KINGmat <- kingToMatrix(file.king, estimator="Kinship")

    # KING --ibdseg
    file.king <- system.file("extdata", "HapMap.seg", package="GENESIS")
    KINGmat <- kingToMatrix(file.king, estimator="PropIBD")

    # SNPRelate
    library(SNPRelate)
    gds <- snpgdsOpen(system.file("extdata", "HapMap_ASW_MXL_geno.gds", package="GENESIS"))
    king <- snpgdsIBDKING(gds)
    KINGmat <- kingToMatrix(king)
    snpgdsClose(gds)

[Package GENESIS version 2.16.1 Index]