sgkit.pedigree_inverse_kinship#

sgkit.pedigree_inverse_kinship(ds, *, method='diploid', parent='parent', stat_Hamilton_Kerr_tau='stat_Hamilton_Kerr_tau', stat_Hamilton_Kerr_lambda='stat_Hamilton_Kerr_lambda', return_relationship=False, allow_half_founders=False, merge=True)#

Calculate the inverse of the kinship matrix from pedigree structure.

This method can optionally return the inverse of the additive relationship matrix (ARM or A-matrix).

Parameters:
ds Dataset

Dataset containing pedigree structure.

method {‘diploid’, ‘Hamilton-Kerr’}Literal['diploid', 'Hamilton-Kerr'] (default: 'diploid')

The method used for kinship estimation. Defaults to “diploid” which is only suitable for pedigrees in which all samples are diploids resulting from sexual reproduction. The “Hamilton-Kerr” method is suitable for autopolyploid and mixed-ploidy datasets following Hamilton and Kerr 2017 [1].

parent Hashable (default: 'parent')

Input variable name holding parents of each sample as defined by sgkit.variables.parent_spec. If the variable is not present in ds, it will be computed using parent_indices().

stat_Hamilton_Kerr_tau Hashable (default: 'stat_Hamilton_Kerr_tau')

Input variable name holding stat_Hamilton_Kerr_tau as defined by sgkit.variables.stat_Hamilton_Kerr_tau_spec. This variable is only required for the “Hamilton-Kerr” method.

stat_Hamilton_Kerr_lambda Hashable (default: 'stat_Hamilton_Kerr_lambda')

Input variable name holding stat_Hamilton_Kerr_lambda as defined by sgkit.variables.stat_Hamilton_Kerr_lambda_spec. This variable is only required for the “Hamilton-Kerr” method.

return_relationship bool (default: False)

If True, the inverse of the additive relationship matrix will be returned in addition to the inverse of the kinship matrix.

allow_half_founders bool (default: False)

If False (the default) then a ValueError will be raised if any individuals only have a single recorded parent. If True then the unrecorded parent will be assumed to be a unique founder unrelated to all other founders. If the Hamilton-Kerr method is used with half-founders then the tau and lambda parameters for gametes contributing to the unrecorded parent will be assumed to be equal to those of the gamete originating from that parent.

merge bool (default: True)

If True (the default), merge the input dataset and the computed output variables into a single dataset, otherwise return only the computed output variables.

Return type:

Dataset

Returns:

: A dataset containing sgkit.variables.stat_pedigree_inverse_kinship_spec. and, if return_relationship is True, sgkit.variables.stat_pedigree_inverse_relationship_spec.

Raises:

  • ValueError – If an unknown method is specified.

  • ValueError – If the (intermediate) kinship matrix is singular.

  • ValueError – If the diploid method is used with a non-diploid dataset.

  • ValueError – If the diploid method is used and the parents dimension does not have a length of two.

  • ValueError – If the Hamilton-Kerr method is used and a sample has more than two contributing parents.

  • ValueError – If the pedigree contains half-founders and allow_half_founders=False.

Note

Dimensions of sgkit.variables.stat_pedigree_inverse_kinship_spec and sgkit.variables.stat_pedigree_inverse_relationship_spec are named samples_0 and samples_1.

Note

The Hamilton-Kerr method may be applied to a dataset with more than two parent columns so long as each sample has two or fewer contributing parents as indicated by the stat_Hamilton_Kerr_tau variable. Within this variable, a contributing parent is indicated by a value greater than zero. Each sample must also have at least one (possibly unknown) contributing parent. Therefore, each row of the stat_Hamilton_Kerr_tau variable must have either one or two non-zero values.

Examples

Inbred diploid pedigree returning inverse additive relationship matrix:

>>> import sgkit as sg
>>> ds = sg.simulate_genotype_call_dataset(n_variant=1, n_sample=4, seed=1)
>>> ds.sample_id.values 
array(['S0', 'S1', 'S2', 'S3'], dtype='<U2')
>>> ds["parent_id"] = ["samples", "parents"], [
...     [".", "."],
...     [".", "."],
...     ["S0", "S1"],
...     ["S0", "S2"]
... ]
>>> ds = sg.pedigree_inverse_kinship(ds, return_relationship=True)
>>> ds["stat_pedigree_inverse_kinship"].values 
array([[ 4.,  1., -1., -2.],
       [ 1.,  3., -2.,  0.],
       [-1., -2.,  5., -2.],
       [-2.,  0., -2.,  4.]])
>>> ds["stat_pedigree_inverse_relationship"].values 
array([[ 2. ,  0.5, -0.5, -1. ],
       [ 0.5,  1.5, -1. ,  0. ],
       [-0.5, -1. ,  2.5, -1. ],
       [-1. ,  0. , -1. ,  2. ]])

Unreduced gamete and half-clone:

>>> ds = sg.simulate_genotype_call_dataset(n_variant=1, n_sample=4, n_ploidy=4, seed=1)
>>> ds.sample_id.values 
array(['S0', 'S1', 'S2', 'S3'], dtype='<U2')
>>> ds["parent_id"] = ["samples", "parents"], [
...     ['.', '.'],
...     ['.', '.'],
...     ['S0','S1'],  # diploid * tetraploid
...     ['S2', '.'],  # half-clone of 'S2'
... ]
>>> ds["stat_Hamilton_Kerr_tau"] = ["samples", "parents"], [
...     [1, 1],
...     [2, 2],
...     [2, 2],  # unreduced gamete from diploid 'S0'
...     [2, 0],  # contribution from 'S2' only
... ]
>>> ds["stat_Hamilton_Kerr_lambda"] = ["samples", "parents"], [
...     [0, 0],
...     [0, 0],
...     [0.1, 0],  # increased probability of IBD in unreduced gamete
...     [0, 0],
... ]
>>> ds = sg.pedigree_inverse_kinship(ds, method="Hamilton-Kerr")
>>> ds["stat_pedigree_inverse_kinship"].values  
array([[ 5.33333333,  3.33333333, -6.66666667,  0.        ],
       [ 3.33333333,  7.33333333, -6.66666667,  0.        ],
       [-6.66666667, -6.66666667, 17.40112994, -4.06779661],
       [ 0.        ,  0.        , -4.06779661,  4.06779661]])

Unreduced gamete and half-clone using a third parent column to indicate clonal propagation:

>>> ds = sg.simulate_genotype_call_dataset(n_variant=1, n_sample=4, n_ploidy=4, seed=1)
>>> ds.sample_id.values 
array(['S0', 'S1', 'S2', 'S3'], dtype='<U2')
>>> ds["parent_id"] = ["samples", "parents"], [
...     ['.', '.', '.'],
...     ['.', '.', '.'],
...     ['S0', 'S1', '.'],  # diploid * tetraploid
...     ['.', '.', 'S2'],  # half-clone of 'S2'
... ]
>>> ds["stat_Hamilton_Kerr_tau"] = ["samples", "parents"], [
...     [1, 1, 0],
...     [2, 2, 0],
...     [2, 2, 0],  # unreduced gamete from diploid 'S0'
...     [0, 0, 2],  # contribution from 'S2' only
... ]
>>> ds["stat_Hamilton_Kerr_lambda"] = ["samples", "parents"], [
...     [0, 0, 0],
...     [0, 0, 0],
...     [0.1, 0, 0],  # increased probability of IBD in unreduced gamete
...     [0, 0, 0],
... ]
>>> ds = sg.pedigree_inverse_kinship(ds, method="Hamilton-Kerr")
>>> ds["stat_pedigree_inverse_kinship"].values  
array([[ 5.33333333,  3.33333333, -6.66666667,  0.        ],
       [ 3.33333333,  7.33333333, -6.66666667,  0.        ],
       [-6.66666667, -6.66666667, 17.40112994, -4.06779661],
       [ 0.        ,  0.        , -4.06779661,  4.06779661]])

References

[1] - Matthew G. Hamilton, and Richard J. Kerr 2017. “Computation of the inverse additive relationship matrix for autopolyploid and multiple-ploidy populations.” Theoretical and Applied Genetics 131: 851-860.