Combines VCF records from different sources.
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:
One or more variant sets to combine.
A combined VCF.
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
These Read Filters are automatically applied to the data by the Engine before processing by CombineVariants.
This tool can be run in multi-threaded mode using this option.
This tool applies the following downsampling settings by default.
This tool uses a sliding window on the reference.
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).
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|
|NA||Input VCF file|
|stdout||File to which variants should be written|
|KEEP_IF_ANY_UNFILTERED||Determines how we should handle records seen at the same site in the VCF, but with different FILTER fields|
|NA||Determines how we should merge genotype records for samples shared across the ROD files|
|1||Combine variants and output site only if the variant is present in at least N input files.|
|NA||A comma-separated string describing the priority ordering for the genotypes as far as which record gets emitted|
||set||Key used in the INFO key=value tag emitted describing which set the combined VCF record came from|
||false||If true, assume input VCFs have identical sample sets and disjoint calls|
|false||Don't include loci found to be non-variant after the combining procedure|
||false||If true, then filtered VCFs are treated as uncalled, so that filtered set annotations don't appear in the combined VCF|
||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.|
||false||If true, then the output VCF will contain no INFO or genotype FORMAT fields|
||false||Print out interesting sites requiring complex compatibility merging|
||false||If true, do not output the header containing the command line used|
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.
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.
Don't include loci found to be non-variant after the combining procedure
If true, then filtered VCFs are treated as uncalled, so that filtered set annotations don't appear in the combined VCF
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:
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:
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.
If true, then the output VCF will contain no INFO or genotype FORMAT fields
Used to generate a sites-only file.
Combine variants and output site only if the variant is present in at least N input files.
int 1 [ [ -? ? ] ]
File to which variants should be written
Print out interesting sites requiring complex compatibility merging
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.
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.
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.
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.
GATK version 3.2-2-gec30cee built at 2014/07/17 17:54:48. GTD: NA