CombineVariants

Combines VCF records from different sources.

Category Variant Evaluation and Manipulation Tools

Traversal LocusWalker

PartitionBy LOCUS


Overview

CombineVariants combines VCF records from different sources. Any (unique) name can be used to bind your rod data and any number of sources can be input. This tool currently supports two different combination types for each of variants (the first 8 fields of the VCF) and genotypes (the rest). Merge: combines multiple records into a single one; if sample names overlap then they are uniquified. Union: assumes each rod represents the same set of samples (although this is not enforced); using the priority list (if provided), it emits a single record instance at every position represented in the rods. CombineVariants will include a record at every site in all of your input VCF files, and annotate which input ROD bindings the record is present, pass, or filtered in in the set attribute in the INFO field. In effect, CombineVariants always produces a union of the input VCFs. However, any part of the Venn of the N merged VCFs can be exacted using JEXL expressions on the set attribute using SelectVariants. If you want to extract just the records in common between two VCFs, you would first run CombineVariants on the two files to generate a single VCF and then run SelectVariants to extract the common records with -select 'set == "Intersection"', as worked out in the detailed example in the documentation guide. Note that CombineVariants supports multi-threaded parallelism (8/15/12). This is particularly useful when converting from VCF to BCF2, which can be expensive. In this case each thread spends CPU time doing the conversion, and the GATK engine is smart enough to merge the partial BCF2 blocks together efficiency. However, since this merge runs in only one thread, you can quickly reach diminishing returns with the number of parallel threads. -nt 4 works well but -nt 8 may be too much. Some fine details about the merging algorithm:

  • As of GATK 2.1, when merging multiple VCF records at a site, the combined VCF record has the QUAL of the first VCF record with a non-MISSING QUAL value. The previous behavior was to take the max QUAL, which resulted in sometime strange downstream confusion

Input

One or more variant sets to combine.

Output

A combined VCF.

Examples

 java -Xmx2g -jar GenomeAnalysisTK.jar \
   -R ref.fasta \
   -T CombineVariants \
   --variant input1.vcf \
   --variant input2.vcf \
   -o output.vcf \
   -genotypeMergeOptions UNIQUIFY

 java -Xmx2g -jar GenomeAnalysisTK.jar \
   -R ref.fasta \
   -T CombineVariants \
   --variant:foo input1.vcf \
   --variant:bar input2.vcf \
   -o output.vcf \
   -genotypeMergeOptions PRIORITIZE
   -priority foo,bar
 

Additional Information

Read filters

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

Parallelism options

This tool can be run in multi-threaded mode using this option.

Downsampling settings

This tool applies the following downsampling settings by default.

  • Mode: BY_SAMPLE
  • To coverage: 1,000

Window size

This tool uses a sliding window on the reference.

  • Window start: -50 bp before the locus
  • Window stop: 50 bp after the locus

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

CombineVariants 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 variants should be written
Optional Parameters
--filteredrecordsmergetype
 -filteredRecordsMergeType
KEEP_IF_ANY_UNFILTERED Determines how we should handle records seen at the same site in the VCF, but with different FILTER fields
--genotypemergeoption
 -genotypeMergeOptions
NA Determines how we should merge genotype records for samples shared across the ROD files
--minimumN
 -minN
1 Combine variants and output site only if the variant is present in at least N input files.
--rod_priority_list
 -priority
NA A comma-separated string describing the priority ordering for the genotypes as far as which record gets emitted
--setKey
set Key used in the INFO key=value tag emitted describing which set the combined VCF record came from
Optional Flags
--assumeIdenticalSamples
false If true, assume input VCFs have identical sample sets and disjoint calls
--excludeNonVariants
 -env
false Don't include loci found to be non-variant after the combining procedure
--filteredAreUncalled
false If true, then filtered VCFs are treated as uncalled, so that filtered set annotations don't appear in the combined VCF
--mergeInfoWithMaxAC
false If true, when VCF records overlap the info field is taken from the one with the max AC instead of only taking the fields which are identical across the overlapping records.
--minimalVCF
false If true, then the output VCF will contain no INFO or genotype FORMAT fields
--printComplexMerges
false Print out interesting sites requiring complex compatibility merging
--suppressCommandLineHeader
false If true, do not output the header containing the command line used

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.


--assumeIdenticalSamples / -assumeIdenticalSamples

If true, assume input VCFs have identical sample sets and disjoint calls
This option allows the user to perform a simple merge (concatenation) to combine the VCFs, drastically reducing the runtime.

boolean  false


--excludeNonVariants / -env

Don't include loci found to be non-variant after the combining procedure

boolean  false


--filteredAreUncalled / -filteredAreUncalled

If true, then filtered VCFs are treated as uncalled, so that filtered set annotations don't appear in the combined VCF

boolean  false


--filteredrecordsmergetype / -filteredRecordsMergeType

Determines how we should handle records seen at the same site in the VCF, but with different FILTER fields

The --filteredrecordsmergetype argument is an enumerated type (FilteredRecordMergeType), which can have one of the following values:

KEEP_IF_ANY_UNFILTERED
Union - leaves the record if any record is unfiltered.
KEEP_IF_ALL_UNFILTERED
Requires all records present at site to be unfiltered. VCF files that don't contain the record don't influence this.
KEEP_UNCONDITIONAL
If any record is present at this site (regardless of possibly being filtered), then all such records are kept and the filters are reset.

FilteredRecordMergeType  KEEP_IF_ANY_UNFILTERED


--genotypemergeoption / -genotypeMergeOptions

Determines how we should merge genotype records for samples shared across the ROD files

The --genotypemergeoption argument is an enumerated type (GenotypeMergeType), which can have one of the following values:

UNIQUIFY
Make all sample genotypes unique by file. Each sample shared across RODs gets named sample.ROD.
PRIORITIZE
Take genotypes in priority order (see the priority argument).
UNSORTED
Take the genotypes in any order.
REQUIRE_UNIQUE
Require that all samples/genotypes be unique between all inputs.

GenotypeMergeType


--mergeInfoWithMaxAC / -mergeInfoWithMaxAC

If true, when VCF records overlap the info field is taken from the one with the max AC instead of only taking the fields which are identical across the overlapping records.

boolean  false


--minimalVCF / -minimalVCF

If true, then the output VCF will contain no INFO or genotype FORMAT fields
Used to generate a sites-only file.

boolean  false


--minimumN / -minN

Combine variants and output site only if the variant is present in at least N input files.

int  1  [ [ -?  ? ] ]


--out / -o

File to which variants should be written

VariantContextWriter  stdout


--printComplexMerges / -printComplexMerges

Print out interesting sites requiring complex compatibility merging

boolean  false


--rod_priority_list / -priority

A comma-separated string describing the priority ordering for the genotypes as far as which record gets emitted
Used when taking the union of variants that contain genotypes. A complete priority list MUST be provided.

String


--setKey / -setKey

Key used in the INFO key=value tag emitted describing which set the combined VCF record came from
Set to 'null' if you don't want the set field emitted.

String  set


--suppressCommandLineHeader / -suppressCommandLineHeader

If true, do not output the header containing the command line used
This option allows the suppression of the command line in the VCF header. This is most often usefully when combining variants for dozens or hundreds of smaller VCFs.

boolean  false


--variant / -V

Input VCF file
The VCF files to merge together variants can take any number of arguments on the command line. Each -V argument will be included in the final merged output VCF. If no explicit name is provided, the -V arguments will be named using the default algorithm: variants, variants2, variants3, etc. The user can override this by providing an explicit name -V:name,vcf for each -V argument, and each named argument will be labeled as such in the output (i.e., set=name rather than set=variants2). The order of arguments does not matter unless except for the naming, so if you provide an rod priority list and no explicit names than variants, variants2, etc are technically order dependent. It is strongly recommended to provide explicit names when a rod priority list is provided.

R List[RodBindingCollection[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