The Perl modules and scripts

VCFtools contains a Perl API ( and a number of Perl scripts that can be used to perform common tasks with VCF files such as file validation, file merging, intersecting, complements, etc. The Perl tools support all versions of the VCF specification (3.2, 3.3, 4.0, 4.1 and 4.2), nevertheless, the users are encouraged to use the latest versions VCFv4.1 or VCFv4.2. The VCFtools in general have been used mainly with diploid data, but the Perl tools aim to support polyploid data as well. Run any of the Perl scripts with the --help switch to obtain more help.

Many of the Perl scripts require that the VCF files are compressed by bgzip and indexed by tabix (both tools are part of the tabix package, available for download here). The VCF files can be compressed and indexed using the following commands

bgzip my_file.vcf
tabix -p vcf my_file.vcf.gz

The tools


Fill or recalculate AN and AC INFO fields.

zcat file.vcf.gz | fill-an-ac | bgzip -c > out.vcf.gz

(Read more)
Usage: fill-an-ac [OPTIONS] < in.vcf >out.vcf
   -h, -?, --help                      This help message.


Annotates the VCF file with flanking sequence (INFO/FS tag) masking known variants with N's. Useful for designing primers.

fill-fs -r /path/to/refseq.fa | vcf-query '%CHROM\t%POS\t%INFO/FS\n' >

(Read more)
About: Annotate VCF with flanking sequence (INFO/FS tag)
Usage: fill-fs [OPTIONS] file.vcf
   -b, --bed-mask <file>           Regions to mask (tabix indexed), multiple files can be given
   -c, --cluster <int>             Do self-masking of clustered variants within this range.
   -l, --length <int>              Flanking sequence length [100]
   -m, --mask-char <char|lc>       The character to use or "lc" for lowercase. This option must preceed
                                       -b, -v or -c in order to take effect. With multiple files works
                                        as a switch on the command line, see the example below [N]
   -r, --refseq <file>             The reference sequence.
   -v, --vcf-mask <file>           Mask known variants in the flanking sequence, multiple files can be given (tabix indexed)
   -h, -?, --help                  This help message.
   # Mask variants from the VCF file with N's and use lowercase for the bed file regions
   fill-fs file.vcf -v mask.vcf -m lc -b mask.bed


Fill missing reference info and sequence MD5s into VCF header.

fill-ref-md5 -i "SP:Homo\ Sapiens" -r ref.fasta in.vcf.gz -d ref.dict out.vcf.gz

(Read more)
About: The script computes MD5 sum of the reference sequence and inserts
   'reference' and 'contig' tags into header as recommended by VCFv4.1.
   The VCF file must be compressed and tabix indexed, as it takes advantage
   of the lightning fast tabix reheader functionality.
Usage: fill-ref-md5 [OPTIONS] in.vcf.gz out.vcf.gz
   -d, --dictionary <file>             Where to read/write computed MD5s. Opened in append mode, existing records are not touched.
   -i, --info <AS:xx,SP:xx,TX:xx>      Optional info on reference assembly (AS), species (SP), taxonomy (TX)
   -r, --refseq <file>                 The reference sequence in fasta format indexed by samtools faidx
   -h, -?, --help                      This help message.
   fill-ref-md5 -i AS:NCBIM37,SP:"Mus\ Musculus" -r NCBIM37_um.fa  -d NCBIM37_um.fa.dict in.vcf.gz out.vcf.gz


Fill missing rsIDs. This script has been discontinued, please use vcf-annotate instead.


The script adds or removes filters and custom annotations to VCF files. To add custom annotations to VCF files, create TAB delimited file with annotations such as

#CHR FROM TO ANNOTATION 1 12345 22345 gene1 1 67890 77890 gene2

Compress the file (using bgzip annotations), index (using tabix -s 1 -b 2 -e 3 annotations.gz) and run

cat in.vcf | vcf-annotate -a annotations.gz \
   -d key=INFO,ID=ANN,Number=1,Type=Integer,Description='My custom annotation' \
   -c CHROM,FROM,TO,INFO/ANN > out.vcf

The script is also routinely used to apply filters. There are a number of predefined filters and custom filters can be easily added, see vcf-annotate -h for examples. Some of the predefined filters take advantage of tags added by bcftools, the descriptions of the most frequently asked ones follow:

Strand Bias .. Tests if variant bases tend to come from one strand. Fisher's exact test for 2x2 contingency table where the row variable is being the reference allele or not and the column variable is strand. Two-tail P-value is used.
End Distance Bias .. Tests if variant bases tend to occur at a fixed distance from the end of reads, which is usually an indication of misalignment. (T-test)
Base Quality Bias .. Tests if variant bases tend to occur with a quality bias (T-test). This filter is by default effectively disabled as it is set to 0.

Note: A fast htslib C version of this tool is now available (see bcftools annotate).

(Read more)
About: Annotates VCF file, adding filters or custom annotations. Requires tabix indexed file with annotations.
   Currently it can annotate ID, QUAL, FILTER and INFO columns, but will be extended on popular demand.
   For examples of user-defined filters see online documentation or examples/filters.txt in vcftools distribution.
Usage: cat in.vcf | vcf-annotate [OPTIONS] > out.vcf
   -a, --annotations <file.gz>         The tabix indexed file with the annotations: CHR\tFROM[\tTO][\tVALUE]+.
   -c, --columns <list>                The list of columns in the annotation file, e.g. CHROM,FROM,TO,-,QUAL,INFO/STR,INFO/GN. The dash
                                           in this example indicates that the third column should be ignored. If TO is not
                                           present, it is assumed that TO equals to FROM. When REF and ALT columns are present, only
                                           matching lines are annotated.
   -d, --description <file|string>     Header annotation, e.g. key=INFO,ID=HM2,Number=0,Type=Flag,Description='HapMap2 membership'.
                                           The descriptions can be read from a file, one annotation per line.
       --fill-AC-AN                    (Re)Calculate AC and AN tags
       --fill-HWE                      (Re)Calculate HWE, AC and AN tags
       --fill-ICF                      (Re)Calculate Inbreeding Coefficient F, HWE, AC and AN
       --fill-type                     Annotate INFO/TYPE with snp,del,ins,mnp,complex
   -f, --filter <file|list>            Apply filters, list is in the format flt1=value/flt2/flt3=value/etc. If argument to -f is a file,
                                           user-defined filters be applied. See User Defined Filters below.
   -H, --hard-filter                   Remove lines with FILTER anything else than PASS or "."
   -n, --normalize-alleles             Make REF and ALT alleles more compact if possible (e.g. TA,TAA -> T,TA).
   -r, --remove <list>                 Comma-separated list of tags to be removed (e.g. ID,INFO/DP,FORMAT/DP,FILTER).
   -h, -?, --help                      This help message.
	+                           		Apply all filters with default values (can be overriden, see the example below).
	-X                          		Exclude the filter X
	1, StrandBias  FLOAT        		Min P-value for strand bias (INFO/PV4) [0.0001]
	2, BaseQualBias  FLOAT      		Min P-value for baseQ bias (INFO/PV4) [0]
	3, MapQualBias  FLOAT       		Min P-value for mapQ bias (INFO/PV4) [0]
	4, EndDistBias  FLOAT       		Min P-value for end distance bias (INFO/PV4) [0.0001]
	a, MinAB  INT               		Minimum number of alternate bases (INFO/DP4) [2]
	c, SnpCluster  INT1,INT2    		Filters clusters of 'INT1' or more SNPs within a run of 'INT2' bases []
	D, MaxDP  INT               		Maximum read depth (INFO/DP or INFO/DP4) [10000000]
	d, MinDP  INT               		Minimum read depth (INFO/DP or INFO/DP4) [2]
	H, HWE  FLOAT               		Minimum P-value for HWE and F<0 (invokes --fill-HWE) []
	H2, HWE2  FLOAT              		Minimum P-value for HWE (plus F<0) (INFO/AC and INFO/AN or --fill-AC-AN) []
	HG, HWE_G3  FLOAT            		Minimum P-value for HWE and F<0 (INFO/HWE and INFO/G3) []
	q, MinMQ  INT               		Minimum RMS mapping quality for SNPs (INFO/MQ) [10]
	Q, Qual  INT                		Minimum value of the QUAL field [10]
	r, RefN                     		Reference base is N []
	v, VDB  FLOAT               		Minimum Variant Distance Bias (INFO/VDB) [0]
	W, GapWin  INT              		Window size for filtering adjacent gaps [3]
	w, SnpGap  INT              		SNP within INT bp around a gap to be filtered [10]
   zcat in.vcf.gz | vcf-annotate -a annotations.gz -d descriptions.txt -c FROM,TO,CHROM,ID,INFO/DP | bgzip -c >out.vcf.gz
   zcat in.vcf.gz | vcf-annotate -f +/-a/c=3,10/q=3/d=5/-D -a annotations.gz -d key=INFO,ID=GN,Number=1,Type=String,Description='Gene Name' | bgzip -c >out.vcf.gz
   zcat in.vcf.gz | vcf-annotate -a -c CHROM,POS,REF,ALT,ID,-,-,- | bgzip -c >out.vcf.gz
   zcat in.vcf.gz | vcf-annotate -r FILTER/MinDP | bgzip -c >out.vcf.gz
Where descriptions.txt contains:
   key=INFO,ID=GN,Number=1,Type=String,Description='Gene Name'
The file with dbSNP IDs can be downloaded from
(Read even more)
# Examples of user-defined filters. Edit and run with -f filters.txt.
# The examples below are self-explanatory. Notice the use of the predefined
#  variables ($PASS, $FAIL, $MATCH, $RECORD) and methods (error).

# In this example, a minimum value of AF1=0.1 is required
    tag  => 'INFO/AF1',                       # The VCF tag to apply this filter on
        name => 'MinAF',                          # The filter ID
        desc => 'Minimum AF1 [0.01]',             # Description for the VCF header
        test => sub { return $MATCH < 0.01 ? $FAIL : $PASS },

# Filter all indels (presence of INDEL tag is tested)
    tag      => 'INFO/INDEL',
    apply_to => 'indels',         # Can be one of SNPs, indels, all. Default: [All]
    name     => 'Indel',
    desc     => 'INDEL tag present',
    test     => sub { return $FAIL },

# Only loci with enough reads supporting the variant will pass the filter
    tag      => 'INFO/DP4',
    name     => 'FewAlts',
    desc     => 'Too few reads supporting the variant',
    apply_to => 'SNPs',
    test     => sub {
        if ( !($MATCH =~ /^([^,]+),([^,]+),([^,]+),(.+)$/) )
            error("Could not parse INFO/DP4: $CHROM:$POS [$MATCH]");
        if ( 0.1*($1+$2) > $3+$4  ) { return $PASS; }
        return $FAIL;

# Example of filtering based on genotype columns and the QUAL column
    tag      => 'FORMAT/PL',
    name     => 'NoHets',
    desc     => 'Inbred homozygous mouse, no hets expected',
    apply_to => 'SNPs',
    test     => sub {
            for my $pl (@$MATCH)
                my @pls = split(/,/,$pl);
                if ( $pls[1]<$pls[0] && $pls[1]<$pls[2] ) { return $FAIL; }
        return $PASS;

# This example splits the four PV4 values into four tags names PV0, PV1, PV2 and PV3.
#   Note the use of the 'header' key, and the $RECORD and $VCF variables.
    header   => [
                    qq[key=INFO,ID=PV0,Number=1,Type=Float,Description="P-value for strand bias"],
                    qq[key=INFO,ID=PV1,Number=1,Type=Float,Description="P-value for baseQ bias"],
                    qq[key=INFO,ID=PV2,Number=1,Type=Float,Description="P-value for mapQ bias"],
                    qq[key=INFO,ID=PV3,Number=1,Type=Float,Description="P-value for tail distance bias"]
    tag      => 'INFO/PV4',
    name     => 'SplitPV4',
    desc     => 'Split PV4',
    apply_to => 'all',
    test     => sub {
        my @vals = split(/,/,$MATCH);
        $$RECORD[7] = $VCF->add_info_field($$RECORD[7],'PV0'=>$vals[0],'PV1'=>$vals[1],'PV2'=>$vals[2],'PV3'=>$vals[3]);
        return $PASS;

# Do whatever you want with every record and edit it according to your needs. This silly
#   example removes the tag SILLY in records where ID is set and depth is bigger than 5.
    tag      => 'Dummy',
    test     => sub {
        if ( $$RECORD[2] eq '.' ) { return $PASS; } # Modify only lines with ID
        my $dp = $vcf->get_info_field($$RECORD[7],'DP');
        if ( $dp>5 ) { $$RECORD[7] = $VCF->add_info_field($$RECORD[7],'SILLY'=>undef); }
        return $PASS;

# Filter records with the value XY absent or not equal to 42
    tag      => 'Dummy',
    header   => [
        qq[key=FILTER,ID=XY,Description="XY not OK"],
    test     => sub {
        my $xy      = $VCF->get_info_field($$RECORD[7],'XY');
        my $is_bad  = ( !defined $xy or $xy!=42 ) ? 1 : 0;
        $$RECORD[6] = $VCF->add_filter($$RECORD[6],'XY'=>$is_bad);
        return $PASS;

# Annotate INFO field with SINGLETON flag when one and only one sample is different from the reference
    header   => [
        qq[key=INFO,ID=SINGLETON,Number=0,Type=Flag,Description="Only one non-ref sample"],
    tag      => 'FORMAT/GT',
    name     => 'Dummy',
    desc     => 'Dummy',
    test     => sub {
        my $nalt = 0;
        for my $gt (@$MATCH)
            my @gt = $VCF->split_gt($gt);
            for my $allele (@gt)
                if ( $allele ne 0 && $allele ne '.' ) { $nalt++; last; }
            if ( $nalt>1 ) { last; }
        if ( $nalt==1 ) { $$RECORD[7] = $VCF->add_info_field($$RECORD[7],'SINGLETON'=>''); }
        return $PASS;

# Set genotypes to unknown ("." or "./." depending on ploidy) when coverage is low (by Shane McCarthy).
    tag      => 'FORMAT/DP',
    name     => 'MinSampleDP',
    desc     => 'Genotypes set to . for samples with DP < 2',
    apply_to => 'all',
    test     => sub {
        my $i = 8;
        for my $dp (@$MATCH)
            next unless ($dp<2);
            my @format = split(/:/,$$RECORD[$i]);
            $format[0] = $format[0] =~ /\// ? "./." : ".";
            $$RECORD[$i] = join(":",@format);
        return $PASS;


Compares positions in two or more VCF files and outputs the numbers of positions contained in one but not the other files; two but not the other files, etc, which comes handy when generating Venn diagrams. The script also computes numbers such as nonreference discordance rates (including multiallelic sites), compares actual sequence (useful when comparing indels), etc.

vcf-compare -H A.vcf.gz B.vcf.gz C.vcf.gz

Note: A fast htslib C version of this tool is now available (see bcftools stats).

(Read more)
About: Compare bgzipped and tabix indexed VCF files. (E.g. bgzip file.vcf; tabix -p vcf file.vcf.gz)
Usage: vcf-compare [OPTIONS] file1.vcf file2.vcf ...
       vcf-compare -p plots chr1.cmp chr2.cmp ...
   -a, --apply-filters                 Ignore lines where FILTER column is anything else than PASS or '.'
   -c, --chromosomes <list|file>       Same as -r, left for backward compatibility. Please do not use as it will be dropped in the future.
   -d, --debug                         Debugging information. Giving the option multiple times increases verbosity
   -g, --cmp-genotypes                 Compare genotypes, not only positions
       --ignore-indels                 Exclude sites containing indels from genotype comparison
   -m, --name-mapping <list|file>      Use with -g when comparing files with differing column names. The argument to this options is a
                                           comma-separated list or one mapping per line in a file. The names are colon separated and must
                                           appear in the same order as the files on the command line.
       --INFO <string> [<int>]         Calculate genotype errors by INFO. Use zero based indecies if field has more than one value. Can be
                                           given multiple times.
   -p, --plot <prefix>                 Create plots. Multiple files (e.g. per-chromosome outputs from vcf-compare) can be given.
   -R, --refseq <file>                 Compare the actual sequence, not just positions. Use with -w to compare indels.
   -r, --regions <list|file>           Process the given regions (comma-separated list or one region per line in a file).
   -s, --samples <list|file>           Process only the listed samples. Excluding unwanted samples may increase performance considerably.
   -t, --title <string>                Title for graphs (see also -p)
   -w, --win <int>                     In repetitive sequences, the same indel can be called at different positions. Consider
                                           records this far apart as matching (be it a SNP or an indel).
   -h, -?, --help                      This help message.


Concatenates VCF files (for example split by chromosome). Note that the input and output VCFs will have the same number of columns, the script does not merge VCFs by position (see also vcf-merge).

In the basic mode it does not do anything fancy except for a sanity check that all files have the same columns. When run with the -s option, it will perform a partial merge sort, looking at limited number of open files simultaneously.

vcf-concat A.vcf.gz B.vcf.gz C.vcf.gz | gzip -c > out.vcf.gz

(Read more)
About: Convenience tool for concatenating VCF files (e.g. VCFs split by chromosome).
   In the basic mode it does not do anything fancy except for a sanity check that all
   files have the same columns.  When run with the -s option, it will perform a partial
   merge sort, looking at limited number of open files simultaneously.
Usage: vcf-concat [OPTIONS] A.vcf.gz B.vcf.gz C.vcf.gz > out.vcf
   -c, --check-columns              Do not concatenate, only check if the columns agree.
   -f, --files <file>               Read the list of files from a file.
   -p, --pad-missing                Write '.' in place of missing columns. Useful for joining chrY with the rest.
   -s, --merge-sort <int>           Allow small overlaps in N consecutive files.
   -h, -?, --help                   This help message.


Apply VCF variants to a fasta file to create consensus sequence.

cat ref.fa | vcf-consensus file.vcf.gz > out.fa

(Read more)
Usage: cat ref.fa | vcf-consensus [OPTIONS] in.vcf.gz > out.fa
   -h, -?, --help                   This help message.
   -H, --haplotype <int>            Apply only variants for the given haplotype (1,2)
   -s, --sample <name>              If not given, all variants are applied
   # Get the consensus for one region. The fasta header lines are then expected
   # in the form ">chr:from-to".
   samtools faidx ref.fa 8:11870-11890 | vcf-consensus in.vcf.gz > out.fa


Convert between VCF versions, currently from VCFv3.3 to VCFv4.0.

zcat file.vcf.gz | vcf-convert -r reference.fa > out.vcf

(Read more)
About: Convert between VCF versions.
Usage: cat in.vcf | vcf-convert [OPTIONS] > out.vcf
   -r, --refseq <file>              The reference sequence in samtools faindexed fasta file. (Not required with SNPs only.)
   -v, --version <string>           4.0, 4.1, 4.2
   -h, -?, --help                   This help message.


A tool for finding differences between groups of samples, useful in trio analysises, cancer genomes etc.

In the example below variants with average mapping quality of 30 (-f MinMQ=30) and minimum depth of 10 (-d 10) are considered. Only novel alleles are reported (-n). Then vcf-query is used to extract the INFO/NOVEL* annotations into a table. Finally the sites are sorted by confidence of the site being different in the child (-k5,5nr).

vcf-annotate -f MinMQ=30 file.vcf | vcf-contrast -n +Child -Mother,Father -d 10 -f | vcf-query -f '%CHROM %POS\t%INFO/NOVELTY\t%INFO/NOVELAL\t%INFO/NOVELGT[\t%SAMPLE %GTR %PL]\n' | sort -k3,3nr | head

(Read more)
About: Finds differences amongst samples adding NOVELGT, NOVELAL and NOVELTY annotations to INFO field.
       Note that haploid genotypes are internally treated as homozygous diploid genotypes, therefore
       "0/1" and "1" are considered different genotypes.
Usage: vcf-contrast +<list> -<list> [OPTIONS] file.vcf.gz
   +<list>                             List of samples where unique variant is expected
   -<list>                             List of background samples
   -d, --min-DP <int>                  Minimum depth across all -<list> samples
   -f, --apply-filters                 Skip sites with FILTER column different from PASS or "."
   -n, --novel-sites                   Print only records with novel genotypes
   -h, -?, --help                      This help message.
   # Test if any of the samples A,B is different from all C,D,E
   vcf-contrast +A,B -C,D,E -m file.vcf.gz

   # Same as above but printing only sites with novel variants and table output
   vcf-contrast -n +A,B -C,D,E -m file.vcf.gz | vcf-query -f '%CHROM %POS\t%INFO/NOVELTY\t%INFO/NOVELAL\t%INFO/NOVELGT[\t%SAMPLE %GTR %PL]\n'

   # Similar to above but require minimum mapping quality of 20
   vcf-annotate -f MinMQ=20 file.vcf.gz | vcf-contrast +A,B,C -D,E,F -f


Please take a look at vcf-annotate and bcftools view which does what you are looking for. Apologies for the non-intuitive naming.
Note: A fast HTSlib C version of a filtering tool is now available (see bcftools filter and bcftools view).


Fixes diploid vs haploid genotypes on sex chromosomes, including the pseudoautosomal regions.

(Read more)
About: Reads in a VCF file with any (commonly used) newline representation and outputs with the
	current system's newline representation.
Usage: vcf-fix-newlines [OPTIONS]
   -i, --info                      Report if the file is consistent with the current platform based.
   -h, -?, --help                  This help message.
	vcf-fix-newlines -i file.vcf
	vcf-fix-newlines file.vcf.gz > out.vcf
	cat file.vcf | vcf-fix-newlines > out.vcf


Fixes diploid vs haploid genotypes on sex chromosomes, including the pseudoautosomal regions.

(Read more)
Usage: cat broken.vcf | vcf-fix-ploidy [OPTIONS] > fixed.vcf
   -a, --assumed-sex <sex>         M or F, required if the list is not complete in -s
   -l, --fix-likelihoods           Add or remove het likelihoods (not the default behaviour)
   -p, --ploidy <file>             Ploidy definition. The default is shown below.
   -s, --samples <file>            List of sample sexes (sample_name [MF]).
   -h, -?, --help                  This help message.
Default ploidy definition:
   ploidy =>
       X =>
           # The pseudoautosomal regions 60,001-2,699,520 and 154,931,044-155,270,560 with the ploidy 2
           { from=>1, to=>60_000, M=>1 },
           { from=>2_699_521, to=>154_931_043, M=>1 },
       Y =>
           # No chrY in females and one copy in males
           { from=>1, to=>59_373_566, M=>1, F=>0 },
       MT =>
           # Haploid MT in males and females
           { from=>1, to => 16_569, M=>1, F=>1 },


Calculate in-frame ratio.

Note: A fast htslib C version of this tool is now available (see bcftools stats).

(Read more)
About: Currently calculates in-frame ratio.
Usage: vcf-indel-stats [OPTIONS] < in.vcf > out.txt
   -h, -?, --help                   This help message.
   -e, --exons <file>               Tab-separated file with exons (chr,from,to; 1-based, inclusive)
   -v, --verbose


Creates intersections and complements of two or more VCF files. Given multiple VCF files, it can output the list of positions which are shared by at least N files, at most N files, exactly N files, etc. The first example below outputs positions shared by at least two files and the second outputs positions present in the files A but absent from files B and C.

vcf-isec -n +2 A.vcf.gz B.vcf.gz | bgzip -c > out.vcf.gz
vcf-isec -c A.vcf.gz B.vcf.gz C.vcf.gz | bgzip -c > out.vcf.gz

Note: A fast htslib C version of this tool is now available (see bcftools isec).

(Read more)
About: Create intersections, unions, complements on bgzipped and tabix indexed VCF or tab-delimited files.
   Note that lines from all files can be intermixed together on the output, which can yield
   unexpected results.
Usage: vcf-isec [OPTIONS] file1.vcf file2.vcf ...
   -a, --apply-filters                 Ignore lines where FILTER column is anything else than PASS or '.'
   -c, --complement                    Output positions present in the first file but missing from the other files.
   -d, --debug                         Debugging information
   -f, --force                         Continue even if the script complains about differing columns, VCF versions, etc.
   -o, --one-file-only                 Print only entries from the left-most file. Without -o, all unique positions will be printed.
   -n, --nfiles [+-=]<int>             Output positions present in this many (=), this many or more (+), or this many or fewer (-) files.
   -p, --prefix <path>                 If present, multiple files will be created with all possible isec combinations. (Suitable for Venn Diagram analysis.)
   -r, --regions <list|file>           Do only the given regions (comma-separated list or one region per line in a file).
   -t, --tab <chr:pos:file>            Tab-delimited file with indexes of chromosome and position columns. (1-based indexes)
   -w, --win <int>                     In repetitive sequences, the same indel can be called at different positions. Consider
                                           records this far apart as matching (be it a SNP or an indel).
   -h, -?, --help                      This help message.
   bgzip file.vcf; tabix -p vcf file.vcf.gz
   bgzip; tabix -s 1 -b 2 -e 2


Merges two or more VCF files into one so that, for example, if two source files had one column each, on output will be printed a file with two columns. See also vcf-concat for concatenating VCFs split by chromosome.

vcf-merge A.vcf.gz B.vcf.gz C.vcf.gz | bgzip -c > out.vcf.gz

Note that this script is not intended for concatenating VCF files. For this, use vcf-concat instead.
Note: A fast htslib C version of this tool is now available (see bcftools merge).

(Read more)
About: Merges VCF files by position, creating multi-sample VCFs from fewer-sample VCFs.
   The tool requires bgzipped and tabix indexed VCF files on input. (E.g. bgzip file.vcf; tabix -p vcf file.vcf.gz)
   If you need to concatenate VCFs (e.g. files split by chromosome), look at vcf-concat instead.
Usage: vcf-merge [OPTIONS] file1.vcf file2.vcf.gz ... > out.vcf
   -c, --collapse <snps|indels|both|any|none>      treat as identical sites with differing alleles [any]
   -d, --remove-duplicates                         If there should be two consecutive rows with the same chr:pos, print only the first one.
   -H, --vcf-header <file>                         Use the provided VCF header
   -h, -?, --help                                  This help message.
   -r, --regions <list|file>                       Do only the given regions (comma-separated list or one region per line in a file).
   -R, --ref-for-missing <string>                  Use the REF allele instead of the default missing genotype. Because it is not obvious
                                                       what ploidy should be used, a user-defined string is used instead (e.g. 0/0).
   -s, --silent                                    Try to be a bit more silent, no warnings about duplicate lines.
   -t, --trim-ALTs                                 If set, redundant ALTs will be removed


Concatenates multiple overlapping VCFs preserving phasing.

(Read more)
About: The script takes multiple overlapping pre-phased chunks and concatenates them into one VCF
   using heterozygous calls from the overlaps to determine correct phase.
Usage: vcf-phased-join [OPTIONS] A.vcf B.vcf C.vcf
   -j, --min-join-quality <num>    Quality threshold for gluing the pre-phased blocks together [10]
   -l, --list <file>               List of VCFs to join.
   -o, --output <file>             Output file name. When "-" is supplied, STDOUT and STDERR will be used
   -q, --min-PQ <num>              Break pre-phased segments if PQ value is lower in input VCFs [0.6]
   -h, -?, --help                  This help message


Powerful tool for converting VCF files into format defined by the user. Supports retrieval of subsets of positions, columns and fields.

vcf-query file.vcf.gz 1:10327-10330
vcf-query file.vcf -f '%CHROM:%POS %REF %ALT [ %DP]\n'

Note: A fast htslib C version of this tool is now available (see bcftools query).

(Read more)
Usage: vcf-query [OPTIONS] file.vcf.gz
   -c, --columns <file|list>           List of comma-separated column names or one column name per line in a file.
   -f, --format <string>               The default is '%CHROM:%POS\t%REF[\t%SAMPLE=%GT]\n'
   -l, --list-columns                  List columns.
   -r, --region chr:from-to            Retrieve the region. (Runs tabix.)
       --use-old-method                Use old version of API, which is slow but more robust.
   -h, -?, --help                      This help message.
   %CHROM          The CHROM column (similarly also other columns)
   %GT             Translated genotype (e.g. C/A)
   %GTR            Raw genotype (e.g. 0/1)
   %INFO/TAG       Any tag in the INFO column
   %LINE           Prints the whole line
   %SAMPLE         Sample name
   []              The brackets loop over all samples
   %*<A><B>        All format fields printed as KEY<A>VALUE<B>
   vcf-query file.vcf.gz 1:1000-2000 -c NA001,NA002,NA003
   vcf-query file.vcf.gz -r 1:1000-2000 -f '%CHROM:%POS\t%REF\t%ALT[\t%SAMPLE:%*=,]\n'
   vcf-query file.vcf.gz -f '[%GT\t]%LINE\n'
   vcf-query file.vcf.gz -f '[%GT\ ]%LINE\n'
   vcf-query file.vcf.gz -f '%CHROM\_%POS\t%INFO/DP\t%FILTER\n'


Reorder columns

vcf-shuffle-cols -t template.vcf.gz file.vcf.gz > out.vcf

(Read more)
About: Reorder columns to match the order in the template VCF.
Usage: vcf-shuffle-cols [OPTIONS] -t template.vcf.gz file.vcf.gz > out.vcf
   -t, --template <file>            The file with the correct order of the columns.
   -h, -?, --help                   This help message.


Sort a VCF file.

vcf-sort file.vcf.gz

(Read more)
Usage: vcf-sort > out.vcf
       cat file.vcf | vcf-sort > out.vcf
   -c, --chromosomal-order       Use natural ordering (1,2,10,MT,X) rather then the default (1,10,2,MT,X). This requires
                                     new version of the unix "sort" command which supports the --version-sort option.
   -p, --parallel <int>          Change the number of sorts run concurrently to <int>
   -t, --temporary-directory     Use a directory other than /tmp as the temporary directory for sorting.
   -h, -?, --help                This help message.


Outputs some basic statistics: the number of SNPs, indels, etc.

vcf-stats file.vcf.gz

Note: A fast htslib C version of this tool is now available (see bcftools stats).

(Read more)
Usage: vcf-stats [OPTIONS] file.vcf.gz
   -d, --dump <file>                           Take an existing dump file and recreate the files (works with -p)
   -f, --filters <filter1,filter2>             List of filters such as column/field (any value), column/field=bin:max (cluster in bins),column/field=value (exact value)
   -p, --prefix <dir/string>                   Prefix of output files. If slashes are present, directories will be created.
   -s, --samples <list>                        Process only the listed samples, - for none. Excluding unwanted samples may increase performance considerably.
   -h, -?, --help                              This help message.

   # Calculate stats separately for the filter field, quality and non-indels
   vcf-stats file.vcf.gz -f FILTER,QUAL=10:200,INFO/INDEL=False -p out/

   # Calculate stats for all samples
   vcf-stats file.vcf.gz -f FORMAT/DP=10:200 -p out/

   # Calculate stats only for the sample NA00001
   vcf-stats file.vcf.gz -f SAMPLE/NA00001/DP=1:200 -p out/

   vcf-stats file.vcf.gz > perl.dump


Remove some columns from the VCF file.

vcf-subset -c NA0001,NA0002 file.vcf.gz | bgzip -c > out.vcf.gz

Note: A fast HTSlib C version of this tool is now available (see bcftools view).

(Read more)
Usage: vcf-subset [OPTIONS] in.vcf.gz > out.vcf
   -a, --trim-alt-alleles           Remove alternate alleles if not found in the subset
   -c, --columns <string>           File or comma-separated list of columns to keep in the vcf file. If file, one column per row
   -e, --exclude-ref                Exclude rows not containing variants.
   -f, --force                      Proceed anyway even if VCF does not contain some of the samples.
   -p, --private                    Print only rows where only the subset columns carry an alternate allele.
   -r, --replace-with-ref           Replace the excluded types with reference allele instead of dot.
   -t, --type <list>                Comma-separated list of variant types to include: ref,SNPs,indels,MNPs,other.
   -u, --keep-uncalled              Do not exclude rows without calls.
   -h, -?, --help                   This help message.
   cat in.vcf | vcf-subset -r -t indels -e -c SAMPLE1 > out.vcf


A lightweight script for quick calculation of Ts/Tv ratio.

cat file.vcf | vcf-tstv

Note: A fast htslib C version of this tool is now available (see bcftools stats).

(Read more)
Usage: cat file.vcf | vcf-tstv
   -h, -?, --help                  This help message.


A simple script which converts the VCF file into a tab-delimited text file listing the actual variants instead of ALT indexes.

zcat file.vcf.gz | vcf-to-tab >

(Read more)
Usage: vcf-to-tab [OPTIONS] < in.vcf >
   -h, -?, --help                   This help message.
   -i, --iupac                      Use one-letter IUPAC codes


vcf-validator file.vcf.gz

(Read more)
Usage: vcf-validator [OPTIONS] file.vcf.gz
   -d, --duplicates                 Warn about duplicate positions.
   -u, --unique-messages            Output all messages only once.
   -h, -?, --help                   This help message.

For examples how to use the Perl API, it is best to look at some of the simpler scripts, for example vcf-to-tab. The detailed documentation can be obtained by running