Build a Variant Index of a GDS for Fast Region Lookup

Source: R/extract_variant_set.R

Reads the chromosome, position and variant id of every record of a GDS once and returns a per-chromosome index. extract_variant_set uses it to find a region's records by binary search on the positions and to set the GDS filter by file position, instead of re-reading the chromosome's variant table and matching ids for every region. A scan builds the index once per open file and passes it to every region.

build_variant_index(gds)

Arguments

gds

An open SeqVarGDSClass object or a character file path. If a path, the file is opened and closed internally. Any filter set on an open handle is reset, since the index describes the whole file.

Value

A glow_variant_index: a named list with one element per chromosome value found in the file. Each element is a list with pos (integer positions in file order), variant_id (the records' ids), sel (their file positions, 1-based) and sorted (TRUE when the positions are non-decreasing, which enables the binary search). The attribute n_variants is the file's record count.

Details

Cost: one read of the three vectors, linear in the file's record count (about 0.2 s and 8 MB for a chromosome of one million records). Positions in a GDS written by SeqArray::seqVCF2GDS or plink_to_gds are sorted within a chromosome; an unsorted chromosome is still supported, by a mask over the index instead of the binary search.

Examples

if (FALSE) { # \dontrun{
gds <- SeqArray::seqOpen("chr22.gds")
idx <- build_variant_index(gds)
vset <- extract_variant_set(gds, list(chr = "22", start = 1.7e7, end = 1.8e7),
                            variant_filter(), variant_index = idx)
SeqArray::seqClose(gds)
} # }