This function computes the IBS matrix.
Usage
snp_ibs(
X,
ind.row = bigstatsr::rows_along(X),
ind.col = bigstatsr::cols_along(X),
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
)Arguments
- X
a bigstatsr::FBM.code256 matrix (as found in the
genotypesslot of a bigsnpr::bigSNP object). Genotypes are decoded with itscode256, and values other than 0, 1 and 2 are treated as missing.- ind.row
An optional vector of the row indices that are used. If not specified, all rows are used. Don't use negative indices.
- ind.col
An optional vector of the column indices that are used. If not specified, all columns are used. Don't use negative indices.
- 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)."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), wheren_lociis the number of loci used, so it is 0 for identical individuals and, with the defaultmissing_correction = "flat", at most2 * n_loci. Note that, withoutflat-missing, PLINK corrects for missing genotypes differently, which gives slightly different values when genotypes are missing (seemissing_correction); with that correction (missing_correction = "allele_freq"), it can exceed2 * n_loci, and "proportion" can be negative (seepairwise_ibs())."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 columns 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 of "proportion" and "adjusted_counts": "flat" (the default, as PLINK 1.9's
flat-missingmodifier) or "allele_freq" (PLINK 1.9's default, which weights the missing loci by their allele frequencies). Seepairwise_ibs()for 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 inind.col(as PLINK's--read-freq); either allele can be used, as the weights are the same for both. IfNULL(the default), it is computed from the genotypes of the individuals inind.row. Missing values are set to 0.5, as PLINK does for loci without genotypes.
Value
for "proportion" and "adjusted_counts", a matrix with one row and
one column per individual; 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 counted (as in PLINK). Remove monomorphic sites beforehand if this is a concern.
See pairwise_ibs() for the two corrections for missing genotypes
(missing_correction).
Examples
example_gt <- load_example_gt("gen_tbl")
X <- attr(example_gt$genotypes, "fbm")
snp_ibs(X)
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,] 1.0000000 0.80 0.700 0.8333333 0.7500000 0.60 0.700
#> [2,] 0.8000000 1.00 0.750 0.8000000 0.5000000 0.50 0.500
#> [3,] 0.7000000 0.75 1.000 0.6000000 0.7000000 0.75 0.625
#> [4,] 0.8333333 0.80 0.600 1.0000000 0.5833333 0.70 0.500
#> [5,] 0.7500000 0.50 0.700 0.5833333 1.0000000 0.60 0.500
#> [6,] 0.6000000 0.50 0.750 0.7000000 0.6000000 1.00 0.750
#> [7,] 0.7000000 0.50 0.625 0.5000000 0.5000000 0.75 1.000
# Compute for individuals 1 to 5
snp_ibs(X, ind.row = 1:5, ind.col = 1:5)
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 1.00 0.7500000 0.7500000 0.800 0.800
#> [2,] 0.75 1.0000000 0.8333333 0.750 0.500
#> [3,] 0.75 0.8333333 1.0000000 0.625 0.625
#> [4,] 0.80 0.7500000 0.6250000 1.000 0.600
#> [5,] 0.80 0.5000000 0.6250000 0.600 1.000
# Adjust block.size
snp_ibs(X, block.size = 2)
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,] 1.0000000 0.80 0.700 0.8333333 0.7500000 0.60 0.700
#> [2,] 0.8000000 1.00 0.750 0.8000000 0.5000000 0.50 0.500
#> [3,] 0.7000000 0.75 1.000 0.6000000 0.7000000 0.75 0.625
#> [4,] 0.8333333 0.80 0.600 1.0000000 0.5833333 0.70 0.500
#> [5,] 0.7500000 0.50 0.700 0.5833333 1.0000000 0.60 0.500
#> [6,] 0.6000000 0.50 0.750 0.7000000 0.6000000 1.00 0.750
#> [7,] 0.7000000 0.50 0.625 0.5000000 0.5000000 0.75 1.000
# Change type
snp_ibs(X, type = "proportion")
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,] 1.0000000 0.80 0.700 0.8333333 0.7500000 0.60 0.700
#> [2,] 0.8000000 1.00 0.750 0.8000000 0.5000000 0.50 0.500
#> [3,] 0.7000000 0.75 1.000 0.6000000 0.7000000 0.75 0.625
#> [4,] 0.8333333 0.80 0.600 1.0000000 0.5833333 0.70 0.500
#> [5,] 0.7500000 0.50 0.700 0.5833333 1.0000000 0.60 0.500
#> [6,] 0.6000000 0.50 0.750 0.7000000 0.6000000 1.00 0.750
#> [7,] 0.7000000 0.50 0.625 0.5000000 0.5000000 0.75 1.000
snp_ibs(X, type = "adjusted_counts")
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,] 0.0 2.4 3.6 2.0 3.0 4.8 3.6
#> [2,] 2.4 0.0 3.0 2.4 6.0 6.0 6.0
#> [3,] 3.6 3.0 0.0 4.8 3.6 3.0 4.5
#> [4,] 2.0 2.4 4.8 0.0 5.0 3.6 6.0
#> [5,] 3.0 6.0 3.6 5.0 0.0 4.8 6.0
#> [6,] 4.8 6.0 3.0 3.6 4.8 0.0 3.0
#> [7,] 3.6 6.0 4.5 6.0 6.0 3.0 0.0
snp_ibs(X, 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
snp_ibs(X, type = "adjusted_counts", missing_correction = "allele_freq")
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7]
#> [1,] 0.000000 2.395837 3.747789 2.000000 3.000000 4.997052 3.593755
#> [2,] 2.395837 0.000000 3.148350 2.395837 5.989592 6.296700 5.974047
#> [3,] 3.747789 3.148350 0.000000 4.997052 3.747789 3.328097 4.722525
#> [4,] 2.000000 2.395837 4.997052 0.000000 5.000000 3.747789 5.989592
#> [5,] 3.000000 5.989592 3.747789 5.000000 0.000000 4.997052 5.989592
#> [6,] 4.997052 6.296700 3.328097 3.747789 4.997052 0.000000 3.148350
#> [7,] 3.593755 5.974047 4.722525 5.989592 5.989592 3.148350 0.000000
