
Compute the Identity by State Matrix for a gen_tibble object
Source: R/pairwise_ibs.R
pairwise_ibs.RdThis function computes the IBS matrix.
Usage
pairwise_ibs(x, ...)
# S3 method for class 'tbl_df'
pairwise_ibs(
x,
as_matrix = FALSE,
type = c("proportion", "adjusted_counts", "raw_counts"),
block_size = bigstatsr::block_size(nrow(x)),
n_cores = bigstatsr::nb_cores(),
missing_correction = c("flat", "allele_freq"),
allele_freqs = NULL,
...
)
# S3 method for class 'vctrs_bigSNP'
pairwise_ibs(
x,
as_matrix = FALSE,
type = c("proportion", "adjusted_counts", "raw_counts"),
block_size = bigstatsr::block_size(length(x)),
n_cores = bigstatsr::nb_cores(),
missing_correction = c("flat", "allele_freq"),
allele_freqs = NULL,
...
)Arguments
- x
a
gen_tibbleobject, or a vector of classvctrs_bigSNP(thegenotypescolumn of agen_tibble, whose individuals are then labelled with the names of the vector).- ...
other arguments passed to specific methods, currently unused.
- as_matrix
boolean, determining whether the results should be a square symmetrical matrix (TRUE), or a tidied tibble (FALSE, the default)
- type
one of:
"proportion" (the default): the proportion of alleles that are identical by state, a similarity (as
--distance ibs flat-missingin PLINK, which writes it to a .mibs file; withmissing_correction = "allele_freq", as--distance ibs, see Details)."adjusted_counts": the allele count distance, a dissimilarity (as
--distance flat-missingin PLINK, which writes it to a .dist file): the number of alleles that differ between two individuals, scaled up by the number of loci over the number of loci genotyped in both individuals, to correct for missing genotypes. It equals2 * n_loci * (1 - proportion), so it is 0 for identical individuals and, with the defaultmissing_correction = "flat", at most2 * n_loci. Withmissing_correction = "allele_freq", as--distancein PLINK (withoutflat-missing), it can exceed2 * n_loci, see Details."raw_counts": the counts of identical alleles and of non-missing alleles, from which the two other quantities are computed.
- block_size
maximum number of loci read at once. Genotypes are compared in a compact bit-packed form, so this has little effect on memory use.
- n_cores
number of cores to be used, it defaults to
bigstatsr::nb_cores()- missing_correction
the correction for missing genotypes, for "proportion" and "adjusted_counts": "flat" (the default, as PLINK 1.9 with the
flat-missingmodifier) or "allele_freq" (as PLINK 1.9's default, which weights loci by their allele frequencies); see Details. It must be "flat" for "raw_counts".- allele_freqs
only used if
missing_correction = "allele_freq": the frequency of the alternate allele at each locus (as PLINK's--read-freq). IfNULL(the default), it is computed from all the individuals ofx(using imputed genotypes ifxis set to use them).
Value
for "proportion" and "adjusted_counts", a tidy tibble with one row
per pair of individuals (columns item1, item2 and value), or a
square matrix if as_matrix = TRUE; for "raw_counts", a list of two
bigstatsr::FBM matrices, ibs (the counts of alleles identical by
state) and valid_n (the counts of non-missing alleles, i.e. twice the
number of loci genotyped in both individuals).
Details
Note that monomorphic sites are currently considered (as in PLINK). Remove
monomorphic sites before running pairwise_ibs() if this is a concern.
Imputed genotypes are used if x is set to use them (see
gt_set_imputed()), and treated as missing otherwise.
Each pair of individuals is compared only on the loci genotyped in both.
Two corrections for missing genotypes are available (missing_correction),
which give the same values when no genotypes are missing:
"flat" (the default), as PLINK 1.9 with the
flat-missingmodifier (--distance ibs flat-missingfor "proportion",--distance flat-missingfor "adjusted_counts"): all loci have the same weight, so the number of alleles that differ between individualsiandj,d_ij, is scaled up byn_loci / n_ij, wheren_ijis the number of loci genotyped in both ("adjusted_counts"), and "proportion" is1 - d_ij / (2 * n_ij)."allele_freq", as PLINK 1.9's default (
--distance ibsand--distance): loci are weighted by their expected contribution to the distance, which depends on their allele frequencyp. Under Hardy-Weinberg equilibrium, the expected number of alleles that differ between two individuals at a locus is4 * p * (1 - p) * (p^2 - p + 1), and PLINK usesw = p * (1 - p) * (p^2 - p + 1)as the weight of the locus (0 for monomorphic loci). "adjusted_counts" is thend_ij * W / W_ij, whereWis the sum of the weights of all loci andW_ijthat of the loci genotyped in both individuals, and "proportion" is1 - adjusted_counts / (2 * n_loci). AsW / W_ijdepends on which loci are genotyped in both individuals, "adjusted_counts" can exceed2 * n_loci(and "proportion" can be negative) for pairs genotyped in both mostly at loci with small weights (loci with a rare allele), as in PLINK. For example, with two loci with frequencies 0.1 and 0.5, a pair of opposite homozygotes at the first locus, missing at the second, has "adjusted_counts" of about 6.58 (more than2 * n_loci = 4). As in PLINK, the weights are scaled to sum to just under2^32and rounded to integers (so values are identical to PLINK's),W_ijexcludes each locus missing in either individual or in both (its weight is removed once), and monomorphic loci have no weight (a missing genotype at a monomorphic locus does not change the distance, but the locus still counts inn_loci). PLINK 1.9 computes the allele frequencies from the founders only (unless--nonfoundersis used), or reads them with--read-freq;pairwise_ibs()computes them from all individuals ofx(the same as PLINK when all individuals are founders, as in data without a pedigree), unless they are given withallele_freqs(e.g. from the founders, withloci_alt_freq()). Loci without any genotype have a frequency of 0.5, as in PLINK. PLINK's1-ibsmodifier (--distance 1-ibs, written to a.mdistfile) gives1 - proportionwith either correction.
Pairs of individuals without any locus genotyped in both (or, with
"allele_freq", without any polymorphic locus genotyped in both) have
NaN (or Inf) values.
pairwise_ibs() is an S3 generic. The method for a gen_tibble
computes the matrix with the method for its genotypes column (of class
vctrs_bigSNP), and labels it with the id of the individuals; grouping
is ignored. Other packages can add methods for their own classes of
genotypes (e.g. genotype likelihoods).
Examples
example_gt <- load_example_gt("gen_tbl")
pairwise_ibs(example_gt, type = "proportion")
#> # A tibble: 21 × 3
#> item1 item2 value
#> <chr> <chr> <dbl>
#> 1 a b 0.8
#> 2 a c 0.7
#> 3 a d 0.833
#> 4 a e 0.75
#> 5 a f 0.6
#> 6 a g 0.7
#> 7 b c 0.75
#> 8 b d 0.8
#> 9 b e 0.5
#> 10 b f 0.5
#> # ℹ 11 more rows
# Alternatively, return a matrix
pairwise_ibs(example_gt, type = "proportion", as_matrix = TRUE)
#> a b c d e f g
#> a 1.0000000 0.80 0.700 0.8333333 0.7500000 0.60 0.700
#> b 0.8000000 1.00 0.750 0.8000000 0.5000000 0.50 0.500
#> c 0.7000000 0.75 1.000 0.6000000 0.7000000 0.75 0.625
#> d 0.8333333 0.80 0.600 1.0000000 0.5833333 0.70 0.500
#> e 0.7500000 0.50 0.700 0.5833333 1.0000000 0.60 0.500
#> f 0.6000000 0.50 0.750 0.7000000 0.6000000 1.00 0.750
#> g 0.7000000 0.50 0.625 0.5000000 0.5000000 0.75 1.000
#> attr(,"class")
#> [1] "pairwise_matrix" "matrix" "array"
# Adjust block_size
pairwise_ibs(example_gt, block_size = 2)
#> # A tibble: 21 × 3
#> item1 item2 value
#> <chr> <chr> <dbl>
#> 1 a b 0.8
#> 2 a c 0.7
#> 3 a d 0.833
#> 4 a e 0.75
#> 5 a f 0.6
#> 6 a g 0.7
#> 7 b c 0.75
#> 8 b d 0.8
#> 9 b e 0.5
#> 10 b f 0.5
#> # ℹ 11 more rows
# Change type
pairwise_ibs(example_gt, type = "adjusted_counts")
#> # A tibble: 21 × 3
#> item1 item2 value
#> <chr> <chr> <dbl>
#> 1 a b 2.4
#> 2 a c 3.6
#> 3 a d 2
#> 4 a e 3
#> 5 a f 4.8
#> 6 a g 3.6
#> 7 b c 3
#> 8 b d 2.4
#> 9 b e 6
#> 10 b f 6
#> # ℹ 11 more rows
pairwise_ibs(example_gt, type = "raw_counts")
#> $ibs
#> A Filebacked Big Matrix of type 'double' with 7 rows and 7 columns.
#>
#> $valid_n
#> A Filebacked Big Matrix of type 'double' with 7 rows and 7 columns.
#>
# PLINK 1.9's default correction for missing genotypes
pairwise_ibs(example_gt,
type = "adjusted_counts",
missing_correction = "allele_freq"
)
#> # A tibble: 21 × 3
#> item1 item2 value
#> <chr> <chr> <dbl>
#> 1 a b 2.40
#> 2 a c 3.75
#> 3 a d 2
#> 4 a e 3
#> 5 a f 5.00
#> 6 a g 3.59
#> 7 b c 3.15
#> 8 b d 2.40
#> 9 b e 5.99
#> 10 b f 6.30
#> # ℹ 11 more rows