This function combined two gen_tibbles. It subsets the loci and swaps ref and alt alleles to make the two datasets compatible. The first object is used as a "reference" , and SNPs in the other dataset will be flipped and/or alleles swapped as needed. SNPs that have different alleles in the two datasets (i.e. triallelic) will also be dropped. There are also options (NOT default) to attempt strand flipping to match alleles (often needed in human datasets from different SNP chips), and remove ambiguous alleles (C/G and A/T) where the correct strand can not be guessed.
Usage
# S3 method for class 'gen_tbl'
rbind(
...,
as_is = FALSE,
flip_strand = FALSE,
use_position = FALSE,
quiet = FALSE,
backingfile = NULL
)Arguments
- ...
two
gen_tibbleobjects. Note that this function can not take more objects,rbindhas to be done sequentially for large sets of objects.- as_is
deprecated, and ignored:
rbindalways subsets the loci and swaps alleles as needed (settingas_is = TRUEnever stopped it, and now gives a warning).- flip_strand
boolean on whether strand flipping should be checked to match the two datasets. If this is set to TRUE, ambiguous SNPs (i.e. A/T and C/G) will also be removed, and loci whose
allele_refis missing in both datasets will have their alleles swapped, so that the observed allele becomesallele_ref. It defaults to FALSE- use_position
boolean of whether a combination of chromosome and position should be used for matching SNPs. By default,
rbinduses the locus name, so this is set to FALSE. If the loci names of eithergen_tibbleare integers (as created bygen_tibble(names_as_int = TRUE), which numbers the loci in the order in which they are found in the VCF), the names do not identify the same locus in the two datasets, so loci are always matched by position:use_positionis then set to TRUE automatically (even if it was set to FALSE), with a message unlessquiet = TRUE. In either case, the merged loci keep the names of the reference dataset. When using 'use_position=TRUE', make sure chromosomes are coded in the same way in bothgen_tibbles(a mix of e.g. 'chr1', '1' or 'chromosome1' can be the reasons if an unexpectedly large number variants are dropped when merging).- quiet
boolean whether to omit reporting to screen
- backingfile
the path and prefix of the files used to store the merged data (it will be a .RDS to store the
bigSNPobject and a .bk file as its backing file for the FBM)
Value
a gen_tibble with the merged data.
Details
Loci are matched by name, unless use_position = TRUE. If the loci names of
either gen_tibble are integers (as created by gen_tibble(names_as_int = TRUE)), loci are always matched by chromosome and position (see
use_position).
rbind differs from merging data with plink, which swaps the order of allele1 and allele2 according to minor allele frequency when merging datasets. rbind flips and/or swaps alleles according to the reference dataset, not according to allele frequency.
If both gen_tibbles are phased (see phased in gen_tibble()), the merged
gen_tibble is phased too, and the alleles of phased genotypes are never
swapped or flipped: rbind stops with an error if flip_strand = TRUE, or
if the reference and alternate alleles of any locus in common are swapped
between the two datasets (use rbind_dry_run() to find these loci, in the
column to_swap of its target table, and select_loci() to remove
them). If only one of them is phased, the phase of its genotypes is
discarded (with a message), and the two datasets are merged as unphased
data (swapping alleles as needed).
Examples
example_gt <- load_example_gt("gen_tbl")
# Create a second gen_tibble to merge
test_indiv_meta <- data.frame(
id = c("x", "y", "z"),
population = c("pop1", "pop1", "pop2")
)
test_genotypes <- rbind(
c(1, 1, 0, 1, 1, 0),
c(2, 1, 0, 0, 0, 0),
c(2, 2, 0, 0, 1, 1)
)
test_loci <- data.frame(
name = paste0("rs", 1:6),
chromosome = paste0("chr", c(1, 1, 1, 1, 2, 2)),
position = as.integer(c(3, 5, 65, 343, 23, 456)),
genetic_dist = as.double(rep(0, 6)),
allele_ref = c("A", "T", "C", "G", "C", "T"),
allele_alt = c("T", "C", NA, "C", "G", "A")
)
test_gt <- gen_tibble(
x = test_genotypes,
loci = test_loci,
indiv_meta = test_indiv_meta,
valid_alleles = c("A", "T", "C", "G"),
quiet = TRUE
)
# Merge the datasets using rbind
merged_gt <- rbind(ref = example_gt, target = test_gt, flip_strand = TRUE)
#> harmonising loci between two datasets
#> flip_strand = TRUE ; remove_ambiguous = TRUE
#> -----------------------------
#> dataset: reference
#> number of SNPs: 6 reduced to 2
#> ( 4 are ambiguous, of which 4 were removed)
#> -----------------------------
#> dataset: target
#> number of SNPs: 6 reduced to 2
#> ( 0 were flipped to match the reference set)
#> ( 4 are ambiguous, of which 4 were removed)
#>
#> gen_tibble saved to /tmp/RtmpZHNEm1/gt_merged_1f1516c78a74.gt
#> using FBM RDS: /tmp/RtmpZHNEm1/gt_merged_1f1516c78a74.rds
#> with FBM backing file: /tmp/RtmpZHNEm1/gt_merged_1f1516c78a74.bk
#> make sure that you do NOT delete those files!
#> to reload the gen_tibble in another session, use:
#> gt_load('/tmp/RtmpZHNEm1/gt_merged_1f1516c78a74.gt')
merged_gt
#> # A gen_tibble: 2 loci
#> # A tibble: 10 × 3
#> id population genotypes
#> <chr> <chr> <vctr_SNP>
#> 1 a pop1 [1,0,...]
#> 2 b pop1 [1,0,...]
#> 3 c pop2 [.,0,...]
#> 4 d pop2 [0,0,...]
#> 5 e pop1 [2,0,...]
#> 6 f pop3 [0,0,...]
#> 7 g pop3 [1,1,...]
#> 8 x pop1 [1,0,...]
#> 9 y pop1 [1,0,...]
#> 10 z pop2 [2,0,...]
