BCF1

The BCF1 format output by versions of samtools <= 0.1.19 is not compatible with this version of bcftools. To read BCF1 files one can use the view command from old versions of bcftools packaged with samtools versions <= 0.1.19 to convert to VCF, which can then be read by this version of bcftools.

    samtools-0.1.19/bcftools/bcftools view file.bcf1 | bcftools view

VARIANT CALLING

See bcftools call for variant calling from the output of the samtools mpileup command. In versions of samtools <= 0.1.19 calling was done with bcftools view. Users are now required to choose between the old samtools calling model (-c/--consensus-caller) and the new multiallelic calling model (-m/--multiallelic-caller). The multiallelic calling model is recommended for most tasks.

Common Options

    bcftools query -f'%CHROM\t%POS\t%REF,%ALT\n' file.vcf

bcftools annotate [OPTIONS] FILE

This command allows to add or remove annotations.

    ##INFO=<ID=TAG,Number=1,Type=Integer,Description="Example header line">

Examples:

    # Remove three fields
    bcftools annotate -x ID,INFO/DP,FORMAT/DP file.vcf.gz

    # Add ID, QUAL and INFO/TAG, not replacing TAG if already present
    bcftools annotate -a src.bcf -c ID,QUAL,+TAG dst.bcf

    # Carry over all INFO and FORMAT annotations except FORMAT/GT
    bcftools annotate -a src.bcf -c INFO,^FORMAT/GT dst.bcf

    # Annotate from a tab-delimited file
    bcftools annotate -a annots.tab.gz -h annots.hdr -c CHROM,POS,REF,ALT,-,TAG file.vcf

bcftools call [OPTIONS] FILE

This command replaces the former bcftools view caller. Some of the original functionality has been temporarily lost in the process of transition under htslib, but will be added back on popular demand. The original calling model can be invoked with the -c option.

bcftools concat [OPTIONS] FILE1 FILE2 […]

Concatenate or combine VCF/BCF files. All source files must have the same sample columns appearing in the same order. Can be used, for example, to concatenate chromosome VCFs into one VCF, or combine a SNP VCF and an indel VCF into one. The input files must be sorted by chr and position. The files must be given in the correct order to produce sorted VCF on output unless the -a, --allow-overlaps option is specified.

bcftools convert [OPTIONS] FILE

  .gen
  ----
  1:111485207_G_A rsID1 111485207 G A 0 1 0 0 1 0
  1:111494194_C_T rsID2 111494194 C T 0 1 0 0 0 1

  .sample
  -------
  ID_1 ID_2 missing
  0 0 0
  sample1 sample1 0
  sample2 sample2 0

  .haps
  ----
  1:111485207_G_A rsID1 111485207 G A 0 1 0 0
  1:111494194_C_T rsID2 111494194 C T 0 1 0 0

  .haps
  -----
  0 1 0 0 1 0
  0 1 0 0 0 1

  .legend
  -------
  id position a0 a1
  1:111485207_G_A 111485207 G A
  1:111494194_C_T 111494194 C T

  .sample
  -------
  sample population group sex
  sample1 sample1 sample1 2
  sample2 sample2 sample2 2

# Convert 23andme results into VCF
bcftools convert -c ID,CHROM,POS,AA -s SampleName -f 23andme-ref.fa --tsv2vcf 23andme.txt -Oz -o out.vcf.gz

bcftools filter [OPTIONS] FILE

Apply fixed-threshold filters.

The SNPs at positions 1 and 7 are filtered, positions 0 and 8 are not:
         0123456789
    ref  .G.GT..G..
    del  .A.G-..A..
Here the positions 1 and 6 are filtered, 0 and 7 are not:
         0123-456789
    ref  .G.G-..G..
    ins  .A.GT..A..

The second indel is filtered:
         012345678901
    ref  .GT.GT..GT..
    del  .G-.G-..G-..
And similarly here, the second is filtered:
         01 23 456 78
    ref  .A-.A-..A-..
    ins  .AT.AT..AT..

bcftools gtcheck [OPTIONS] [-g genotypes.vcf.gz] query.vcf.gz

Checks sample identity or, without -g, multi-sample cross-check is performed.

        \sum_s { min_G { PL_a(G) + PL_b(G) } },

bcftools index [OPTIONS] <in.bcf>|<in.vcf.gz>

Creates index for bgzip compressed VCF/BCF files for random access. CSI (coordinate-sorted index) is created by default. The CSI format supports indexing of chromosomes up to length 2^31. TBI (tabix index) index files, which support chromosome lengths up to 2^29, can be created by using the -t/--tbi option or using the tabix program packaged with htslib. When loading an index file, bcftools will try the CSI first and then the TBI.

bcftools isec [OPTIONS] A.vcf.gz B.vcf.gz […]

Creates intersections, unions and complements of VCF files. Depending on the options, the program can output records from one (or more) files which have (or do not have) corresponding records with the same position in the other files.

    bcftools isec -p dir A.vcf.gz B.vcf.gz

    bcftools isec -p dir -n=2 -w1 A.vcf.gz B.vcf.gz

    bcftools isec -p dir -n-1 -c all A.vcf.gz B.vcf.gz

bcftools merge [OPTIONS] A.vcf.gz B.vcf.gz […]

Merge multiple VCF/BCF files from non-overlapping sample sets to create one multi-sample file. For example, when merging file A.vcf.gz containing samples S1, S2 and S3 and file B.vcf.gz containing samples S3 and S4, the output file will contain four samples named S1, S2, S3, 2:S3 and S4.

Note that it is responsibility of the user to ensure that the sample names are unique across all files. If they are not, the program will exit with an error unless the option --force-samples is given. Note that sample names can be also given explicitly using the --print-header and --use-header options.

bcftools norm [OPTIONS] -f ref.fa file.vcf.gz

Left-align and normalize indels, check if REF alleles match the reference, split multiallelic sites into multiple rows; recover multiallelics from multiple rows.

bcftools plugin NAME [OPTIONS] FILE — [PLUGIN OPTIONS]

# List options common to all plugins
bcftools plugin

# List available plugins
bcftools plugin -l

# One can run plugins in several ways
bcftools plugin counts in.vcf
bcftools +counts in.vcf
cat in.vcf | bcftools +counts

# Print usage information of plugin "dosage"
bcftools +dosage -h

# Replace missing genotypes with 0/0
bcftools +missing2ref in.vcf

# Replace missing genotypes with 0|0
bcftools +missing2ref in.vcf -- -p

bcftools query [OPTIONS] file.vcf.gz [file.vcf.gz […]]

Extracts fields from VCF or BCF files and outputs them in user-defined format.

%CHROM          The CHROM column (similarly also other columns, such as POS, ID, QUAL, etc.)
%INFO/TAG       Any tag in the INFO column
%TYPE           Variant type (REF, SNP, MNP, INDEL, OTHER)
%MASK           Indicates presence of the site in other files (with multiple files)
%TAG{INT}       Curly brackets to subscript vectors (0-based)
[]              The brackets loop over all samples
%GT             Genotype (e.g. 0/1)
%TGT            Translated genotype (e.g. C/A)
%IUPACGT        Genotype translated to IUPAC ambiguity codes (e.g. M instead of C/A)
%LINE           Prints the whole line
%SAMPLE         Sample name

bcftools query -f '%CHROM\t%POS\t%REF\t%ALT[\t%SAMPLE=%GT]\n' file.vcf.gz

bcftools reheader [OPTIONS] file.vcf.gz

Modify header of VCF/BCF files, change sample names.

bcftools roh [OPTIONS] file.vcf.gz

A program for detecting runs of homo/autozygosity. Only bi-allelic sites are considered.

Notation:
  D  = Data, AZ = autozygosity, HW = Hardy-Weinberg (non-autozygosity),
  f  = non-ref allele frequency

Emission probabilities:
  oAZ = P_i(D|AZ) = (1-f)*P(D|RR) + f*P(D|AA)
  oHW = P_i(D|HW) = (1-f)^2 * P(D|RR) + f^2 * P(D|AA) + 2*f*(1-f)*P(D|RA)

Transition probabilities:
  tAZ = P(AZ|HW)  .. from HW to AZ, the -a parameter
  tHW = P(HW|AZ)  .. from AZ to HW, the -H parameter
  P(AZ|AZ) = 1 - P(HW|AZ) = 1 - tHW
  P(HW|HW) = 1 - P(AZ|HW) = 1 - tAZ

  ci  = P_i(C)  .. probability of cross-over at site i, from genetic map
  AZi = P_i(AZ) .. probability of site i being AZ/non-AZ, scaled so that AZi+HWi = 1
  HWi = P_i(HW)

  P_{i+1}(AZ) = oAZ * max[(1-tHW) * (1-ci) * AZ{i-1} , tAZ * ci * (1-AZ{i-1})]
  P_{i+1}(HW) = oHW * max[(1-tAZ) * (1-ci) * (1-AZ{i-1}) , tHW * ci * AZ{i-1}]

    bcftools query -f'%CHROM\t%POS\t%REF,%ALT\t%INFO/TAG\n' file.vcf | bgzip -c > freqs.tab.gz

bcftools stats [OPTIONS] A.vcf.gz [B.vcf.gz]

Parses VCF or BCF and produces text file stats which is suitable for machine processing and can be plotted using plot-vcfstats. When two files are given, the program generates separate stats for intersection and the complements.

    tabix -s1 -b2 -e3 file.gz

bcftools view [OPTIONS] file.vcf.gz [REGION […]]

View, subset and filter VCF or BCF files by position and filtering expression. Convert between VCF and BCF. Former bcftools subset.

plot-vcfstats [OPTIONS] file.vchk […]

Script for processing output of bcftools stats. It can merge results from multiple outputs (useful when running the stats for each chromosome separately), plots graphs and creates a PDF presentation.