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 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 details, see the list further down below the table.
| Name | Type | Default value | Summary |
|---|---|---|---|
| Required | |||
| --variant | List[RodBinding[VariantContext]] | NA | Input VCF file |
| Optional | |||
| --assumeIdenticalSamples | boolean | false | If true, assume input VCFs have identical sample sets and disjoint calls |
| --filteredAreUncalled | boolean | false | If true, then filtered VCFs are treated as uncalled, so that filtered set annotations don't appear in the combined VCF |
| --filteredrecordsmergetype | FilteredRecordMergeType | KEEP_IF_ANY_UNFILTERED | Determines how we should handle records seen at the same site in the VCF, but with different FILTER fields |
| --genotypemergeoption | GenotypeMergeType | NA | Determines how we should merge genotype records for samples shared across the ROD files |
| --mergeInfoWithMaxAC | boolean | 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 | boolean | false | If true, then the output VCF will contain no INFO or genotype FORMAT fields |
| --minimumN | int | 1 | Combine variants and output site only if the variant is present in at least N input files. |
| --out | VariantContextWriter | stdout | File to which variants should be written |
| --printComplexMerges | boolean | false | Print out interesting sites requiring complex compatibility merging |
| --rod_priority_list | String | NA | A comma-separated string describing the priority ordering for the genotypes as far as which record gets emitted |
| --setKey | String | set | Key used in the INFO key=value tag emitted describing which set the combined VCF record came from |
| --suppressCommandLineHeader | boolean | 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..
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..
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. --variant binds reference ordered data. This argument supports ROD files of the following types: BCF2, VCF, VCF3
See also Guide Index | Technical Documentation Index | Support Forum
GATK version 2.5-2-gdb4546e built at 2013/05/01 09:32:36.
