Source code for cgr_gwas_qc.parsers.king

"""
KING Relationship Inferences
----------------------------

KING is a toolset to robustly identify different types of relatedness. Unlike
other methods, you should only remove markers that fail QC (i.e., don't mess
with MAF or LD filters).

Kinship Table
+++++++++++++

.. csv-table::
    :header: name, dtype, description

    ID1, string, Individual ID for the first individual of the pair
    ID2, string, Individual ID for the second individual of the pair
    N_SNP, UInt32, The number of SNPs that do not have missing genotypes in either of the individual
    HetHet, float, Proportion of SNPs with double heterozygotes (e.g., AG and AG)
    IBS0, float, Proportion of SNPs with zero IBS (identical-by-state) (e.g., AA and GG)
    HetConc, float, Heterozygous concordance
    HomIBS0, float, Homozygous IBS0
    Kinship, float, Estimated kinship coefficient from the SNP data
    IBD1Seg, float, Total length of IBD1 segments divided by total length of all segments
    IBD2Seg, float, Total length of IBD2 segments divided by total length of all segments
    PropIBD, float, Proportion of genome with shared IBD (e.g., IBD2Seg + IBD1Seg/2)
    relationship, string, The assigned relationship based on Kinship

King Relationships
******************

Categories were assigned based on Kinship ranges provided in the `KING manual`_.

.. csv-table::
    :header: name, description

    ID, duplicate or MZ twin
    D1, 1st degree relative
    D2, 2nd degree relative
    D3, 3rd degree relative
    UN, unrelated

.. _KING manual: http://people.virginia.edu/~wc9c/KING/manual.html#WITHIN

References:
    - http://people.virginia.edu/~wc9c/KING/manual.html
    - Manichaikul A, Mychaleckyj JC, Rich SS, Daly K, Sale M, Chen WM (2010)
      Robust relationship inference in genome-wide association studies.
      Bioinformatics 26(22):2867-2873
"""
import pandas as pd

from cgr_gwas_qc.typing import PathLike

DTYPES = {
    "ID1": "string",
    "ID2": "string",
    "N_SNP": "UInt32",
    "HetHet": "float",
    "IBS0": "float",
    "HetConc": "float",
    "HomIBS0": "float",
    "Kinship": "float",
    "IBD1Seg": "float",
    "IBD2Seg": "float",
    "PropIBD": "float",
    "relationship": "string",
}


def read_related(filename: PathLike, **kwargs) -> pd.DataFrame:
    """Reads the table generated by ``king --related``.

    Reads the king file and re-assigns ID1/ID2 by sorting IDs
    alphanumerically.

    Returns:
        pd.DataFrame

        - ID1
        - ID2
        - N_SNP
        - HetHet
        - IBS0
        - HetConc
        - HomIBS0
        - Kinship
        - IBD1Seg
        - IBD2Seg
        - PropIBD
        - relationship {ID, PO, FS, D2, D3}

    References:
        - http://people.virginia.edu/~wc9c/KING/manual.html#WITHIN
    """

    def _sort_ids(x: pd.Series) -> pd.Series:
        x["ID1"], x["ID2"] = sorted([x.ID1, x.ID2])
        return x

    return (
        pd.read_csv(filename, sep="\t", **kwargs)
        .apply(_sort_ids, axis=1)
        .rename({"InfType": "relationship"}, axis=1)
        .replace({"Dup/MZ": "ID", "2nd": "D2", "3rd": "D3"})
        .reindex(DTYPES.keys(), axis=1)
        .astype(DTYPES)
    )