VariantsToTable

Extract specific fields from a VCF file to a tab-delimited table

Category Variant Manipulation Tools

Traversal LocusWalker

PartitionBy LOCUS


Overview

This tool is designed to extract fields from the VCF to a table format that is more convenient to work with in downstream analyses.

The user specifies one or more fields to print with the -F NAME, each of which appears as a single column in the output file, with a header named NAME, and the value of this field in the VCF one per line. NAME can be any standard VCF column (CHROM, ID, QUAL) or any binding in the INFO field (AC=10). In addition, there are specially supported values like EVENTLENGTH (length of the event), TRANSITION (for SNPs), HET (count of het genotypes), HOM-REF (count of homozygous reference genotypes), HOM-VAR (count of homozygous variant genotypes), NO-CALL (count of no-call genotypes), TYPE (the type of event), VAR (count of non-reference genotypes), NSAMPLES (number of samples), NCALLED (number of called samples), GQ (from the genotype field; works only for a file with a single sample), and MULTI-ALLELIC (is the record from a multi-allelic site).

Input

  • A VCF file
  • A list of -F fields to write

Output

A tab-delimited file containing the values of the requested fields in the VCF file

Usage example

     java -jar GenomeAnalysisTK.jar \
     -R reference.fasta
     -T VariantsToTable \
     -V file.vcf \
     -F CHROM -F POS -F ID -F QUAL -F AC \
     -o results.table
 

would produce a file that looks like:

     CHROM    POS ID      QUAL    AC
     1        10  .       50      1
     1        20  rs10    99      10
     et cetera...
 

Caveats

  • Some annotations cannot be applied to all variant sites, so VCFs typically contain records where some annotation values are missing. By default this tool the tool will emit the special value NA for the missing annotations if you request export of an annotation for which not all records have values. You can override this behavior by setting --errorIfMissingData in the command line. As a result, the tool will throw an error if a record is missing a value.
  • When you request export of sample-level annotations (FORMAT field annotations such as GT), the annotations will be identified per-sample. If multiple samples are present in the VCF, the columns will be ordered alphabetically by sample name (SM tag).

Additional Information

Read filters

These Read Filters are automatically applied to the data by the Engine before processing by VariantsToTable.


Command-line Arguments

Engine arguments

All tools inherit arguments from the GATK Engine' "CommandLineGATK" argument collection, which can be used to modify various aspects of the tool's function. For example, the -L argument directs the GATK engine to restrict processing to specific genomic intervals; or the -rf argument allows you to apply certain read filters to exclude some of the data from the analysis.

VariantsToTable specific arguments

This table summarizes the command-line arguments that are specific to this tool. For more details on each argument, see the list further down below the table or click on an argument name to jump directly to that entry in the list.

Argument name(s) Default value Summary
Required Inputs
--variant
 -V
NA Input VCF file
Optional Outputs
--out
 -o
stdout File to which results should be written
Optional Parameters
--fields
 -F
[] The name of each field to capture for output in the table
--genotypeFields
 -GF
[] The name of each genotype field to capture for output in the table
--maxRecords
 -M
-1 If provided, we will emit at most maxRecord records to the table
Optional Flags
--splitMultiAllelic
 -SMA
false If provided, we will split multi-allelic records into multiple lines of output
Advanced Flags
--errorIfMissingData
 -EMD
false If provided, we will require every record to contain every field
--moltenize
false If provided, we will produce molten output
--showFiltered
 -raw
false If provided, field values from filtered records will be included in the output

Argument details

Arguments in this list are specific to this tool. Keep in mind that other arguments are available that are shared with other tools (e.g. command-line GATK arguments); see Inherited arguments above.


--errorIfMissingData / -EMD

If provided, we will require every record to contain every field
By default, this tool will write out NA values indicating missing data when it encounters a field without a value in a record. If this flag is added to the command, the tool will instead exit with an error if missing data is encountered..

boolean  false


--fields / -F

The name of each field to capture for output in the table
-F NAME can be any standard VCF column (CHROM, ID, QUAL) or any binding in the INFO field (e.g., AC=10). Note that to capture GENOTYPE (FORMAT) field values, see the GF argument. This argument accepts any number of inputs. So -F CHROM -F POS is allowed.

List[String]  []


--genotypeFields / -GF

The name of each genotype field to capture for output in the table
-GF NAME can be any binding in the FORMAT field (e.g., GQ, PL). Note this argument accepts any number of inputs. So -GF GQ -GF PL is allowed.

List[String]  []


--maxRecords / -M

If provided, we will emit at most maxRecord records to the table
If provided, then this tool will exit with success after this number of VCF records have been emitted to the file.

int  -1  [ [ -∞  ∞ ] ]


--moltenize / -moltenize

If provided, we will produce molten output
By default, this tool emits one line per usable VCF record (or per allele if the -SMA flag is provided). Using the -moltenize flag will cause records to be split into multiple lines of output: one for each field provided with -F or one for each combination of sample and field provided with -GF. Note that the "Sample" column for -F fields will always be "site".

boolean  false


--out / -o

File to which results should be written

PrintStream  stdout


--showFiltered / -raw

If provided, field values from filtered records will be included in the output
By default this tool only emits values for fields where the FILTER field is either PASS or . (unfiltered). Throwing this flag will cause VariantsToTable to emit values regardless of the FILTER field value.

boolean  false


--splitMultiAllelic / -SMA

If provided, we will split multi-allelic records into multiple lines of output
By default, records with multiple ALT alleles will comprise just one line of output; note that in general this can make your resulting file unreadable/malformed for certain tools like R, as the representation of multi-allelic INFO field values are often comma-separated lists of values. Using the flag will cause multi-allelic records to be split into multiple lines of output (one for each allele in the ALT field); INFO field values that are not lists are copied for each of the output records while only the appropriate entry is used for lists.

boolean  false


--variant / -V

Input VCF file
Variants from this VCF file are used by this tool as input. The file must at least contain the standard VCF header lines, but can be empty (i.e., no variants are contained in the file).

This argument supports reference-ordered data (ROD) files in the following formats: BCF2, VCF, VCF3

R List[RodBinding[VariantContext]]  NA


Return to top


See also GATK Documentation Index | Tool Docs Index | Support Forum

GATK version 3.8-0-ge9d806836 built at 2017/07/29 01:40:22.