Documentation

VariantsToTable

Emits specific fields from a VCF file to a tab-deliminated table

Category Variant Evaluation and Manipulation Tools

Traversal LocusWalker

PartitionBy LOCUS


Overview

This walker accepts a single VCF file and writes out user-selected fields from the VCF as a header-containing, tab-deliminated file. 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). Note that if a VCF record is missing a value, then the tool by default throws an error, but the special value NA can be emitted instead with appropriate tool arguments.

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

Examples

     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...
 

Additional Information

Read filters

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

Downsampling settings

This tool applies the following downsampling settings by default.

  • Mode: BY_SAMPLE
  • To coverage: 1,000

Command-line Arguments

Inherited arguments

The arguments described in the entries below can be supplied to this tool to modify its behavior. For example, the -L argument directs the GATK engine restricts processing to specific genomic intervals (this is an Engine capability and is therefore available to all GATK walkers).

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
--allowMissingData
 -AMD
false If provided, we will not 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.


--allowMissingData / -AMD

If provided, we will not require every record to contain every field
By default, this tool throws a UserException when it encounters a field without a value in some record. This is generally useful when you mistype -F CHROM, so that you get a friendly warning about CHROM not being found before the tool runs through 40M 1000G records. However, in some cases you genuinely want to allow such fields (e.g., AC not being calculated for filtered records, if included). When provided, this argument will cause VariantsToTable to write out NA values for missing fields instead of throwing an error.

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).

--variant binds reference ordered data. This argument supports ROD files of the following types: BCF2, VCF, VCF3

R List[RodBinding[VariantContext]]


See also Guide Index | Tool Documentation Index | Support Forum

GATK version 3.2-2-gec30cee built at 2014/07/17 17:54:48. GTD: NA