For detailed information about GQT please see our Nature Methods paper at:

http://www.nature.com/nmeth/journal/vaop/ncurrent/full/nmeth.3654.html

For questions and discussion about GQT please visit the forum at:

https://groups.google.com/forum/#!forum/gqt-discuss

Genotype Query Tools (GQT) is command line software and a C API for indexing and querying large-scale genotype data sets like those produced by 1000 Genomes, the UK100K, and forthcoming datasets involving millions of genomes. GQT represents genotypes as compressed bitmap indices, which reduce computational burden of variant queries based on sample genotypes, phenotypes, and relationships by orders of magnitude over standard "variant-centric" indexing strategies. This index can significantly expand the capabilities of population-scale analyses by providing interactive-speed queries to data sets with millions of individuals.

1. [Installation] (#installation)
2. [Example work flow] (#example-workflow)
3. [Extra detail] (#extra-detail)

GQT depends on htslib, sqlite3, and lex (flex).

Step 1. Install htslib.

Step 2. Download sqlite amalgamation source.

Step 3. Check to see if your system has lex/flex installed. If not, install.

If both fail then install from source, otherwise skip to step 4

Step 4. Get GQT source then modify the GQT Makefile by setting the HTS_ROOT and SQLITE_ROOT variable in src/Makfile to reflect their locations based on the directories in which they were placed during steps 1 and 2. Compile.

At this point, it is recommended that you copy the gqt binary to a directory that is on your PATH.

Step 5 (Optional) Run the GQT functional tests.

5a. Install bcftools (not necessary for GQT to function, but useful for the functional tests below).

5b. Install plink (v1.9) (not necessary for GQT to function, but useful for the functional tests below)..

5c. In addition, after you install bcftools, you need to also update the directory assigned to BCFTOOLS_PLUGIN in your gqt/test/func/functional_tests.sh file to be the plugins directory in the bcftools source tree. For example, if you compiled bcftool in ~/src, the correct path for BCFTOOLS_PLUGIN would be ~/src/bcftools/plugins. That is:

5d. Lastly, you may need to also upate the directories assigned to either LD_LIBRARY_PATH (linux) or DYLD_LIBRARY_PATH (Mac OS X) in your gqt/test/func/functional_tests.sh file to include the directory where libhts.so.1 is located. For example, if you compiled htslib in ~/src, the correct settings would be:

Okay, now you are ready to run the tests. Make sure you are back in the make gqt source directory.

GQT starts with a target VCF, VCF.GZ, or BCF file. Download an example BCF file.

To index the BCF, GQT needs to know the number of columns and rows in the BCF. This information can be either supplied with command line parameters or GQT can extract this info from the CSI index produced by bcftools.

With the BCF index created, now create the GQT index.

This will create three files:

• chr11.11q14.3.bcf.gqt is the GQT index
• chr11.11q14.3.bcf.bim is the compressed variant metadata
• chr11.11q14.3.bcf.vid is the variant order information

GQT requires a database that describes the samples in the target BCF file. This database is based on the samples in the BCF, and can be optionally augmented by file (typically called PED file) that contains tab separated fields, one line that gives the field name, and the subsequent lines give the field values for each sample. One column in this file must correspond to a sample in the BCF file. By default column 2 is used, but this can be modified by using the -c option. A warning will be generated for each record in the PED file that does not have a corresponding sample in the VCF/BCF. NOTE: Each field in the first line will become a database column. Given the naming restriction, many special characters are not allowed (e.g., %, $, :), and all spaces will be converted to underscores ("_").

For example, the following file includes Family ID, Population and Gender information. Using the default sample column (2), the each Individual ID will be matched with the Sample ID in the VCF/BCF.

Without a PED file the database can be created from the BCF file:

This creates a database named chr11.11q14.3.bcf.db

When a PED file is available it can be included, thus allowing more sophisticated queries based on the phenotypes, ancestries, and relationships of the samples. More on this below.

This creates a database named 1kg.phase3.ped.db

When the database is based only on the BCF file (chr11.11q14.3.bcf.db), queries can be based on the sample names. For example, you can find the variants where at least two of the three listed individuals is heterozygous.