File: bcftools.1

package info (click to toggle)
bcftools 1.22-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 22,792 kB
sloc: ansic: 72,978; perl: 7,583; sh: 694; python: 595; makefile: 301
file content (6889 lines) | stat: -rw-r--r-- 190,817 bytes
'\" t
.\"     Title: bcftools
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.16.dev
.\"      Date: 2025-05-30
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "BCFTOOLS" "1" "2025-05-30" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
bcftools \- utilities for variant calling and manipulating VCFs and BCFs.
.SH "SYNOPSIS"
.sp
\fBbcftools\fP [\-\-version|\-\-version\-only] [\-\-help] [\fICOMMAND\fP] [\fIOPTIONS\fP]
.SH "DESCRIPTION"
.sp
BCFtools  is  a set of utilities that manipulate variant calls in the Variant
Call Format (VCF) and its binary counterpart BCF. All commands work
transparently with both VCFs and BCFs, both uncompressed and BGZF\-compressed.
.sp
Most commands accept VCF, bgzipped VCF and BCF with filetype detected
automatically even when streaming from a pipe. Indexed VCF and BCF
will work in all situations. Un\-indexed VCF and BCF and streams will
work in most, but not all situations. In general, whenever multiple VCFs are
read simultaneously, they must be indexed and therefore also compressed.
(Note that files with non\-standard index names can be accessed as e.g.
"\f(CRbcftools view \-r X:2928329 file.vcf.gz##idx##non\-standard\-index\-name\fP".)
.sp
BCFtools is designed to work on a stream. It regards an input file "\-" as the
standard input (stdin) and outputs to the standard output (stdout). Several
commands can thus be  combined  with  Unix pipes.
.SS "VERSION"
.sp
This manual page was last updated \fB2025\-05\-30\fP and refers to bcftools git version \fB1.22\fP.
.SS "BCF1"
.sp
The obsolete BCF1 format output by versions of samtools <= 0.1.19 is \fBnot\fP
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.
.sp
.if n .RS 4
.nf
.fam C
    samtools\-0.1.19/bcftools/bcftools view file.bcf1 | bcftools view
.fam
.fi
.if n .RE
.SS "VARIANT CALLING"
.sp
See \fIbcftools call\fP for variant calling from the output of the
\fIsamtools mpileup\fP command. In versions of samtools <= 0.1.19 calling was
done with \fIbcftools view\fP. Users are now required to choose between the old
samtools calling model (\fI\-c/\-\-consensus\-caller\fP) and the new multiallelic
calling model (\fI\-m/\-\-multiallelic\-caller\fP). The multiallelic calling model
is recommended for most tasks.
.SS "FILTERING EXPRESSIONS"
.sp
See \fBEXPRESSIONS\fP
.SH "LIST OF COMMANDS"
.sp
For a full list of available commands, run \fBbcftools\fP without arguments. For a full
list of available options, run \fBbcftools\fP \fICOMMAND\fP without arguments.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBannotate\fP  ..  edit VCF files, add or remove annotations
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBcall\fP      ..  SNP/indel calling (former "view")
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBcnv\fP       ..  Copy Number Variation caller
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBconcat\fP    ..  concatenate VCF/BCF files from the same set of samples
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBconsensus\fP ..  create consensus sequence by applying VCF variants
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBconvert\fP   ..  convert VCF/BCF to other formats and back
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBcsq\fP       ..  haplotype aware consequence caller
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBfilter\fP    ..  filter VCF/BCF files using fixed thresholds
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBgtcheck\fP   ..  check sample concordance, detect sample swaps and contamination
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBhead\fP      ..  view VCF/BCF file headers
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBindex\fP     ..  index VCF/BCF
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBisec\fP      ..  intersections of VCF/BCF files
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBmerge\fP     ..  merge VCF/BCF files files from non\-overlapping sample sets
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBmpileup\fP   ..  multi\-way pileup producing genotype likelihoods
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBnorm\fP      ..  normalize indels
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBplugin\fP    ..  run user\-defined plugin
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBpolysomy\fP  ..  detect contaminations and whole\-chromosome aberrations
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBquery\fP     ..  transform VCF/BCF into user\-defined formats
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBreheader\fP  ..  modify VCF/BCF header, change sample names
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBroh\fP       ..  identify runs of homo/auto\-zygosity
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBsort\fP      ..  sort VCF/BCF files
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBstats\fP     ..  produce VCF/BCF stats (former vcfcheck)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBview\fP      ..  subset, filter and convert VCF and BCF files
.RE
.SH "LIST OF SCRIPTS"
.sp
Some helper scripts are bundled with the bcftools code.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBgff2gff\fP  .. converts a GFF file to the format required by \fBbcftools csq\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBplot\-vcfstats\fP  .. plots the output of \fBbcftools stats\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBroh\-viz\fP .. creates HTML/JavaScript visualization of \fBbcftools roh\fP
.RE
.SH "COMMANDS AND OPTIONS"
.SS "Common Options"
.sp
The following options are common to many bcftools commands. See usage for
specific commands to see if they apply.
.sp
\fIFILE\fP
.RS 4
Files can be both VCF or BCF, uncompressed or BGZF\-compressed. The file "\-"
is interpreted as standard input. Some tools may require tabix\- or
CSI\-indexed files.
.RE
.sp
\fB\-c, \-\-collapse\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIsome\fP|\fInone\fP|\fIid\fP
.RS 4
Controls  how to treat records with duplicate positions and defines compatible
records across multiple input files. Here by "compatible" we mean records which
should be considered as identical by the tools. For example, when performing
line intersections, the desire may be to consider as identical all sites with
matching positions (\fBbcftools isec \-c\fP \fIall\fP), or only sites with  matching variant
type (\fBbcftools isec \-c\fP \fIsnps\fP\~ \fB\-c\fP \fIindels\fP), or only sites with all alleles
identical (\fBbcftools isec \-c\fP \fInone\fP).
.sp
\fInone\fP
.RS 4
only records with identical REF and ALT alleles are compatible
.RE
.sp
\fIsome\fP
.RS 4
only records where some subset of ALT alleles match are compatible
.RE
.sp
\fIall\fP
.RS 4
all records are compatible, regardless of whether the ALT alleles
match or not. In the case of records with the same position, only
the first will be considered and appear on output.
.RE
.sp
\fIsnps\fP
.RS 4
any SNP records are compatible, regardless of whether the ALT
alleles match or not. For duplicate positions, only the first SNP
record will be considered and appear on output.
.RE
.sp
\fIindels\fP
.RS 4
all  indel records are compatible, regardless of whether the REF
and ALT alleles match or not. For duplicate positions, only the
first indel record will be considered and appear on output.
.RE
.sp
\fIboth\fP
.RS 4
abbreviation of "\fB\-c\fP \fIindels\fP\~ \fB\-c\fP \fIsnps\fP"
.RE
.sp
\fIid\fP
.RS 4
only records with identical ID column are compatible.
.RE
.RE
.sp
\fB\-f, \-\-apply\-filters\fP \fILIST\fP
.RS 4
Skip sites where FILTER column does not contain any of the strings listed
in \fILIST\fP. For example, to include only sites which have no filters set,
use \fB\-f\fP \fI.,PASS\fP.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
Do not append version and command line information to the output VCF header.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
When output consists of a single stream, write it to \fIFILE\fP rather than
to standard output, where it is written by default.
The file type is determined automatically from the file name suffix and in
case a conflicting \fB\-O\fP option is given, the file name suffix takes precedence.
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
Output compressed BCF (\fIb\fP), uncompressed BCF (\fIu\fP), compressed VCF (\fIz\fP), uncompressed VCF (\fIv\fP).
Use the \-Ou option when piping between bcftools subcommands to speed up
performance by removing unnecessary compression/decompression and
VCF\(<-\(->BCF conversion.
\~
The compression level of the compressed formats (\fIb\fP and \fIz\fP) can be set by
by appending a number between 0\-9.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:beg\-end\fP|\fIchr:beg\-\fP[,...]
.RS 4
Comma\-separated list of regions, see also \fB\-R, \-\-regions\-file\fP. Overlapping
records are matched even when the starting coordinate is outside of the
region, unlike the \fB\-t/\-T\fP options where only the POS coordinate is checked.
Note that \fB\-r\fP cannot be used in combination with \fB\-R\fP.
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIFILE\fP
.RS 4
Regions can be specified either on command line or in a VCF, BED, or
tab\-delimited file (the default). The columns of the tab\-delimited file
can contain either positions (two\-column format: CHROM, POS) or intervals
(three\-column format: CHROM, BEG, END), but not both. Positions are 1\-based
and inclusive. The columns of the tab\-delimited BED file are also
CHROM, POS and END (trailing columns are ignored), but coordinates
are 0\-based, half\-open.  To indicate that a file be treated as BED rather
than the 1\-based tab\-delimited file, the file must have the ".bed" or
".bed.gz" suffix (case\-insensitive). Uncompressed files are stored in
memory, while bgzip\-compressed and tabix\-indexed region files are streamed.
Note that sequence names must match exactly, "chr20" is not the same as
"20".  Also note that chromosome ordering in \fIFILE\fP will be respected,
the VCF will be processed in the order in which chromosomes first appear
in \fIFILE\fP. However, within chromosomes, the VCF will always be
processed in ascending genomic coordinate order no matter what order they
appear in \fIFILE\fP. Note that overlapping regions in \fIFILE\fP can result in
duplicated out of order positions in the output.
This option requires indexed VCF/BCF files. Note that \fB\-R\fP cannot be used
in combination with \fB\-r\fP.
.RE
.sp
\fB\-\-regions\-overlap\fP \fIpos\fP|\fIrecord\fP|\fIvariant\fP|\fI0\fP|\fI1\fP|\fI2\fP
.RS 4
This option controls how overlapping records are determined:
set to \fBpos\fP or \fB0\fP if the VCF record has to have POS inside a region
(this corresponds to the default behavior of \fB\-t/\-T\fP);
set to \fBrecord\fP or \fB1\fP if also overlapping records with POS outside a region
should be included (this is the default behavior of \fB\-r/\-R\fP, and includes indels
with POS at the end of a region, which are technically outside the region); or set
to \fBvariant\fP or \fB2\fP to include only true overlapping variation (compare
the full VCF representation "\f(CRTA>T\-\fP" vs the true sequence variation "\f(CRA>\-\fP").
.RE
.sp
\fB\-s, \-\-samples\fP [^]\fILIST\fP
.RS 4
Comma\-separated list of samples to include or exclude if prefixed
with "^." (Note that when multiple samples are to be excluded,
the "^" prefix is still present only once, e.g.  "^SAMPLE1,SAMPLE2".)
The sample order is updated to reflect that given on the command line.
Note that in general tags such as INFO/AC, INFO/AN, etc are not updated
to correspond to the subset samples. \fBbcftools view\fP is the
exception where some tags will be updated (unless the \fB\-I, \-\-no\-update\fP
option is used; see \fBbcftools view\fP documentation). To use updated
tags for the subset in another command one can pipe from \fBview\fP into
that command. For example:
.RE
.sp
.if n .RS 4
.nf
.fam C
    bcftools view \-Ou \-s sample1,sample2 file.vcf | bcftools query \-f %INFO/AC\(rst%INFO/AN\(rsn
.fam
.fi
.if n .RE
.sp
\fB\-S, \-\-samples\-file\fP [^]\fIFILE\fP
.RS 4
File of sample names to include or exclude if prefixed with "^".
One sample per line. See also the note above for the \fB\-s, \-\-samples\fP
option.
The sample order is updated to reflect that given in the input file.
The command \fBbcftools call\fP accepts an optional second
column indicating ploidy (0, 1 or 2) or sex (as defined by
\fB\-\-ploidy\fP, for example "F" or "M"), for example:
.RE
.sp
.if n .RS 4
.nf
.fam C
    sample1    1
    sample2    2
    sample3    2
.fam
.fi
.if n .RE
.sp
or
.sp
.if n .RS 4
.nf
.fam C
    sample1    M
    sample2    F
    sample3    F
.fam
.fi
.if n .RE
.sp
If the second column is not present, the sex "F" is assumed.
With \fBbcftools call \-C\fP \fItrio\fP, PED file is expected.
The program ignores the first column and the last indicates sex (1=male, 2=female), for example:
.sp
.if n .RS 4
.nf
.fam C
    ignored_column  daughterA fatherA  motherA  2
    ignored_column  sonB      fatherB  motherB  1
.fam
.fi
.if n .RE
.sp
\fB\-t, \-\-targets\fP [^]\fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
Similar as \fB\-r, \-\-regions\fP, but the next position is accessed by streaming the
whole VCF/BCF rather than using the tbi/csi index. Both \fB\-r\fP and \fB\-t\fP options
can be applied simultaneously: \fB\-r\fP  uses  the index  to  jump  to  a  region
and \fB\-t\fP discards positions which are not in the targets. Unlike \fB\-r\fP, targets
can be prefixed with "^" to request logical complement. For example, "^X,Y,MT"
indicates that sequences X, Y and MT should be skipped.
Yet another difference between the \fB\-t/\-T\fP and \fB\-r/\-R\fP is that \fB\-r/\-R\fP checks for
proper overlaps and considers both POS and the end position of an indel, while \fB\-t/\-T\fP
considers the POS coordinate only (by default; see also \fB\-\-regions\-overlap\fP and \fB\-\-targets\-overlap\fP).
Note that \fB\-t\fP cannot be used in combination with \fB\-T\fP.
.RE
.sp
\fB\-T, \-\-targets\-file\fP [^]\fIFILE\fP
.RS 4
Same \fB\-t, \-\-targets\fP, but reads regions from a file. Note that \fB\-T\fP
cannot be used in combination with \fB\-t\fP.
.sp
With the \fBcall \-C\fP \fIalleles\fP command, third column of the targets file must
be comma\-separated list of alleles, starting with the reference allele.
Note that the file must be compressed and indexed.
Such a file can be easily created from a VCF using:
.RE
.sp
.if n .RS 4
.nf
.fam C
    bcftools query \-f\*(Aq%CHROM\(rst%POS\(rst%REF,%ALT\(rsn\*(Aq file.vcf | bgzip \-c > als.tsv.gz && tabix \-s1 \-b2 \-e2 als.tsv.gz
.fam
.fi
.if n .RE
.sp
\fB\-\-targets\-overlap\fP \fIpos\fP|\fIrecord\fP|\fIvariant\fP|\fI0\fP|\fI1\fP|\fI2\fP
.RS 4
Same as \fB\-\-regions\-overlap\fP but for \fB\-t/\-T\fP.
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
Use multithreading with \fIINT\fP worker threads. The option is currently used only for the compression of the
output stream, only when \fI\-\-output\-type\fP is \fIb\fP or \fIz\fP. Default: 0.
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
Verbosity level. Values bigger than 3 are passed to the underlying HTSlib library so that network issues
and other problems occurring at the library level can be investigated.
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output files. \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format. Defaults to
CSI unless specified otherwise. Can be used only for compressed
BCF and VCF output.
.RE
.SS "bcftools annotate \fI[OPTIONS]\fP \fIFILE\fP"
.sp
Add or remove annotations.
.sp
\fB\-a, \-\-annotations\fP \fIfile\fP
.RS 4
Bgzip\-compressed and tabix\-indexed file with annotations. The file
can be VCF, BED, or a tab\-delimited file with mandatory columns CHROM, POS
(or, alternatively, FROM and TO), optional columns REF and ALT, and arbitrary
number of annotation columns. BED files are expected to have
the ".bed" or ".bed.gz" suffix (case\-insensitive), otherwise a tab\-delimited file is assumed.
Note that in case of tab\-delimited file, the coordinates POS, FROM and TO are
one\-based and inclusive.  When REF and ALT are present, only matching VCF
records will be annotated. If the END coordinate is present in the annotation file
and given on command line as "\f(CR\-c ~INFO/END\fP", then VCF records will be matched also by the INFO/END coordinate.
If ID is present in the annotation file and given as "\f(CR\-c ~ID\fP", then VCF records will be matched
also by the ID column.
\~
.br
\~
.br
When multiple ALT alleles are present in the annotation file (given as
comma\-separated list of alleles), at least one must match one of the
alleles in the corresponding VCF record. Similarly, at least one
alternate allele from a multi\-allelic VCF record must be present in the
annotation file.
\~
.br
\~
.br
Missing values can be added by providing "." in place of actual value
and using the missing value modifier with \fB\-c\fP, such as ".TAG".
\~
.br
\~
.br
Note that flag types, such as "INFO/FLAG", can be annotated by including
a field with the value "1" to set the flag, "0" to remove it, or "." to
keep existing flags.
See also \fB\-c, \-\-columns\fP and \fB\-h, \-\-header\-lines\fP.
.RE
.sp
.if n .RS 4
.nf
.fam C
    # Sample annotation file with columns CHROM, POS, STRING_TAG, NUMERIC_TAG
    1  752566  SomeString      5
    1  798959  SomeOtherString 6
.fam
.fi
.if n .RE
.sp
\fB\-c, \-\-columns\fP \fIlist\fP
.RS 4
Comma\-separated list of columns or tags to carry over from the annotation file
(see also \fB\-a, \-\-annotations\fP). If the annotation file is not a VCF/BCF,
\fIlist\fP describes the columns of the annotation file and must include CHROM,
POS (or, alternatively, FROM,TO or BEG,END), and optionally REF and ALT. Unused
columns which should be ignored can be indicated by "\-".
\~
.br
\~
.br
If the annotation file is a VCF/BCF, only the edited columns/tags must be present and their
order does not matter. The columns ID, QUAL, FILTER, INFO and FORMAT
can be edited, where INFO tags can be written both as "INFO/TAG" or simply "TAG",
and FORMAT tags can be written as "FORMAT/TAG" or "FMT/TAG".
The imported VCF annotations can be renamed as "DST_TAG:=SRC_TAG" or "FMT/DST_TAG:=FMT/SRC_TAG".
\~
.br
\~
.br
To carry over all INFO annotations, use "INFO". To add all INFO annotations except
"TAG", use "^INFO/TAG". By default, existing values are replaced.
\~
.br
\~
.br
By default, existing tags are overwritten unless the source value is a missing value (i.e. ".").
If also missing values should be carried over (and overwrite existing tags), use ".TAG" instead of "TAG".
To add annotations without overwriting existing values (that is, to add tags that are absent or
to add values to existing tags with missing values), use "+TAG" instead of "TAG". These can be combined,
for example ".+TAG" can be used to add TAG even if the source value is missing but only if TAG does not
exist in the target file; existing tags will not be overwritten.
To append to existing values (rather than replacing or leaving untouched), use "=TAG"
(instead of "TAG" or "+TAG").
To replace only existing values without modifying missing annotations, use "\-TAG".
As a special case of this, if position needs to be replaced, mark the column with the new coordinate as "\-POS".
(Note that in previous releases this used to be "~POS", now deprecated.)
\~
.br
\~
.br
To match the record also by ID or INFO/END, in addition to REF and ALT, use "~ID" or "~INFO/END".
Note that this works only for ID and POS, for other fields see the description of \fB\-i\fP below.
\~
.br
\~
.br
If the annotation file is not a VCF/BCF, all new annotations must be
defined via \fB\-h, \-\-header\-lines\fP.
\~
.br
\~
.br
See also the \fB\-l, \-\-merge\-logic\fP option.
\~
.br
\~
.br
\fBSummary of \f(CR\-c, \-\-columns\fP:\fP
.RE
.sp
.if n .RS 4
.nf
.fam C
    CHROM,POS,TAG       .. match by chromosome and position, transfer annotation from TAG
    CHROM,POS,\-,TAG     .. same as above, but ignore the third column of the annotation file
    CHROM,BEG,END,TAG   .. match by region (BEG,END are synonymous to FROM,TO)
    CHROM,POS,REF,ALT   .. match by CHROM, POS, REF and ALT

    DST_TAG:=SRC_TAG    .. transfer the SRC_TAG using the new name DST_TAG
    INFO                .. transfer all INFO annotations
    ^INFO/TAG           .. transfer all INFO annotations except "TAG"

    TAG       .. add or overwrite existing target value if source is not "." and skip otherwise
    +TAG      .. add or overwrite existing target value only if it is "."
    .TAG      .. add or overwrite existing target value even if source is "."
    .+TAG     .. add new but never overwrite existing tag, regardless of its value; can transfer "." if target does not exist
    \-TAG      .. overwrite existing value, never add new if target does not exist
    =TAG      .. do not overwrite but append value to existing tags

    ~FIELD    .. use this column to match lines with \-i/\-e expression (see the description of \-i below)
    ~ID       .. in addition to CHROM,POS,REF,ALT match by also ID
    ~INFO/END .. in addition to CHROM,POS,REF,ALT match by also INFO/END
.fam
.fi
.if n .RE
.sp
\fB\-C, \-\-columns\-file\fP \fIfile\fP
.RS 4
Read the list of columns from a file (normally given via the \fB\-c, \-\-columns\fP option).
"\-" to skip a column of the annotation file.
One column name per row, an additional space\- or tab\-separated field can
be present to indicate the merge logic (normally given via the \fB\-l, \-\-merge\-logic\fP option).
This is useful when many annotations are added at once.
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP and the extension described in \fB\-i, \-\-include\fP below.
.RE
.sp
\fB\-\-force\fP
.RS 4
continue even when parsing errors, such as undefined tags, are encountered. Note
this can be an unsafe operation and can result in corrupted BCF files. If this
option is used, make sure to sanity check the result thoroughly.
.RE
.sp
\fB\-h, \-\-header\-lines\fP \fIfile\fP
.RS 4
Lines to append to the VCF header, see also \fB\-c, \-\-columns\fP and \fB\-a, \-\-annotations\fP. For example:
.RE
.sp
.if n .RS 4
.nf
.fam C
    ##INFO=<ID=NUMERIC_TAG,Number=1,Type=Integer,Description="Example header line">
    ##INFO=<ID=STRING_TAG,Number=1,Type=String,Description="Yet another header line">
.fam
.fi
.if n .RE
.sp
\fB\-I, \-\-set\-id\fP [+]\fIFORMAT\fP
.RS 4
assign ID on the fly. The format is the same as in the \fBquery\fP
command (see below).  By default all existing IDs are replaced. If the
format string is preceded by "+", only missing IDs will be set. For example,
one can use
.RE
.sp
.if n .RS 4
.nf
.fam C
    bcftools annotate \-\-set\-id +\*(Aq%CHROM\(rs_%POS\(rs_%REF\(rs_%FIRST_ALT\*(Aq file.vcf
.fam
.fi
.if n .RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
\~
.br
\~
.br
Additionally, the command \fBbcftools annotate\fP supports expressions updated from the annotation
file dynamically for each record:
.RE
.sp
.if n .RS 4
.nf
.fam C
    # The field \*(AqSTR\*(Aq from the \-a file is required to match INFO/TAG in VCF. In the first example
    # the alleles REF,ALT must match, in the second example they are ignored. The option \-k is required
    # to output also records that are not annotated. The third example shows the same concept with
    # a numerical expression.
    bcftools annotate \-a annots.tsv.gz \-c CHROM,POS,REF,ALT,SCORE,~STR \-i\*(AqTAG={STR}\*(Aq \-k input.vcf
    bcftools annotate \-a annots.tsv.gz \-c CHROM,POS,\-,\-,SCORE,~STR     \-i\*(AqTAG={STR}\*(Aq \-k input.vcf
    bcftools annotate \-a annots.tsv.gz \-c CHROM,POS,\-,\-,SCORE,~INT     \-i\*(AqTAG>{INT}\*(Aq \-k input.vcf
.fam
.fi
.if n .RE
.sp
\fB\-k, \-\-keep\-sites\fP
.RS 4
keep sites which do not pass \fB\-i\fP and \fB\-e\fP expressions instead of discarding them
.RE
.sp
\fB\-l, \-\-merge\-logic\fP \fItag:first\fP|\fIappend\fP|\fIappend\-missing\fP|\fIunique\fP|\fIsum\fP|\fIavg\fP|\fImin\fP|\fImax\fP[,...]
.RS 4
When multiple regions overlap a single record, this option defines how to treat multiple
annotation values when setting \fItag\fP in the destination file: use the first encountered value ignoring
the rest (\fIfirst\fP); append allowing duplicates (\fIappend\fP); append even if the appended value is missing,
i.e. is a dot (\fIappend\-missing\fP); append discarding duplicate values (\fIunique\fP);
sum the values (\fIsum\fP, numeric fields only); average the values (\fIavg\fP); use the minimum value (\fImin\fP) or
the maximum (\fImax\fP).
+
Note that this option is intended for use with BED or TAB\-delimited annotation files only. Moreover,
it is effective only when either \fIREF\fP and \fIALT\fP or \fIBEG\fP and \fIEND\fP \fB\-\-columns\fP are present .
+
Multiple rules can be given either as a comma\-separated list or giving the option multiple times.
This is an experimental feature.
.RE
.sp
\fB\-m, \-\-mark\-sites\fP \fITAG\fP
.RS 4
annotate sites which are present ("+") or absent ("\-") in the \fB\-a\fP file with a new INFO/TAG flag
.RE
.sp
\fB\-\-min\-overlap\fP \fIANN\fP:\*(AqVCF\*(Aq
.RS 4
minimum overlap required as a fraction of the variant in the annotation \fB\-a\fP file (\fIANN\fP), in the
target VCF file (\fI:VCF\fP), or both for reciprocal overlap (\fIANN:VCF\fP).
By default overlaps of arbitrary length are sufficient.
The option can be used only with the tab\-delimited annotation \fB\-a\fP file and with \fIBEG\fP and \fIEND\fP
columns present.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-pair\-logic\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIsome\fP|\fIexact\fP|\fIid\fP
.RS 4
Controls how to match records from the annotation file to the target VCF.
Effective only when \fB\-a\fP is a VCF or BCF. The option replaces the former
uninuitive \fB\-\-collapse\fP.
See \fBCommon Options\fP for more.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-rename\-annots\fP \fIfile\fP
.RS 4
rename annotations according to the map in \fIfile\fP, with
"old_name new_name\(rsn" pairs separated by whitespaces, each on a separate
line. The old name must be prefixed with the annotation type:
INFO, FORMAT, or FILTER.
.RE
.sp
\fB\-\-rename\-chrs\fP \fIfile\fP
.RS 4
rename chromosomes according to the map in \fIfile\fP, with
"old_name new_name\(rsn" pairs separated by whitespaces, each on a separate
line.
.RE
.sp
\fB\-s, \-\-samples\fP [^]\fILIST\fP
.RS 4
subset of samples to annotate, see also \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
subset of samples to annotate. If the samples are named differently in the
target VCF and the \fB\-a, \-\-annotations\fP VCF, the name mapping can be
given as "src_name dst_name\(rsn", separated by whitespaces, each pair on a
separate line.
.RE
.sp
\fB\-\-single\-overlaps\fP
.RS 4
use this option to keep memory requirements low with very large annotation
files. Note, however, that this comes at a cost, only single overlapping intervals
are considered in this mode. This was the default mode until the commit
af6f0c9 (Feb 24 2019).
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-x, \-\-remove\fP \fIlist\fP
.RS 4
List of annotations to remove. Use "FILTER" to remove all filters or
"FILTER/SomeFilter" to remove a specific filter. Similarly, "INFO" can
be used to remove all INFO tags and "FORMAT" to remove all FORMAT tags
except GT. To remove all INFO tags except "FOO" and "BAR", use
"^INFO/FOO,INFO/BAR" (and similarly for FORMAT and FILTER).
"INFO" can be abbreviated to "INF" and "FORMAT" to "FMT".
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.sp
\fBExamples:\fP
.sp
.if n .RS 4
.nf
.fam C
    # Remove three fields
    bcftools annotate \-x ID,INFO/DP,FORMAT/DP file.vcf.gz

    # Remove all INFO fields and all FORMAT fields except for GT and PL
    bcftools annotate \-x INFO,^FORMAT/GT,FORMAT/PL file.vcf

    # 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 with six columns (the fifth is ignored),
    # first indexing with tabix. The coordinates are 1\-based.
    tabix \-s1 \-b2 \-e2 annots.tab.gz
    bcftools annotate \-a annots.tab.gz \-h annots.hdr \-c CHROM,POS,REF,ALT,\-,TAG file.vcf

    # Annotate from a tab\-delimited file with regions (1\-based coordinates, inclusive)
    tabix \-s1 \-b2 \-e3 annots.tab.gz
    bcftools annotate \-a annots.tab.gz \-h annots.hdr \-c CHROM,FROM,TO,TAG input.vcf

    # Annotate from a bed file (0\-based coordinates, half\-closed, half\-open intervals)
    bcftools annotate \-a annots.bed.gz \-h annots.hdr \-c CHROM,FROM,TO,TAG input.vcf

    # Transfer the INFO/END tag, matching by POS,REF,ALT and ID. This example assumes
    # that INFO/END is already present in the VCF header.
    bcftools annotate \-a annots.tab.gz  \-c CHROM,POS,~ID,REF,ALT,INFO/END input.vcf

    # For (many) more examples see http://samtools.github.io/bcftools/howtos/annotate.html
.fam
.fi
.if n .RE
.SS "bcftools call \fI[OPTIONS]\fP \fIFILE\fP"
.sp
This command replaces the former \fBbcftools view\fP caller. Some of the original
functionality has been temporarily lost in the process of transition under
.URL "http://github.com/samtools/htslib" "htslib" ","
but will be added back on popular
demand. The original calling model can be invoked with the \fB\-c\fP option.
.SS "File format options:"
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-ploidy\fP \fIASSEMBLY\fP[\fI?\fP]
.RS 4
predefined ploidy, use \fIlist\fP (or any other unused word) to print a list
of all predefined assemblies. Append a question mark to print the actual
definition. See also \fB\-\-ploidy\-file\fP.
.RE
.sp
\fB\-\-ploidy\-file\fP \fIFILE\fP
.RS 4
ploidy definition given as a space/tab\-delimited list of
CHROM, FROM, TO, SEX, PLOIDY. The SEX codes are arbitrary and
correspond to the ones used by \fB\-\-samples\-file\fP.
The default ploidy can be given using the starred records (see
below), unlisted regions have ploidy 2. The default ploidy definition is
.RE
.sp
.if n .RS 4
.nf
.fam C
    X 1 60000 M 1
    X 2699521 154931043 M 1
    Y 1 59373566 M 1
    Y 1 59373566 F 0
    MT 1 16569 M 1
    MT 1 16569 F 1
    *  * *     M 2
    *  * *     F 2
.fam
.fi
.if n .RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "Input/output options:"
.sp
\fB\-A, \-\-keep\-alts\fP
.RS 4
output all alternate alleles present in the alignments even if they do not
appear in any of the genotypes
.RE
.sp
\fB\-\fP*\fB, \-\-keep\-unseen\-allele\fP
.RS 4
keep the unobserved allele <*> or <NON_REF>, useful mainly for gVCF output
.RE
.sp
\fB\-f, \-\-format\-fields\fP \fIlist\fP
.RS 4
comma\-separated list of FORMAT fields to output for each sample. Currently
GQ and GP fields are supported. For convenience, the fields can be given
as lower case letters. Prefixed with "^" indicates a request for tag
removal of auxiliary tags useful only for calling.
.RE
.sp
\fB\-F, \-\-prior\-freqs\fP \fIAN\fP,\fIAC\fP
.RS 4
take advantage of prior knowledge of population allele frequencies. The
workflow looks like this:
.RE
.sp
.if n .RS 4
.nf
.fam C
    # Extract AN,AC values from an existing VCF, such 1000Genomes
    bcftools query \-f\*(Aq%CHROM\(rst%POS\(rst%REF\(rst%ALT\(rst%AN\(rst%AC\(rsn\*(Aq 1000Genomes.bcf | bgzip \-c > AFs.tab.gz

    # If the tags AN,AC are not already present, use the +fill\-tags plugin
    bcftools +fill\-tags 1000Genomes.bcf | bcftools query \-f\*(Aq%CHROM\(rst%POS\(rst%REF\(rst%ALT\(rst%AN\(rst%AC\(rsn\*(Aq | bgzip \-c > AFs.tab.gz
    tabix \-s1 \-b2 \-e2 AFs.tab.gz

    # Create a VCF header description, here we name the tags REF_AN,REF_AC
    cat AFs.hdr
    ##INFO=<ID=REF_AN,Number=1,Type=Integer,Description="Total number of alleles in reference genotypes">
    ##INFO=<ID=REF_AC,Number=A,Type=Integer,Description="Allele count in reference genotypes for each ALT allele">

    # Now before calling, stream the raw mpileup output through `bcftools annotate` to add the frequencies
    bcftools mpileup [...] \-Ou | bcftools annotate \-a AFs.tab.gz \-h AFs.hdr \-c CHROM,POS,REF,ALT,REF_AN,REF_AC \-Ou | bcftools call \-mv \-F REF_AN,REF_AC [...]
.fam
.fi
.if n .RE
.sp
\fB\-G, \-\-group\-samples\fP \fIFILE\fP|\fI\-\fP
.RS 4
by default, all samples are assumed to come from a single population. This option groups samples
into populations and apply the HWE assumption within but not across the populations. \fIFILE\fP is a tab\-delimited
text file with sample names in the first column and group names in the second column. If \fI\-\fP is
given instead, no HWE assumption is made at all and single\-sample calling is performed. (Note that
in low coverage data this inflates the rate of false positives.) The \fB\-G\fP option requires the presence of
per\-sample FORMAT/QS or FORMAT/AD tag generated with \fBbcftools mpileup \-a QS\fP (or \fB\-a AD\fP).
.RE
.sp
\fB\-g, \-\-gvcf\fP \fIINT\fP[,...]
.RS 4
output gVCF blocks of homozygous REF calls, with depth (DP) ranges
specified by the list of integers. For example, passing \fI5,15\fP will
group sites into two types of gVCF blocks, the first with minimum
per\-sample DP from the interval [5,15) and the latter with minimum
depth 15 or more. In this example, sites with minimum per\-sample
depth less than 5 will be printed as separate records, outside of
gVCF blocks.
.RE
.sp
\fB\-i, \-\-insert\-missed\fP \fIINT\fP
.RS 4
output also sites missed by mpileup but present in \fB\-T, \-\-targets\-file\fP.
.RE
.sp
\fB\-M, \-\-keep\-masked\-ref\fP
.RS 4
output sites where REF allele is N
.RE
.sp
\fB\-V, \-\-skip\-variants\fP \fIsnps\fP|\fIindels\fP
.RS 4
skip indel/SNP sites
.RE
.sp
\fB\-v, \-\-variants\-only\fP
.RS 4
output variant sites only
.RE
.SS "Consensus/variant calling options:"
.sp
\fB\-c, \-\-consensus\-caller\fP
.RS 4
the original \fBsamtools\fP/\fBbcftools\fP calling method (conflicts with \fB\-m\fP)
.RE
.sp
\fB\-C, \-\-constrain\fP \fIalleles\fP|\fItrio\fP
.RS 4
.sp
\fIalleles\fP
.RS 4
call genotypes given alleles. See also \fB\-T, \-\-targets\-file\fP.
.RE
.sp
\fItrio\fP
.RS 4
call genotypes given the father\-mother\-child constraint. See also
\fB\-s, \-\-samples\fP and \fB\-n, \-\-novel\-rate\fP.
.RE
.RE
.sp
\fB\-m, \-\-multiallelic\-caller\fP
.RS 4
alternative model for multiallelic and rare\-variant calling designed to
overcome known limitations in \fB\-c\fP calling model (conflicts with \fB\-c\fP)
.RE
.sp
\fB\-n, \-\-novel\-rate\fP \fIfloat\fP[,...]
.RS 4
likelihood of novel mutation for constrained \fB\-C\fP \fItrio\fP calling. The trio
genotype calling maximizes likelihood of a particular combination of
genotypes for father, mother and the child
P(F=i,M=j,C=k) = P(unconstrained) * Pn + P(constrained) * (1\-Pn).
By providing three values, the mutation rate Pn is set explicitly for SNPs,
deletions and insertions, respectively.  If two values are given, the first
is interpreted as the mutation rate of SNPs and the second is used to
calculate the mutation rate of indels according to their length as
Pn=\fIfloat\fP*exp(\-a\-b*len), where a=22.8689, b=0.2994 for insertions and
a=21.9313, b=0.2856 for deletions [pubmed:23975140].  If only one value is
given, the same mutation rate Pn is used for SNPs and indels.
.RE
.sp
\fB\-p, \-\-pval\-threshold\fP \fIfloat\fP
.RS 4
with \fB\-c\fP, accept variant if P(ref|D) < \fIfloat\fP.
.RE
.sp
\fB\-P, \-\-prior\fP \fIfloat\fP
.RS 4
expected substitution rate, or 0 to disable the prior. Only with \fB\-m\fP.
.RE
.sp
\fB\-t, \-\-targets\fP \fIfile\fP|\fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-X, \-\-chromosome\-X\fP
.RS 4
haploid output for male samples (requires PED file with \fB\-s\fP)
.RE
.sp
\fB\-Y, \-\-chromosome\-Y\fP
.RS 4
haploid output for males and skips females (requires PED file with \fB\-s\fP)
.RE
.SS "bcftools cnv \fI[OPTIONS]\fP \fIFILE\fP"
.sp
Copy number variation caller, requires a VCF annotated with the Illumina\(cqs
B\-allele frequency (BAF) and Log R Ratio intensity (LRR) values. The HMM
considers the following copy number states: CN 2 (normal), 1 (single\-copy
loss), 0 (complete loss), 3 (single\-copy gain).
.SS "General Options:"
.sp
\fB\-c, \-\-control\-sample\fP \fIstring\fP
.RS 4
optional control sample name. If given, pairwise calling is performed
and the \fB\-P\fP  option can be used
.RE
.sp
\fB\-f, \-\-AF\-file\fP \fIfile\fP
.RS 4
read allele frequencies from  a tab\-delimited file with the columns CHR,POS,REF,ALT,AF
.RE
.sp
\fB\-o, \-\-output\-dir\fP \fIpath\fP
.RS 4
output directory
.RE
.sp
\fB\-p, \-\-plot\-threshold\fP \fIfloat\fP
.RS 4
call \fBmatplotlib\fP to produce plots for chromosomes with quality at least \fIfloat\fP,
useful for visual inspection of the calls. With \fB\-p 0\fP, plots for all chromosomes will be
generated. If not given, a \fBmatplotlib\fP script will be created but not called.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-query\-sample\fP \fIstring\fP
.RS 4
query sample name
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "HMM Options:"
.sp
\fB\-a, \-\-aberrant\fP \fIfloat\fP[,\fIfloat\fP]
.RS 4
fraction of aberrant cells in query and control. The hallmark of
duplications and contaminations is the BAF value of heterozygous markers
which is dependent on the fraction of aberrant cells. Sensitivity to
smaller fractions of cells can be increased by setting \fB\-a\fP to a lower value. Note
however, that this comes at the cost of increased false discovery rate.
.RE
.sp
\fB\-b, \-\-BAF\-weight\fP \fIfloat\fP
.RS 4
relative contribution from BAF
.RE
.sp
\fB\-d, \-\-BAF\-dev\fP \fIfloat\fP[,\fIfloat\fP]
.RS 4
expected BAF deviation in query and control, i.e. the noise observed
in the data.
.RE
.sp
\fB\-e, \-\-err\-prob\fP \fIfloat\fP
.RS 4
uniform error probability
.RE
.sp
\fB\-l, \-\-LRR\-weight\fP \fIfloat\fP
.RS 4
relative contribution from LRR. With noisy data, this option can have big effect
on the number of calls produced. In truly random noise (such as in simulated data),
the value should be set high (1.0), but in the presence of systematic noise
when LRR are not informative, lower values result in cleaner calls (0.2).
.RE
.sp
\fB\-L, \-\-LRR\-smooth\-win\fP \fIint\fP
.RS 4
reduce LRR noise by applying moving average given this window size
.RE
.sp
\fB\-O, \-\-optimize\fP \fIfloat\fP
.RS 4
iteratively estimate the fraction of aberrant cells, down to the given fraction.
Lowering this value from the default 1.0 to say, 0.3, can help discover more
events but also increases noise
.RE
.sp
\fB\-P, \-\-same\-prob\fP \fIfloat\fP
.RS 4
the prior probability of the query and the control sample being the same.
Setting to 0 calls both independently, setting to 1 forces the same copy
number state in both.
.RE
.sp
\fB\-x, \-\-xy\-prob\fP \fIfloat\fP
.RS 4
the HMM probability of transition to another copy number state. Increasing this
values leads to smaller and more frequent calls.
.RE
.SS "bcftools concat \fI[OPTIONS]\fP \fIFILE1\fP \fIFILE2\fP [...]"
.sp
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 \fB\-a, \-\-allow\-overlaps\fP option is specified. With the \-\-naive option, the files
are concatenated without being recompressed, which is very fast..
.sp
\fB\-a, \-\-allow\-overlaps\fP
.RS 4
First coordinate of the next file can precede last record of the current file.
.RE
.sp
\fB\-c, \-\-compact\-PS\fP
.RS 4
Do not output PS tag at each site, only at the start of a new phase set block.
.RE
.sp
\fB\-d, \-\-rm\-dups\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIexact\fP
.RS 4
Output duplicate records of specified type present in multiple files only once.
Note that records duplicate within one file are not removed with this option,
for that use \fBbcftools norm \-d\fP instead.
.br
In other words, the default behavior of the program is similar to unix "\f(CRcat\fP" in
that when two files contain a record with the same position, that position will appear
twice on output. With \fB\-d\fP, every line that finds a matching record in another
file will be printed only once.
.br
Requires \fB\-a, \-\-allow\-overlaps\fP.
.RE
.sp
\fB\-D, \-\-remove\-duplicates\fP
.RS 4
Alias for \fB\-d exact\fP
.RE
.sp
\fB\-f, \-\-file\-list\fP \fIFILE\fP
.RS 4
Read file names from \fIFILE\fP, one file name per line.
.RE
.sp
\fB\-l, \-\-ligate\fP
.RS 4
Ligate phased VCFs by matching phase at overlapping haplotypes.
Note that the option is intended for VCFs with perfect overlap, sites
in overlapping regions present in one but missing in the other are dropped.
.RE
.sp
\fB\-\-ligate\-force\fP
.RS 4
Keep all sites and ligate even non\-overlapping chunks and chunks with imperfect overlap
.RE
.sp
\fB\-\-ligate\-warn\fP
.RS 4
Drop sites in imperfect overlaps
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-n, \-\-naive\fP
.RS 4
Concatenate VCF or BCF files without recompression. This is very fast but requires
that all files are of the same type (all VCF or all BCF) and have the same headers.
This is because all tags and chromosome names in the BCF body rely on the order
of the contig and tag definitions in the header. A header check compatibility
is performed and the program throws an error if it is not safe to use the option.
.RE
.sp
\fB\-\-naive\-force\fP
.RS 4
Same as \-\-naive, but header compatibility is not checked. Dangerous, use with caution.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-q, \-\-min\-PQ\fP \fIINT\fP
.RS 4
Break phase set if phasing quality is lower than \fIINT\fP
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP. Requires \fB\-a, \-\-allow\-overlaps\fP.
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP. Requires \fB\-a, \-\-allow\-overlaps\fP.
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "bcftools consensus \fI[OPTIONS]\fP \fIFILE\fP"
.sp
Create consensus sequence by applying VCF variants to a reference fasta file.
By default, the program will apply all ALT variants to the reference fasta to
obtain the consensus sequence. Using the \fB\-\-sample\fP (and, optionally,
\fB\-\-haplotype\fP) option will apply genotype (haplotype) calls from FORMAT/GT.
Note that the program does not act as a primitive variant caller and ignores allelic
depth information, such as INFO/AD or FORMAT/AD. For that, consider using the
\fBsetGT\fP plugin.
.sp
\fB\-a, \-\-absent\fP \fICHAR\fP
.RS 4
replace positions absent from VCF with CHAR
.RE
.sp
\fB\-c, \-\-chain\fP \fIFILE\fP
.RS 4
write a chain file for liftover
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIFILE\fP
.RS 4
reference sequence in fasta format
.RE
.sp
\fB\-H, \-\-haplotype\fP N|\fIR\fP|\fIA\fP|\fII\fP|\fILR\fP|\fILA\fP|\fISR\fP|\fISA\fP|\fINpIu\fP
.RS 4
choose which allele from the FORMAT/GT field to use (the codes are case\-insensitive):
.sp
\fIN\fP
.RS 4
N={1,2,3,...}, the allele index within the genotype, regardless of phasing
.RE
.sp
\fIR\fP
.RS 4
the REF allele (in heterozygous genotypes)
.RE
.sp
\fIA\fP
.RS 4
the ALT allele (in heterozygous genotypes)
.RE
.sp
\fII\fP
.RS 4
IUPAC code for all genotypes
.RE
.sp
\fILR, LA\fP
.RS 4
the longer allele. If both have the same length, use the REF allele (LR), or the ALT allele  (LA)
.RE
.sp
\fISR, SA\fP
.RS 4
the shorter allele. If both have the same length, use the REF allele (SR), or the ALT allele  (SA)
.RE
.sp
\fINpIu\fP
.RS 4
N={1,2,3,...}, the allele index within genotype for phased genotypes and IUPAC code for unphased genotypes.
For example, \fI1pIu\fP or \fI2pIu\fP
.RE
.RE
.sp
Note that the \fB\-H, \-\-haplotype\fP option requires the \fB\-s, \-\-samples\fP option, unless exactly one sample is present in the VCF
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-I, \-\-iupac\-codes\fP
.RS 4
output variants in the form of IUPAC ambiguity codes determined from FORMAT/GT fields. By default all
samples are used and can be subset with \fB\-s, \-\-samples\fP and \fB\-S, \-\-samples\-file\fP. Use \fB\-s \-\fP to ignore
samples and use only the REF and ALT columns.  NOTE: prior to version 1.17 the IUPAC codes were determined solely
from REF,ALT columns and sample genotypes were not considered.
.RE
.sp
\fB\-\-mark\-del\fP \fICHAR\fP
.RS 4
instead of removing sequence, insert character CHAR for deletions
.RE
.sp
\fB\-\-mark\-ins\fP \fIuc\fP|\fIlc\fP|\fICHAR\fP
.RS 4
highlight inserted sequence in uppercase (uc), lowercase (lc), or a provided character CHAR, leaving the rest of the sequence as is
.RE
.sp
\fB\-\-mark\-snv\fP \fIuc\fP|\fIlc\fP
.RS 4
highlight substitutions in uppercase (uc), lowercase (lc), or a provided character CHAR, leaving the rest of the sequence as is
.RE
.sp
\fB\-m, \-\-mask\fP \fIFILE\fP
.RS 4
BED file or TAB file with regions to be replaced with N (the default) or as specified by
the next \fB\-\-mask\-with\fP option. See discussion
of \fB\-\-regions\-file\fP in \fBCommon Options\fP for file
format details.
.RE
.sp
\fB\-\-mask\-with\fP \fICHAR\fP|\fIlc\fP|\fIuc\fP
.RS 4
replace sequence from \fB\-\-mask\fP with CHAR, skipping overlapping variants, or change to lowercase (lc) or uppercase (uc)
.RE
.sp
\fB\-M, \-\-missing\fP \fICHAR\fP
.RS 4
instead of skipping the missing genotypes, output the character CHAR (e.g. "?")
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
write output to a file
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
how to treat VCF variants overlapping the target region in the fasta file:
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
apply variants of the listed samples. See also the option \fB\-I, \-\-iupac\-codes\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
apply variants of the samples listed in the file. See also the option \fB\-I, \-\-iupac\-codes\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fBExamples:\fP
.sp
.if n .RS 4
.nf
.fam C
    # Apply variants present in sample "NA001", output IUPAC codes for hets
    bcftools consensus \-i \-s NA001 \-f in.fa in.vcf.gz > out.fa

    # Create consensus for one region. The fasta header lines are then expected
    # in the form ">chr:from\-to". Ignore samples and consider only the REF and ALT columns
    samtools faidx ref.fa 8:11870\-11890 | bcftools consensus \-s \- in.vcf.gz \-o out.fa

    # For more examples see http://samtools.github.io/bcftools/howtos/consensus\-sequence.html
.fam
.fi
.if n .RE
.sp
\fBNotes:\fP
.RS 4
Masking options are applied in the following order
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
mask regions with \fB\-\-mask\-with\fP character if \fB\-\-mask\fP is given. All overlapping VCF variants are ignored
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
replace sequence not mentioned in the VCF with the requested character if \fB\-\-absent\fP is given
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
finally apply \fB\-\-mark\-del\fP, \fB\-\-mark\-ins\fP, \fB\-\-mark\-snv\fP masks
.RE
.RE
.SS "bcftools convert \fI[OPTIONS]\fP \fIFILE\fP"
.SS "VCF input options:"
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "General options:"
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "GEN/SAMPLE conversion:"
.sp
\fB\-G, \-\-gensample2vcf\fP \fIprefix\fP or \fIgen\-file\fP,\fIsample\-file\fP
.RS 4
convert IMPUTE2 output to VCF. One of the ID columns ("SNP ID" or "rsID" in
.URL "https://www.cog\-genomics.org/plink/2.0/formats#gen" "" ")"
must be of the form
"CHROM:POS_REF_ALT" to detect possible strand swaps.
\~
.br
When the \fB\-\-vcf\-ids\fP option is given, the other column (autodetected) is used
to fill the ID column of the VCF.
\~
.br
See also \fB\-g\fP and \fB\-\-3N6\fP options.
.RE
.sp
\fB\-g, \-\-gensample\fP \fIprefix\fP or \fIgen\-file\fP,\fIsample\-file\fP
.RS 4
convert from VCF to gen/sample format used by IMPUTE2 and SHAPEIT.
The columns of .gen file format are ID1,ID2,POS,A,B followed by three
genotype probabilities P(AA), P(AB), P(BB) for each sample.  In order to
prevent strand swaps, the program uses IDs of the form "CHROM:POS_REF_ALT".
When the \fB\-\-vcf\-ids\fP option is given, the second column is set to match the ID
column of the VCF.
\~
.br
See also \fB\-G\fP and \fB\-\-3N6\fP options.
\~
.br
The file .gen and .sample file format are:
.RE
.sp
.if n .RS 4
.nf
.fam C
  .gen (with \-\-3N6 \-\-vcf\-ids)
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  chr1 1:111485207_G_A rsID1 111485207 G A 0 1 0 0 1 0
  chr1 1:111494194_C_T rsID2 111494194 C T 0 1 0 0 0 1

  .gen (with \-\-vcf\-ids)
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  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

  .gen (the default)
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  1:111485207_G_A 1:111485207_G_A 111485207 G A 0 1 0 0 1 0
  1:111494194_C_T 1:111494194_C_T 111494194 C T 0 1 0 0 0 1

  .sample
  \-\-\-\-\-\-\-
  ID_1 ID_2 missing
  0 0 0
  sample1 sample1 0
  sample2 sample2 0
.fam
.fi
.if n .RE
.sp
\fB\-\-3N6\fP
.RS 4
Expect/Create files in the 3*N+6 column format. This is the new .gen file format with the first
column containing the chromosome name, see \c
.URL "https://www.cog\-genomics.org/plink/2.0/formats#gen" "" ""
.RE
.sp
\fB\-\-tag\fP \fISTRING\fP
.RS 4
tag to take values for .gen file: GT,PL,GL,GP
.RE
.sp
\fB\-\-sex\fP \fIFILE\fP
.RS 4
output sex column in the sample file. The FILE format is
.RE
.sp
.if n .RS 4
.nf
.fam C
    MaleSample    M
    FemaleSample  F
.fam
.fi
.if n .RE
.sp
\fB\-\-vcf\-ids\fP
.RS 4
output VCF IDs in the second column instead of CHROM:POS_REF_ALT
.RE
.SS "gVCF conversion:"
.sp
\fB\-\-gvcf2vcf\fP
.RS 4
convert gVCF to VCF, expanding REF blocks into sites. Note that
the \fB\-i\fP and \fB\-e\fP options work differently with this switch. In this situation
the filtering expressions define which sites should be expanded and
which sites should be left unmodified, but all sites are printed on
output. In order to drop sites, stream first through \fBbcftools view\fP.
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIfile\fP
.RS 4
reference sequence in fasta format. Must be indexed with samtools faidx
.RE
.SS "HAP/SAMPLE conversion:"
.sp
\fB\-\-hapsample2vcf\fP \fIprefix\fP or \fIhap\-file\fP,\fIsample\-file\fP
.RS 4
convert from hap/sample format to VCF. The columns of .hap file are
similar to .gen file above, but there are only two haplotype columns per
sample.  Note that the first or the second column of the .hap file is expected to be in
the form "CHR:POS_REF_ALT[_END]", with the _END being optional for
defining the INFO/END tag when ALT is a symbolic allele. For example:
.RE
.sp
.if n .RS 4
.nf
.fam C
  .hap (with \-\-vcf\-ids)
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  1:111485207_G_A rsID1 111485207 G A 0 1 0 0
  1:111495231_A_<DEL>_111495784 rsID3 111495231 A <DEL> 0 0 1 0

  .hap (the default)
  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  1 1:111485207_G_A 111485207 G A 0 1 0 0
  1 1:111495231_A_<DEL>_111495784 111495231 A <DEL> 0 0 1 0
.fam
.fi
.if n .RE
.sp
\fB\-\-hapsample\fP \fIprefix\fP or \fIhap\-file\fP,\fIsample\-file\fP
.RS 4
convert from VCF to hap/sample format used by IMPUTE2 and SHAPEIT.
The columns of .hap file begin with ID,RSID,POS,REF,ALT. In order to
prevent strand swaps, the program uses IDs of the form
"CHROM:POS_REF_ALT".
.RE
.sp
\fB\-\-haploid2diploid\fP
.RS 4
with \fB\-h\fP option converts haploid genotypes to homozygous diploid
genotypes. For example, the program will print \fI0 0\fP instead of the
default \fI0 \-\fP. This is useful for programs which do not handle haploid
genotypes correctly.
.RE
.sp
\fB\-\-sex\fP \fIFILE\fP
.RS 4
output sex column in the sample file. The FILE format is
.RE
.sp
.if n .RS 4
.nf
.fam C
    MaleSample    M
    FemaleSample  F
.fam
.fi
.if n .RE
.sp
\fB\-\-vcf\-ids\fP
.RS 4
the second column of the .hap file holds the VCF ids, the first
column is of the form "CHR:POS_REF_ALT[_END]". Without the option,
the format follows \c
.URL "https://www.cog\-genomics.org/plink/2.0/formats#haps" ""
with ids (the second column) of the form "CHR:POS_REF_ALT[_END]"
.RE
.SS "HAP/LEGEND/SAMPLE conversion:"
.sp
\fB\-H, \-\-haplegendsample2vcf\fP \fIprefix\fP or \fIhap\-file\fP,\fIlegend\-file\fP,\fIsample\-file\fP
.RS 4
convert from hap/legend/sample format used by IMPUTE2 to VCF.
See also \fB\-h, \-\-hapslegendsample\fP below.
.RE
.sp
\fB\-h, \-\-haplegendsample\fP \fIprefix\fP or \fIhap\-file\fP,\fIlegend\-file\fP,\fIsample\-file\fP
.RS 4
convert from VCF to hap/legend/sample format used by IMPUTE2 and SHAPEIT.
The columns of .legend file ID,POS,REF,ALT. In order to prevent strand
swaps, the program uses IDs of the form "CHROM:POS_REF_ALT".
The .sample file is quite basic at the moment with columns for population, group and
sex expected to be edited by the user. For example:
.RE
.sp
.if n .RS 4
.nf
.fam C
  .hap
  \-\-\-\-\-
  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
.fam
.fi
.if n .RE
.sp
\fB\-\-haploid2diploid\fP
.RS 4
with \fB\-h\fP option converts haploid genotypes to homozygous diploid
genotypes. For example, the program will print \fI0 0\fP instead of the
default \fI0 \-\fP. This is useful for programs which do not handle haploid
genotypes correctly.
.RE
.sp
\fB\-\-sex\fP \fIFILE\fP
.RS 4
output sex column in the sample file. The FILE format is
.RE
.sp
.if n .RS 4
.nf
.fam C
    MaleSample    M
    FemaleSample  F
.fam
.fi
.if n .RE
.sp
\fB\-\-vcf\-ids\fP
.RS 4
output VCF IDs instead of "CHROM:POS_REF_ALT". Note that this option can
be used with \fB\-\-haplegendsample\fP but not with \fB\-\-haplegendsample2vcf\fP.
.RE
.SS "TSV conversion:"
.sp
\fB\-\-tsv2vcf\fP \fIfile\fP
.RS 4
convert from TSV (tab\-separated values) format (such as generated by
23andMe) to VCF. The input file fields can be tab\- or space\- delimited
.RE
.sp
\fB\-c, \-\-columns\fP \fIlist\fP
.RS 4
comma\-separated list of fields in the input file. In the current
version, the fields CHROM, POS, ID, and AA or REF, ALT are expected and
can appear in arbitrary order. Columns which should be ignored in the input
file can be indicated by "\-".
The AA field lists alleles on the forward reference strand,
for example "CC" or "CT" for diploid genotypes or "C"
for haploid genotypes (sex chromosomes). Insertions and deletions
are supported only with REF and ALT but not with AA. Missing data can be indicated with "\-\-" or ".".
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIfile\fP
.RS 4
reference sequence in fasta format. Must be indexed with samtools faidx
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
list of sample names. See \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
file of sample names. See \fBCommon Options\fP
.RE
.sp
\fBExample:\fP
.sp
.if n .RS 4
.nf
.fam C
# Convert 23andme results into VCF
bcftools convert \-c ID,CHROM,POS,AA \-s SampleName \-f 23andme\-ref.fa \-\-tsv2vcf 23andme.txt \-o out.vcf.gz

# Convert tab\-delimited file into a sites\-only VCF (no genotypes), in this example first column to be ignored
bcftools convert \-c \-,CHROM,POS,REF,ALT \-f ref.fa \-\-tsv2vcf calls.txt \-o out.bcf
.fam
.fi
.if n .RE
.SS "bcftools csq \fI[OPTIONS]\fP \fIFILE\fP"
.sp
Haplotype aware consequence predictor which correctly handles combined
variants such as MNPs split over multiple VCF records, SNPs separated by
an intron (but adjacent in the spliced transcript) or nearby frame\-shifting
indels which in combination in fact are not frame\-shifting.
.sp
The output VCF is annotated with INFO/BCSQ and FORMAT/BCSQ tag (configurable
with the \fB\-c\fP option). The latter is a bitmask of indexes to INFO/BCSQ, with
interleaved haplotypes. See the usage examples below for using the %TBCSQ
converter in \fBquery\fP for extracting a more human readable form from this
bitmask. The construction of the bitmask limits the number of consequences
that can be referenced per sample in the FORMAT/BCSQ tags. By default this is 15, but
if more are required, see the \fB\-\-ncsq\fP option.
.sp
Note that the program annotates only records with a functional consequence and
intergenic regions will pass through unchanged.
.sp
The program requires on input a VCF/BCF file, the reference genome in fasta
format (\fB\-\-fasta\-ref\fP) and genomic features in the GFF3 format downloadable
from the Ensembl website (\fB\-\-gff\-annot\fP), and outputs an annotated VCF/BCF
file. Currently, only Ensembl GFF3 files are supported.
.sp
By default, the input VCF should be phased. If phase is unknown, or only
partially known, the \fB\-\-phase\fP option can be used to indicate how to handle
unphased data. Alternatively, haplotype aware calling can be turned off
with the \fB\-\-local\-csq\fP option.
.sp
If conflicting (overlapping) variants within one haplotype are detected,
a warning will be emitted and predictions will be based on only the first
variant in the analysis.
.sp
Symbolic alleles are not supported. They will remain unannotated in the
output VCF and are ignored for the prediction analysis.
.sp
\fB\-B, \-\-trim\-protein\-seq\fP \fIINT\fP
.RS 4
abbreviate protein\-changing predictions to maximum of INT aminoacids.
For example, instead of writing the whole modified protein sequence with potentially hundreds of
aminoacids, with \fB\-B 1\fP only an abbreviated version such as \fI25E..329>25G..94\fP will be
written.
.RE
.sp
\fB\-C, \-\-genetic\-code\fP \fIINT\fP|\fIl\fP
.RS 4
specify the genetic code table to use, \fIl\fP to print a list of supported tables
.RE
.sp
\fB\-c, \-\-custom\-tag\fP \fISTRING\fP
.RS 4
use this custom tag to store consequences rather than the default BCSQ tag
.RE
.sp
\fB\-\-dump\-gff\fP \fIFILE\fP
.RS 4
dump the parsed GFF into a gzipped FILE. Intended for debugging purposes,
shows how is the input GFF viewed by the program.
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIFILE\fP
.RS 4
reference sequence in fasta format (required)
.RE
.sp
\fB\-\-force\fP
.RS 4
run even if some sanity checks fail. Currently the option enables skipping
transcripts in malformatted GFFs with incorrect phase
.RE
.sp
\fB\-g, \-\-gff\-annot\fP \fIFILE\fP
.RS 4
GFF3 annotation file (required), such as \c
.URL "http://ftp.ensembl.org/pub/current_gff3/homo_sapiens/" "" "."
The script \fBgff2gff\fP can help with conversion from non\-standard GFF formats.
An example of a minimal working GFF file:
.RE
.sp
.if n .RS 4
.nf
.fam C
    # The program looks for "CDS", "exon", "three_prime_UTR" and "five_prime_UTR" lines,
    # looks up their parent transcript (determined from the "Parent=transcript:" attribute),
    # the gene (determined from the transcript\*(Aqs "Parent=gene:" attribute), and the biotype
    # (the most interesting is "protein_coding").
    #
    # Empty and commented lines are skipped, the following GFF columns are required
    #   1.  chromosome
    #   2.  IGNORED
    #   3.  type (CDS, exon, three_prime_UTR, five_prime_UTR, gene, transcript, etc.)
    #   4.  start of the feature (1\-based)
    #   5.  end of the feature (1\-based)
    #   6.  IGNORED
    #   7.  strand (+ or \-)
    #   8.  phase (0, 1, 2 or .)
    #   9.  semicolon\-separated attributes (see below)
    #
    # Attributes required for
    #   gene lines:
    #   \- ID=gene:<gene_id>
    #   \- biotype=<biotype>
    #   \- Name=<gene_name>      [optional]
    #
    #   transcript lines:
    #   \- ID=transcript:<transcript_id>
    #   \- Parent=gene:<gene_id>
    #   \- biotype=<biotype>
    #
    #   other lines (CDS, exon, five_prime_UTR, three_prime_UTR):
    #   \- Parent=transcript:<transcript_id>
    #
    # Supported biotypes:
    #   \- see the function gff_parse_biotype() in bcftools/csq.c

    1   ignored_field  gene            21  2148  .   \-   .   ID=gene:GeneId;biotype=protein_coding;Name=GeneName
    1   ignored_field  transcript      21  2148  .   \-   .   ID=transcript:TranscriptId;Parent=gene:GeneId;biotype=protein_coding
    1   ignored_field  three_prime_UTR 21  2054  .   \-   .   Parent=transcript:TranscriptId
    1   ignored_field  exon            21  2148  .   \-   .   Parent=transcript:TranscriptId
    1   ignored_field  CDS             21  2148  .   \-   1   Parent=transcript:TranscriptId
    1   ignored_field  five_prime_UTR  210 2148  .   \-   .   Parent=transcript:TranscriptId
.fam
.fi
.if n .RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-l, \-\-local\-csq\fP
.RS 4
switch off haplotype\-aware calling, run localized predictions considering
only one VCF record at a time
.RE
.sp
\fB\-n, \-\-ncsq\fP \fIINT\fP
.RS 4
maximum number of per\-haplotype consequences to consider for each site. The INFO/BCSQ column includes
all consequences, but only the first \fIINT\fP will be referenced by the FORMAT/BCSQ fields.
The default value is 15 which corresponds to one 32\-bit integer per diploid
sample, after accounting for values reserved by the BCF specification.
Note that increasing the value leads to increased size of the output BCF.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIt\fP|\fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP. In addition, a custom tab\-delimited
plain text output can be printed (\fIt\fP).
.RE
.sp
\fB\-p, \-\-phase\fP \fIa\fP|\fIm\fP|\fIr\fP|\fIR\fP|\fIs\fP
.RS 4
how to handle unphased heterozygous genotypes:
.sp
\fIa\fP
.RS 4
take GTs as is, create haplotypes regardless of phase (0/1 \(-> 0|1)
.RE
.sp
\fIm\fP
.RS 4
merge all GTs into a single haplotype (0/1 \(-> 1, 1/2 \(-> 1)
.RE
.sp
\fIr\fP
.RS 4
require phased GTs, throw an error on unphased heterozygous GTs
.RE
.sp
\fIR\fP
.RS 4
create non\-reference haplotypes if possible (0/1 \(-> 1|1, 1/2 \(-> 1|2)
.RE
.sp
\fIs\fP
.RS 4
skip unphased heterozygous GTs
.RE
.RE
.sp
\fB\-q, \-\-quiet\fP
.RS 4
suppress warning messages
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
samples to include or "\-" to apply all variants and ignore samples
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-unify\-chr\-names\fP \fI0\fP|\fILIST\fP
.RS 4
unify chromosome naming by stripping a prefix in VCF, GFF, fasta, respectively.
For example, if the LIST is "chr,Chromosome,\-", the program will trim the "chr" prefix
in the VCF, "Chromosome" in the GFF, and the fasta will be left unchanged.
The chromosome names in the output VCF will match that of the input VCF. The default is
not to modify the sequence names.
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.sp
\fBExamples:\fP
.sp
.if n .RS 4
.nf
.fam C
    # Basic usage
    bcftools csq \-f hs37d5.fa \-g Homo_sapiens.GRCh37.82.gff3.gz in.vcf \-Ob \-o out.bcf

    # Extract the translated haplotype consequences. The following TBCSQ variations
    # are recognised:
    #   %TBCSQ    .. print consequences in all haplotypes in separate columns
    #   %TBCSQ{0} .. print the first haplotype only
    #   %TBCSQ{1} .. print the second haplotype only
    #   %TBCSQ{*} .. print a list of unique consequences present in either haplotype
    bcftools query \-f\*(Aq[%CHROM\(rst%POS\(rst%SAMPLE\(rst%TBCSQ\(rsn]\*(Aq out.bcf
.fam
.fi
.if n .RE
.sp
\fBExamples of BCSQ annotation:\fP
.sp
.if n .RS 4
.nf
.fam C
    # Two separate VCF records at positions 2:122106101 and 2:122106102
    # change the same codon. This UV\-induced C>T dinucleotide mutation
    # has been annotated fully at the position 2:122106101 with
    #   \- consequence type
    #   \- gene name
    #   \- ensembl transcript ID
    #   \- coding strand (+ fwd, \- rev)
    #   \- amino acid position (in the coding strand orientation)
    #   \- list of corresponding VCF variants
    # The annotation at the second position gives the position of the full
    # annotation
    BCSQ=missense|CLASP1|ENST00000545861|\-|1174P>1174L|122106101G>A+122106102G>A
    BCSQ=@122106101

    # A frame\-restoring combination of two frameshift insertions C>CG and T>TGG
    BCSQ=@46115084
    BCSQ=inframe_insertion|COPZ2|ENST00000006101|\-|18AGRGP>18AQAGGP|46115072C>CG+46115084T>TGG

    # Stop gained variant
    BCSQ=stop_gained|C2orf83|ENST00000264387|\-|141W>141*|228476140C>T

    # The consequence type of a variant downstream from a stop are prefixed with *
    BCSQ=*missense|PER3|ENST00000361923|+|1028M>1028T|7890117T>C
.fam
.fi
.if n .RE
.sp
\fBSupported consequence types\fP
.sp
.if n .RS 4
.nf
.fam C
3_prime_utr
5_prime_utr
coding_sequence
feature_elongation
frameshift
inframe_altering
inframe_deletion
inframe_insertion
intergenic
intron
missense
non_coding
splice_acceptor
splice_donor
splice_region
start_lost
start_retained
stop_gained
stop_lost
stop_retained
synonymous
.fam
.fi
.if n .RE
.sp
See also \c
.URL "https://ensembl.org/info/genome/variation/prediction/predicted_data.html" "" ""
.SS "bcftools filter \fI[OPTIONS]\fP \fIFILE\fP"
.sp
Apply fixed\-threshold filters.
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-g, \-\-SnpGap\fP \fIINT\fP[:\*(Aqindel\*(Aq,\fImnp\fP,\fIbnd\fP,\fIother\fP,\fIoverlap\fP]
.RS 4
filter SNPs within \fIINT\fP base pairs of an indel or other other variant type. The following example
demonstrates the logic of \fB\-\-SnpGap\fP \fI3\fP applied on a deletion and
an insertion:
.RE
.sp
.if n .RS 4
.nf
.fam C
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..
.fam
.fi
.if n .RE
.sp
\fB\-G, \-\-IndelGap\fP \fIINT\fP
.RS 4
filter clusters of indels separated by \fIINT\fP or fewer base pairs allowing
only one to pass. The following example demonstrates the logic of
\fB\-\-IndelGap\fP \fI2\fP applied on a deletion and an insertion:
.RE
.sp
.if n .RS 4
.nf
.fam C
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..
.fam
.fi
.if n .RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-\-mask\fP [^]\fIREGION\fP
.RS 4
Soft filter regions, prepepend "^" to negate. Requires \fB\-s, \-\-soft\-filter\fP.
.RE
.sp
\fB\-M, \-\-mask\-file\fP [^]\fIFILE\fP
.RS 4
Soft filter regions listed in a file, "^" to negate.  Requires \fB\-s, \-\-soft\-filter\fP.
.RE
.sp
\fB\-\-mask\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
Same as \fB\-\-regions\-overlap\fP but for \fB\-\-mask/\-\-mask\-file\fP.
See \fBCommon Options\fP. [1]
.RE
.sp
\fB\-m, \-\-mode\fP [\fI+x\fP]
.RS 4
define behaviour at sites with existing FILTER annotations. The default
mode replaces existing filters of failed sites with a new FILTER string
while leaving sites which pass untouched when non\-empty and setting to
"PASS" when the FILTER string is absent. The "+" mode appends new FILTER
strings of failed sites instead of replacing them. The "x" mode resets
filters of sites which pass to "PASS". Modes "+" and "x" can both be set.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-soft\-filter\fP \fISTRING\fP|\fI+\fP
.RS 4
annotate FILTER column with \fISTRING\fP or, with \fI+\fP, a unique filter name generated
by the program ("Filter%d"). Applies to records that do not meet filter expression.
.RE
.sp
\fB\-S, \-\-set\-GTs\fP \fI.\fP|\fI0\fP
.RS 4
set genotypes of failed samples to missing value (\fI.\fP) or reference allele (\fI0\fP)
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "bcftools gtcheck [\fIOPTIONS\fP] [\fB\-g\fP \fIgenotypes.vcf.gz\fP] \fIquery.vcf.gz\fP"
.sp
Checks sample identity. The program can operate in two modes. If the \fB\-g\fP
option is given, the identity of samples from \fIquery.vcf.gz\fP
is checked against the samples in the \fB\-g\fP file.
Without the \fB\-g\fP option, multi\-sample cross\-check of samples in \fIquery.vcf.gz\fP is performed.
.sp
Note that the interpretation of the discordance score depends on the options provided (specifically \fB\-e\fP and
\fB\-u\fP) and on the available annotations (FORMAT/PL vs FORMAT/GT).
The discordance score can be interpreted as the number of mismatching genotypes only if GT\-vs\-GT matching is performed.
.sp
\fB\-\-distinctive\-sites\fP \fINUM[,MEM[,DIR]]\fP
.RS 4
Find sites that can distinguish between at least NUM sample pairs. If the number is smaller or equal to 1,
it is interpreted as the fraction of pairs.  The optional MEM string sets the maximum memory used for
in\-memory sorting and DIR is the temporary directory for external sorting. This option requires also
\fB\-\-pairs\fP to be given.
.RE
.sp
\fB\-\-dry\-run\fP
.RS 4
Stop after first record to estimate required time.
.RE
.sp
\fB\-e, \-\-exclude\fP [\fIqry\fP|\fIgt\fP]:\*(AqEXPRESSION\*(Aq
.RS 4
Exclude sites from query file (\fIqry:\fP) or genotype file (\fIgt:\fP) for which \fIEXPRESSION\fP is true.
For valid expressions see \fBEXPRESSIONS\fP.
.RE
.sp
\fB\-E, \-\-error\-probability\fP \fIINT\fP
.RS 4
Interpret genotypes and genotype likelihoods probabilistically. The value of \fIINT\fP
represents genotype quality when GT tag is used (e.g. Q=30 represents one error in 1,000 genotypes and
Q=40 one error in 10,000 genotypes) and is ignored when PL tag is used (in that case an arbitrary
non\-zero integer can be provided).
\~
.br
\~
.br
If \fB\-E\fP is set to 0, the discordance score can be interpreted as the number of mismatching genotypes,
but only in the GT\-vs\-GT matching mode. See the \fB\-u, \-\-use\fP option below for additional notes and caveats.
\~
.br
\~
.br
If performance is an issue, set \fB\-E 0\fP for faster run times but less accurate results.
\~
.br
\~
.br
Note that in previous versions of bcftools (\(lA1.18), this option used to be a smaller case \fB\-e\fP. It
changed to make room for the filtering option \fB\-e, \-\-exclude\fP to stay consistent across other
commands.
.RE
.sp
\fB\-g, \-\-genotypes\fP \fIFILE\fP
.RS 4
VCF/BCF file with reference genotypes to compare against
.RE
.sp
\fB\-H, \-\-homs\-only\fP
.RS 4
Homozygous genotypes only, useful with low coverage data (requires \fB\-g, \-\-genotypes\fP)
.RE
.sp
\fB\-i, \-\-include\fP [\fIqry\fP|\fIgt\fP]:\*(AqEXPRESSION\*(Aq
.RS 4
Include sites from query file (\fIqry:\fP) or genotype file (\fIgt:\fP) for which \fIEXPRESSION\fP is true.
For valid expressions see \fBEXPRESSIONS\fP.
.RE
.sp
\fB\-\-n\-matches\fP \fIINT\fP
.RS 4
Print only top INT matches for each sample, 0 for unlimited. Use negative value
to sort by HWE probability rather than the number of discordant sites. Note
that average score is used to determine the top matches, not absolute values.
.RE
.sp
\fB\-\-no\-HWE\-prob\fP
.RS 4
Disable calculation of HWE probability to reduce memory requirements with
comparisons between very large number of sample pairs.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
Write to \fIFILE\fP rather than to standard output, where it is written by default.
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIt\fP|\fIz\fP
.RS 4
Write a plain (\fIt\fP) or compressed (\fIz\fP) text tab\-delimited output.
.RE
.sp
\fB\-p, \-\-pairs\fP \fILIST\fP
.RS 4
A comma\-separated list of sample pairs to compare. When the \fB\-g\fP option is given, the first
sample must be from the query file, the second from the \fB\-g\fP file, third from the query file
etc (qry,gt[,qry,gt..]). Without the \fB\-g\fP option, the pairs are created the same way but both
samples are from the query file (qry,qry[,qry,qry..])
.RE
.sp
\fB\-P, \-\-pairs\-file\fP \fIFILE\fP
.RS 4
A file with tab\-delimited sample pairs to compare. The first sample in the pair must come
from the query file, the second from the genotypes file when \fB\-g\fP is given
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
Restrict to comma\-separated list of regions, see \fBCommon Options\fP
.RE
.sp
*\-R, \-\-regions\-file\*(Aq \fIFILE\fP
.RS 4
Restrict to regions listed in a file, see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP [\fIqry\fP|\fIgt\fP]:\*(AqLIST\*(Aq:
List of query samples or \fB\-g\fP samples. If neither \fB\-s\fP nor \fB\-S\fP are given, all possible sample
pair combinations are compared
.sp
\fB\-S, \-\-samples\-file\fP [\fIqry\fP|\fIgt\fP]:\*(AqFILE\*(Aq
File with the query or \fB\-g\fP samples to compare.  If neither \fB\-s\fP nor \fB\-S\fP are given, all possible sample
pair combinations are compared
.sp
\fB\-t, \-\-targets\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-u, \-\-use\fP \fITAG1\fP[,\fITAG2\fP]
.RS 4
specifies which tag to use in the query file (\fITAG1\fP) and the \fB\-g\fP (\fITAG2\fP) file.
By default, the PL tag is used in the query file and, when available, the GT tags in the
\fB\-g\fP file.
\~
.br
\~
.br
Note that when the requested tag is not available, the program will attempt to use
the other tag. The output includes the number of sites that were matched by the four
possible modes (for example GT\-vs\-GT or GT\-vs\-PL).
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fBExamples:\fP
.sp
.if n .RS 4
.nf
.fam C
   # Check discordance of all samples from B against all samples in A
   bcftools gtcheck \-g A.bcf B.bcf

   # Limit comparisons to the given list of samples
   bcftools gtcheck \-s gt:a1,a2,a3 \-s qry:b1,b2 \-g A.bcf B.bcf

   # Compare only two pairs a1,b1 and a1,b2
   bcftools gtcheck \-p a1,b1,a1,b2 \-g A.bcf B.bcf
.fam
.fi
.if n .RE
.SS "bcftools head [\fIOPTIONS\fP] [\fIFILE\fP]"
.sp
By default, prints all headers from the specified input file to standard output
in VCF format. The input file may be in VCF or BCF format; if no \fIFILE\fP is
specified, standard input will be read. With appropriate options, only some
of the headers and/or additionally some of the variant records will be printed.
.sp
The \fBbcftools head\fP command outputs VCF headers almost exactly as they appear
in the input file: it may add a \f(CR##FILTER=<ID=PASS>\fP header if not already
present, but it never adds version or command line information itself.
.SS "Options:"
.sp
\fB\-h, \-\-header\fP \fIINT\fP
.RS 4
Display only the first \fIINT\fP header lines.
By default, all header lines are displayed.
.RE
.sp
\fB\-n, \-\-records\fP \fIINT\fP
.RS 4
Also display the first \fIINT\fP variant records.
By default, no variant records are displayed.
.RE
.sp
\fB\-s, \-\-samples\fP \fIINT\fP
.RS 4
Display the first \fIINT\fP variant records including the last #CHROM header line with samples.
Running with \fB\-s 0\fP alone outputs the #CHROM header line only. Note that
the list of samples, with each sample per line, can be obtained with \f(CRbcftools query\fP using
the option \fB\-l, \-\-list\-samples\fP.
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "bcftools index [\fIOPTIONS\fP] \fIin.bcf\fP|\fIin.vcf.gz\fP"
.sp
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 \fI\-t/\-\-tbi\fP option or using the \fItabix\fP program
packaged with htslib. When loading an index file, bcftools will try
the CSI first and then the TBI.
.SS "Indexing options:"
.sp
\fB\-c, \-\-csi\fP
.RS 4
generate CSI\-format index for VCF/BCF files [default]
.RE
.sp
\fB\-f, \-\-force\fP
.RS 4
overwrite index if it already exists
.RE
.sp
\fB\-m, \-\-min\-shift \fIINT\fP\fP
.RS 4
set minimal interval size for CSI indices to 2^INT; default: 14
.RE
.sp
\fB\-o, \-\-output \fIFILE\fP\fP
.RS 4
output file name. If not set, then the index will be created
using the input file name plus a \fI.csi\fP or \fI.tbi\fP extension
.RE
.sp
\fB\-t, \-\-tbi\fP
.RS 4
generate TBI\-format index for VCF files
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "Stats options:"
.sp
\fB\-a, \-\-all\fP
.RS 4
Used in conjunction with \fB\-s, \-\-stats\fP, print per contig stats
for all contigs, even those with zero records and those for which
no stats are recorded in the index file (shown as \fI.\fP).
.RE
.sp
\fB\-n, \-\-nrecords\fP
.RS 4
print the number of records based on the CSI or TBI index files
.RE
.sp
\fB\-s, \-\-stats\fP
.RS 4
Print per contig stats based on the CSI or TBI index files.
Output format is three tab\-delimited columns listing the contig
name, contig length (\fI.\fP if unknown) and number of records for
the contig. Contigs with zero records are not printed by default.
.RE
.SS "bcftools isec [\fIOPTIONS\fP] \fIA.vcf.gz\fP \fIB.vcf.gz\fP [...]"
.sp
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.
.sp
\fB\-c, \-\-collapse\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIsome\fP|\fInone\fP|\fIid\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-C, \-\-complement\fP
.RS 4
output positions present only in the first file but missing in the others
.RE
.sp
\fB\-e, \-\-exclude\fP \fI\-\fP|\fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. If \fB\-e\fP (or \fB\-i\fP)
appears only once, the same filtering expression will be applied to all
input files.  Otherwise, \fB\-e\fP or \fB\-i\fP must be given for each input file.
To indicate that no filtering should be performed on a file, use "\-" in
place of \fIEXPRESSION\fP, as shown in the example below.
For valid expressions see \fBEXPRESSIONS\fP.
.RE
.sp
\fB\-f, \-\-apply\-filters\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. See discussion
of \fB\-e, \-\-exclude\fP above.
.RE
.sp
\fB\-f, \-\-file\-list\fP \fIFILE\fP
.RS 4
Read file names from \fIFILE\fP, one file name per line.
.RE
.sp
\fB\-n, \-\-nfiles\fP [+\-=]\fIINT\fP|~\fIBITMAP\fP
.RS 4
output positions present in this many (=), this many or more (+), this
many or fewer (\-), or the exact same (~) files
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP.  When several files are being
output, their names are controlled via \fB\-p\fP instead.
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-p, \-\-prefix\fP \fIDIR\fP
.RS 4
if given, subset each of the input files accordingly. See also \fB\-w\fP.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-w, \-\-write\fP \fILIST\fP
.RS 4
comma\-separated list of input files to output given as 1\-based indices. With \fB\-p\fP and no
\fB\-w\fP, all files are written.
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and defaults
to tbi for vcf.gz and csi for bcf.  This is done automatically
with the \fB\-p\fP option if the output format is compressed.
.RE
.SS "Examples:"
.sp
Create intersection and complements of two sets saving the output in dir/*
.sp
.if n .RS 4
.nf
.fam C
    bcftools isec \-p dir A.vcf.gz B.vcf.gz
.fam
.fi
.if n .RE
.sp
Filter sites in A (require INFO/MAF>=0.01) and B (require INFO/dbSNP) but not in C,
and create an intersection, including only sites which appear in at least two of
the files after filters have been applied
.sp
.if n .RS 4
.nf
.fam C
    bcftools isec \-e\*(AqMAF<0.01\*(Aq \-i\*(AqdbSNP=1\*(Aq \-e\- A.vcf.gz B.vcf.gz C.vcf.gz \-n +2 \-p dir
.fam
.fi
.if n .RE
.sp
Extract and write records from A shared by both A and B using exact allele match
.sp
.if n .RS 4
.nf
.fam C
    bcftools isec \-p dir \-n=2 \-w1 A.vcf.gz B.vcf.gz
.fam
.fi
.if n .RE
.sp
Extract records private to A or B comparing by position only
.sp
.if n .RS 4
.nf
.fam C
    bcftools isec \-p dir \-n\-1 \-c all A.vcf.gz B.vcf.gz
.fam
.fi
.if n .RE
.sp
Print a list of records which are present in A and B but not in C and D
.sp
.if n .RS 4
.nf
.fam C
    bcftools isec \-n~1100 \-c all A.vcf.gz B.vcf.gz C.vcf.gz D.vcf.gz
.fam
.fi
.if n .RE
.SS "bcftools merge [\fIOPTIONS\fP] \fIA.vcf.gz\fP \fIB.vcf.gz\fP [...]"
.sp
Merge multiple VCF/BCF files from non\-overlapping sample sets to create one
multi\-sample file.  For example, when merging file \fIA.vcf.gz\fP containing
samples \fIS1\fP, \fIS2\fP and \fIS3\fP and file \fIB.vcf.gz\fP containing samples \fIS3\fP and
\fIS4\fP, the output file will contain five samples named \fIS1\fP, \fIS2\fP, \fIS3\fP, \fI2:S3\fP
and \fIS4\fP.
.sp
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 \fB\-\-force\-samples\fP is given.  The sample names can be
also given explicitly using the \fB\-\-print\-header\fP and \fB\-\-use\-header\fP options.
.sp
Note that only records from different files can be merged, never from the same file.
For "vertical" merge take a look at \fBbcftools concat\fP or \fBbcftools norm \-m\fP instead.
.sp
\fB\-\-force\-no\-index\fP
.RS 4
synonymous to \fB\-\-no\-index\fP
.RE
.sp
\fB\-\-force\-samples\fP
.RS 4
if the merged files contain duplicate samples names, proceed anyway.
Duplicate sample names will be resolved by prepending the index of the file
as it appeared on the command line to the conflicting sample name (see
\fI2:S3\fP in the above example).
.RE
.sp
\fB\-\-force\-single\fP
.RS 4
run even if only one file is given on input
.RE
.sp
\fB\-\-print\-header\fP
.RS 4
print only merged header and exit
.RE
.sp
\fB\-\-use\-header\fP \fIFILE\fP
.RS 4
use the VCF header in the provided text \fIFILE\fP
.RE
.sp
\fB\-0  \-\-missing\-to\-ref\fP
.RS 4
assume genotypes at missing sites are 0/0
.RE
.sp
\fB\-f, \-\-apply\-filters\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-F, \-\-filter\-logic\fP \fIx\fP|\fI+\fP
.RS 4
Set the output record to PASS if any of the inputs is PASS (\fIx\fP),
or apply all filters (\fI+\fP), which is the default.
.RE
.sp
\fB\-g, \-\-gvcf\fP \fI\-\fP|\fIFILE\fP
.RS 4
merge gVCF blocks, INFO/END tag is expected. If the reference fasta
file \fIFILE\fP is not given and the dash (\fI\-\fP) is given, unknown reference
bases generated at gVCF block splits will be substituted with N\(cqs.
The \fB\-\-gvcf\fP option uses the following default INFO rules:
\fB\-i QS:sum,MinDP:min,I16:sum,IDV:max,IMF:max\fP and the following missing
rules: \fB\-M PL:max,AD:0\fP.
.RE
.sp
\fB\-i, \-\-info\-rules\fP \fI\-\fP|\fITAG:METHOD\fP[,...]
.RS 4
Rules for merging INFO fields (scalars or vectors) or \fI\-\fP to disable the
default rules. \fIMETHOD\fP is one of \fIsum\fP, \fIavg\fP, \fImin\fP, \fImax\fP, \fIjoin\fP.
Default is \fIDP:sum,DP4:sum\fP if these fields exist in the input files.
Fields with no specified rule will take the value from the first input file.
The merged QUAL value is currently set to the maximum. This behaviour is
not user controllable at the moment.
.RE
.sp
\fB\-l, \-\-file\-list\fP \fIFILE\fP
.RS 4
Read file names from \fIFILE\fP, one file name per line.
.RE
.sp
\fB\-L, \-\-local\-alleles\fP \fIINT\fP
.RS 4
Sites with many alternate alleles can require extremely large storage space which
can exceed the 2GB size limit representable by BCF. This is caused
by Number=G tags (such as FORMAT/PL) which store a value for each combination of reference
and alternate alleles. The \fB\-L, \-\-local\-alleles\fP option allows replacement of such tags
with a localized tag (FORMAT/LPL) which only includes a subset of alternate alleles relevant
for that sample. A new FORMAT/LAA tag is added which lists 1\-based indices of the
alternate alleles relevant (local) for the current sample. The number \fIINT\fP gives the
maximum number of alternate alleles that can be included in the PL tag. The default value
is 0 which disables the feature and outputs values for all alternate alleles.
.RE
.sp
\fB\-m, \-\-merge\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIsnp\-ins\-del\fP|\fIall\fP|\fInone\fP|\fIid\fP[,\fI*\fP]
.RS 4
The option controls what types of multiallelic records can be created. If single asterisk
\fI*\fP is appended, the unobserved allele \fI<*>\fP or \fI<NON_REF>\fP will be removed at variant sites;
if two asterisks \fI**\fP are appended, the unobserved allele will be removed all sites.
.RE
.sp
.if n .RS 4
.nf
.fam C
\-m none        ..  no new multiallelics, output multiple records instead
\-m snps        ..  allow multiallelic SNP records
\-m indels      ..  allow multiallelic indel records
\-m both        ..  both SNP and indel records can be multiallelic
\-m both,*      ..  same as above but remove <*> (or <NON_REF>) from variant sites
\-m both,**     ..  same as above but remove <*> (or <NON_REF>) at all sites
\-m all         ..  SNP records can be merged with indel records
\-m snp\-ins\-del ..  allow multiallelic SNVs, insertions, deletions, but don\*(Aqt mix them
\-m id          ..  merge by ID
.fam
.fi
.if n .RE
.sp
\fB\-M, \-\-missing\-rules\fP \fI\-\fP|\fITAG:METHOD\fP[,...]
.RS 4
Rules for merging vector tags at multiallelic sites. When input files have different alternate
alleles, vector fields pertaining to unobserved alleles are set to missing (\fI.\fP) by default.
The \fIMETHOD\fP is one of \fI.\fP (the default, use missing values), \fINUMBER\fP (use a constant value, e.g. 0),
\fImax\fP (the maximum value observed for other alleles in the sample). When \fB\-\-gvcf\fP option is set,
the rule \fB\-M PL:max,AD:0\fP is implied. This can be overridden with providing \fB\-M \-\fP or \fB\-M PL:.,AD:.\fP.
Note that if the unobserved allele is explicitly present as \fI<*>\fP or \fI<NON_REF>\fP, then its corresponding
value will be used regardless of \fB\-M\fP settings.
.RE
.sp
\fB\-\-no\-index\fP
.RS 4
the option allows files to be merged without indexing them first. In order for this
option to work, the user must ensure that the input files have chromosomes in
the same order and consistent with the order of sequences in the VCF header.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "bcftools mpileup [\fIOPTIONS\fP] \fB\-f\fP \fIref.fa\fP \fIin.bam\fP [\fIin2.bam\fP [...]]"
.sp
Generate VCF or BCF containing genotype likelihoods for one or multiple
alignment (BAM or CRAM) files. This is based on the original
\fBsamtools mpileup\fP command (with the \fB\-v\fP or \fB\-g\fP options) producing
genotype likelihoods in VCF or BCF format, but not the textual pileup
output. The \fBmpileup\fP command was transferred to bcftools in order to
avoid errors resulting from use of incompatible versions of samtools
and bcftools when using in the mpileup+bcftools call pipeline.
.sp
Individuals are identified from the SM tags in the @RG header lines.  Multiple
individuals can be pooled in one alignment file, also one individual can be
separated into multiple files.  If sample identifiers are absent, each input
file is regarded as one sample.
.sp
Note that there are two orthogonal ways to specify locations in the
input file; via \fB\-r\fP \fIregion\fP and \fB\-t\fP \fIpositions\fP.  The
former uses (and requires) an index to do random access while the
latter streams through the file contents filtering out the specified
regions, requiring no index.  The two may be used in conjunction.  For
example a BED file containing locations of genes in chromosome 20
could be specified using \fB\-r 20 \-t chr20.bed\fP, meaning that the
index is used to find chromosome 20 and then it is filtered for the
regions listed in the BED file. Also note that the \fB\-r\fP option can be much
slower than \fB\-t\fP with many regions and can require more memory when
multiple regions and many alignment files are processed.
.SS "Input options"
.sp
\fB\-6, \-\-illumina1.3+\fP
.RS 4
Assume the quality is in the Illumina 1.3+ encoding.
.RE
.sp
\fB\-A, \-\-count\-orphans\fP
.RS 4
Include anomalous read pairs in variant calling, i.e. reads with
flag PAIRED but not PROPER_PAIR set. By default such reads are discarded.
.RE
.sp
\fB\-b, \-\-bam\-list\fP \fIFILE\fP
.RS 4
List of input alignment files, one file per line [null]
.RE
.sp
\fB\-B, \-\-no\-BAQ\fP
.RS 4
Disable probabilistic realignment for the computation of base alignment
quality (BAQ). BAQ is the Phred\-scaled probability of a read base being
misaligned. Applying this option greatly helps to reduce false SNPs caused
by misalignments.
.RE
.sp
\fB\-C, \-\-adjust\-MQ\fP \fIINT\fP
.RS 4
Coefficient for downgrading mapping quality for reads containing
excessive mismatches.  Mismatches are counted as a proportion of the
number of aligned bases ("M", "X" or "=" CIGAR operations), along with
their quality, to derive an upper\-bound of the mapping quality.
Original mapping qualities lower than this are left intact, while
higher ones are capped at the new adjusted score.
.sp
The exact formula is complex and likely tuned to specific instruments
and specific alignment tools, so this option is disabled by default
(indicated as having a zero value).  Variables in the formulae and
their meaning are defined below.
.sp
.if n .RS 4
.nf
.fam C
Variable    Meaning / formula
M           The number of matching CIGAR bases (operation "M", "X" or "=").
X           The number of substitutions with quality >= 13.
SubQ        The summed quality of substitution bases included in X, capped
            at a maximum of quality 33 per mismatching base.
ClipQ       The summed quality of soft\-clipped or hard\-clipped bases. This
            has no minimum or maximum quality threshold per base.  For
            hard\-clipped bases the per\-base quality is taken as 13.

T           SubQ \- 10 * log10(M^X / X!) + ClipQ/5
Cap         MAX(0, INT * sqrt((INT \- T) / INT))
.fam
.fi
.if n .RE
.sp
Some notes on the impact of this.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
As the number of mismatches increases, the mapping quality cap
reduces, eventually resulting in discarded alignments.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
High quality mismatches reduces the cap faster than low quality
mismatches.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The starting INT value also acts as a hard cap on mapping quality,
even when zero mismatches are observed.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Indels have no impact on the mapping quality.
.sp
The intent of this option is to work around aligners that compute a
mapping quality using a local alignment without having any regard to
the degree of clipping required or consideration of potential
contamination or large scale insertions with respect to the reference.
A record may align uniquely and have no close second match, but having
a high number of mismatches may still imply that the reference is not
the correct site.
.sp
However we do not recommend use of this parameter unless you fully
understand the impact of it and have determined that it is appropriate
for your sequencing technology.
.RE
.RE
.sp
\fB\-D, \-\-full\-BAQ\fP
.RS 4
Run the BAQ algorithm on all reads, not just those in problematic
regions.  This matches the behaviour for Bcftools 1.12 and earlier.
.sp
By default mpileup uses heuristics to decide when to apply the BAQ
algorithm.  Most sequences will not be BAQ adjusted, giving a CPU
time closer to \-\-no\-BAQ, but it will still be applied in regions
with suspected problematic alignments.  This has been tested to
work well on single sample data with even allele frequency, but
the reliability is unknown for multi\-sample calling and for low
allele frequency variants so full BAQ is still recommended in
those scenarios.
.RE
.sp
\fB\-d, \-\-max\-depth\fP \fIINT\fP
.RS 4
At a position, read maximally \fIINT\fP reads per input file. Note that
the original \fBsamtools mpileup\fP command had a minimum value of \fI8000/n\fP
where \fIn\fP was the number of input files given to mpileup. This means that
in \fBsamtools mpileup\fP the default was highly likely to be increased and the
\fB\-d\fP parameter would have an effect only once above the cross\-sample minimum of 8000.
This behavior was problematic when working with a combination of
single\- and multi\-sample bams, therefore in \fBbcftools mpileup\fP the user
is given the full control (and responsibility), and an informative message
is printed instead [250]
.RE
.sp
\fB\-E, \-\-redo\-BAQ\fP
.RS 4
Recalculate BAQ on the fly, ignore existing BQ tags
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIFILE\fP
.RS 4
The \fBfaidx\fP\-indexed reference file in the FASTA format. The file can be
optionally compressed by \fBbgzip\fP. Reference is required by default
unless the \fB\-\-no\-reference\fP option is set [null]
.RE
.sp
\fB\-\-no\-reference\fP
.RS 4
Do not require the \fB\-\-fasta\-ref\fP option.
.RE
.sp
\fB\-G, \-\-read\-groups\fP \fIFILE\fP
.RS 4
list of read groups to include or exclude if prefixed with "^".
One read group per line.  This file can also be used to assign new sample
names to read groups by giving the new sample name as a second
white\-space\-separated field, like this: "read_group_id new_sample_name".
If the read group name is not unique, also the bam file name can
be included: "read_group_id file_name sample_name".  If all
reads from the alignment file should be treated as a single sample, the
asterisk symbol can be used: "* file_name sample_name". Alignments without
a read group ID can be matched with "?". \fBNOTE:\fP The meaning of \fBbcftools mpileup \-G\fP
is the opposite of \fBsamtools mpileup \-G\fP.
.RE
.sp
.if n .RS 4
.nf
.fam C
    RG_ID_1
    RG_ID_2  SAMPLE_A
    RG_ID_3  SAMPLE_A
    RG_ID_4  SAMPLE_B
    RG_ID_5  FILE_1.bam  SAMPLE_A
    RG_ID_6  FILE_2.bam  SAMPLE_A
    *        FILE_3.bam  SAMPLE_C
    ?        FILE_3.bam  SAMPLE_D
.fam
.fi
.if n .RE
.sp
\fB\-\-indels\-2.0\fP
.RS 4
A new EXPERIMENTAL indel calling model which aims to address some known deficiencies of
the current indel calling algorithm. Specifically, it uses diploid reference consensus
sequence. Note that in the current version it has the potential to increase sensitivity
but at the cost of decreased specificity.
Only works with short\-read sequencing technologies.
.RE
.sp
\fB\-\-indels\-cns\fP
.RS 4
Another EXPERIMENTAL indel calling method, predating indels\-2.0 in
PR form, but merged more recently.  It also uses a diploid
reference consensus, but with added parameters and heuristics to
optimise for a variety of sequencing platforms.  This is usually
faster and more accurate than the default caller and \-\-indels\-2.0,
but has not been tested on non\-diploid samples and samples without
approximately even allele frequency.
.RE
.sp
\fB\-\-no\-indels\-cns\fP
.RS 4
May be used to turn off \-\-indels\-cns mode when using one of the
newer profiles that has this enabled by default.
.RE
.sp
\fB\-q, \-min\-MQ\fP \fIINT\fP
.RS 4
Minimum mapping quality for an alignment to be used [0]
.RE
.sp
\fB\-Q, \-\-min\-BQ\fP \fIINT\fP
.RS 4
Minimum base quality for a base to be considered [13]
.RE
.sp
\fB\-\-max\-BQ\fP \fIINT\fP
.RS 4
Caps the base quality to a maximum value [60].  This can be
particularly useful on technologies that produce overly optimistic
high qualities, leading to too many false positives or incorrect
genotype assignments.
.RE
.sp
\fB\-r, \-\-regions\fP \fICHR\fP|\fICHR:POS\fP|\fICHR:FROM\-TO\fP|\fICHR:FROM\-\fP[,...]
.RS 4
Only generate mpileup output in given regions. Requires the alignment files
to be indexed.  If used in conjunction with \-l then considers the intersection;
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIFILE\fP
.RS 4
As for \fB\-r, \-\-regions\fP, but regions read from FILE;
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-ignore\-RG\fP
.RS 4
Ignore RG tags. Treat all reads in one alignment file as one sample.
.RE
.sp
\fB\-\-ls, \-\-skip\-all\-set\fP
.RS 4
Skip reads with all of the FLAG bits set [null]
.RE
.sp
\fB\-\-ns, \-\-skip\-any\-set\fP
.RS 4
Skip reads with any of the FLAG bits set. This option replaces and
is synonymous to the deprecated \fB\-\-ff, \-\-excl\-flags\fP [UNMAP,SECONDARY,QCFAIL,DUP]
.RE
.sp
\fB\-\-lu, \-\-skip\-all\-unset\fP
.RS 4
Skip reads with all of the FLAG bits unset. This option replaces and
is synonymous to the deprecated \fB\-\-rf, \-\-incl\-flags\fP [null]
.RE
.sp
\fB\-\-nu, \-\-skip\-any\-unset\fP
.RS 4
Skip reads with any of the FLAG bits unset [null]
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
list of sample names. See \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
file of sample names to include or exclude if prefixed with "^".
One sample per line. This file can also be used to rename samples by giving
the new sample name as a second white\-space\-separated column, like this:
"old_name new_name".  If a sample name contains spaces, the spaces can be
escaped using the backslash character, for example "Not\(rs a\(rs good\(rs sample\(rs
name".
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-x, \-\-ignore\-overlaps\fP
.RS 4
Disable read\-pair overlap detection.
.RE
.sp
\fB\-\-seed\fP \fIINT\fP
.RS 4
Set the random number seed used when sub\-sampling deep regions [0].
.RE
.SS "Output options"
.sp
\fB\-a, \-\-annotate\fP \fILIST\fP
.RS 4
Comma\-separated list of FORMAT and INFO tags to output. (case\-insensitive,
the "FORMAT/" prefix is optional, and use "?" to list available annotations
on the command line) [null]:
.RE
.sp
.if n .RS 4
.nf
.fam C
FORMAT/AD   .. Allelic depth (Number=R,Type=Integer)
FORMAT/ADF  .. Allelic depths on the forward strand (Number=R,Type=Integer)
FORMAT/ADR  .. Allelic depths on the reverse strand (Number=R,Type=Integer)
FORMAT/DP   .. Number of high\-quality bases (Number=1,Type=Integer)
FORMAT/SP   .. Phred\-scaled strand bias P\-value (Number=1,Type=Integer)
FORMAT/SCR  .. Number of soft\-clipped reads (Number=1,Type=Integer)

INFO/AD     .. Total allelic depth (Number=R,Type=Integer)
INFO/ADF    .. Total allelic depths on the forward strand (Number=R,Type=Integer)
INFO/ADR    .. Total allelic depths on the reverse strand (Number=R,Type=Integer)
INFO/SCR    .. Number of soft\-clipped reads (Number=1,Type=Integer)

FORMAT/DV   .. Deprecated in favor of FORMAT/AD; Number of high\-quality non\-reference bases, (Number=1,Type=Integer)
FORMAT/DP4  .. Deprecated in favor of FORMAT/ADF and FORMAT/ADR; Number of high\-quality ref\-forward, ref\-reverse,
               alt\-forward and alt\-reverse bases (Number=4,Type=Integer)
FORMAT/DPR  .. Deprecated in favor of FORMAT/AD; Number of high\-quality bases for each observed allele (Number=R,Type=Integer)
INFO/DPR    .. Deprecated in favor of INFO/AD; Number of high\-quality bases for each observed allele (Number=R,Type=Integer)
.fam
.fi
.if n .RE
.sp
\fB\-g, \-\-gvcf\fP \fIINT\fP[,...]
.RS 4
output gVCF blocks of homozygous REF calls, with depth (DP) ranges
specified by the list of integers. For example, passing \fI5,15\fP will
group sites into two types of gVCF blocks, the first with minimum
per\-sample DP from the interval [5,15) and the latter with minimum
depth 15 or more. In this example, sites with minimum per\-sample
depth less than 5 will be printed as separate records, outside of
gVCF blocks.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
Write output to \fIFILE\fP, rather than the default of standard output.
(The same short option is used for both \fB\-\-open\-prob\fP and \fB\-\-output\fP.  If \fB\-o\fP\*(Aqs
argument contains any non\-digit characters other than a leading + or \-
sign,  it  is  interpreted  as \fB\-\-output\fP.  Usually the filename extension
will take care of this, but to write to an entirely numeric filename use \fB\-o
\&./123\fP or \fB\-\-output 123\fP.)
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-U, \-\-mwu\-u\fP
.RS 4
The the previous Mann\-Whitney U test score from version 1.12 and
earlier.  This is a probability score, but importantly it folds
probabilities above or below the desired score into the same P.
The new Mann\-Whitney U test score is a "Z score", expressing the
score as the number of standard deviations away from the mean (with
zero being matching the mean).  It keeps both positive and
negative values.  This can be important for some tests where
errors are asymmetric.
.sp
.if n .RS 4
.nf
.fam C
This option changes the INFO field names produced back to the ones
used by the earlier Bcftools releases.  For excample BQBZ becomes
BQB.
.fam
.fi
.if n .RE
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "Options for SNP/INDEL genotype likelihood computation"
.sp
\fB\-X, \-\-config\fP \fISTR\fP
.RS 4
Specify a platform specific configuration profile.  Specifying the
profile as "list" will list the available profile names and the
parameters they change.  There are profiles named after a release,
which should be used if you wish to ensure forward compatibility
of results.  The non\-versioned names (eg "illumina") will always
point to the most recent set of parameters for that instrument type.
The current values are:
.sp
.if n .RS 4
.nf
.fam C
1.12            \-Q13 \-h100 \-m1
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
bgi
bgi\-1.20        \-\-indels\-cns \-B \-\-indel\-size 80 \-F0.1 \-\-indel\-bias 0.9
                \-\-seqq\-offset 120
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
illumina\-1.18   [ default values ]
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
illumina
illumina\-1.20   \-\-indels\-cns \-\-seqq\-offset 125
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
ont             \-B \-Q5 \-\-max\-BQ 30 \-I
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
ont\-sup
ont\-sup\-1.20    \-\-indels\-cns \-B \-Q1 \-\-max\-BQ 35 \-\-delta\-BQ 99 \-F0.2
                \-o15 \-e1 \-h110 \-\-del\-bias 0.4 \-\-indel\-bias 0.7
                \-\-poly\-mqual \-\-seqq\-offset 130 \-\-indel\-size 80
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
pacbio\-ccs\-1.18 \-D \-Q5 \-\-max\-BQ 50 \-F0.1 \-o25 \-e1 \-M99999
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
pacbio\-ccs
pacbio\-ccs\-1.20  \-\-indels\-cns \-B \-Q5 \-\-max\-BQ 50 \-F0.1 \-o25 \-e1 \-h300
                 \-\-delta\-BQ 10 \-\-del\-bias 0.4 \-\-poly\-mqual
                 \-\-indel\-bias 0.9 \-\-seqq\-offset 118 \-\-indel\-size 80
                 \-\-score\-vs\-ref 0.7
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
ultima
ultima\-1.20      \-\-indels\-cns \-B \-Q1 \-\-max\-BQ 30 \-\-delta\-BQ 10 \-F0.15
                 \-o20 \-e10 \-h250 \-\-del\-bias 0.3 \-\-indel\-bias 0.7
                 \-\-poly\-mqual \-\-seqq\-offset 140 \-\-score\-vs\-ref 0.3
                 \-\-indel\-size 80
.fam
.fi
.if n .RE
.RE
.sp
\fB\-\-ar, \-\-ambig\-reads\fP \fIdrop\fP|\fIincAD\fP|\fIincAD0\fP
.RS 4
What to do with ambiguous indel reads that do not span an entire
short tandem repeat region: discard ambiguous reads from calling
and do not increment high\-quality AD depth counters (\fIdrop\fP),
exclude from calling but increment AD counters proportionally (\fIincAD\fP),
exclude from calling and increment the first value of the AD counter
(\fIincAD0\fP) [\fIdrop\fP]
.RE
.sp
\fB\-e, \-\-ext\-prob\fP \fIINT\fP
.RS 4
Phred\-scaled gap extension sequencing error probability. Reducing \fIINT\fP
leads to longer indels [20]
.RE
.sp
\fB\-F, \-\-gap\-frac\fP \fIFLOAT\fP
.RS 4
Minimum fraction of gapped reads [0.002]
.RE
.sp
\fB\-h, \-\-tandem\-qual\fP \fIINT\fP
.RS 4
Coefficient for modeling homopolymer errors. Given an \fIl\fP\-long homopolymer
run, the sequencing error of an indel of size s is modeled as \fIINT\fP*s/l [500]
Increasing this informs the caller that indels in long
homopolymers are more likely genuine and less likely to be
sequencing artifacts.  Hence increasing tandem\-qual will have
higher recall and lower precision.  Bcftools 1.12 and earlier had
a default of 100, which was tuned around more error prone instruments.
Note changing this may have a minor impact on SNP calling too.
For maximum SNP calling accuracy, it may be preferable to adjust
this lower again, although this will adversely affect indels.
.RE
.sp
\fB\-\-indel\-bias\fP \fIFLOAT\fP
.RS 4
Skews the indel scores up or down, trading recall (low
false\-negative) vs precision (low false\-positive) [1.0].  In Bcftools
1.12 and earlier this parameter didn\(cqt exist, but had an implied
value of 1.0.  If you are planning to do heavy filtering of
variants, selecting the best quality ones only (favouring
precision over recall), it is advisable to set this lower (such as
0.75) while higher depth samples or where you favour recall rates
over precision may work better with a higher value such as 2.0.
.RE
.sp
\fB\-\-del\-bias\fP \fIFLOAT\fP
.RS 4
Skews the likelihood of deletions over insertions.  Defaults to an
even distribution value of 1.0.  Lower values imply a higher rate
of false positive deletions (meaning candidate deletions are less
likely to be real).
.RE
.sp
\fB\-\-indel\-size\fP \fIINT\fP
.RS 4
Indel window size to use when assessing the quality of candidate indels.
Note that although the window size approximately corresponds to the maximum
indel size considered, it is not an exact threshold [110]
.RE
.sp
\fB\-\-seqq\-offset\fP \fIINT\fP
.RS 4
Tunes the importance of indel sequence quality per depth.  The
final "seqQ" quality used is "offset \- 5*MIN(depth,20)". [120]
.RE
.sp
\fB\-\-poly\-mqual\fP
.RS 4
Use the lowest quality value within a homopolymer run, instead of
the quality immediately adjacent to the indel.  This may be
important for unclocked instruments, particularly ones with a flow
chemistry where runs of bases of identical type are incorporated
together.
.RE
.sp
\fB\-I, \-\-skip\-indels\fP
.RS 4
Do not perform INDEL calling
.RE
.sp
\fB\-L, \-\-max\-idepth\fP \fIINT\fP
.RS 4
Skip INDEL calling if the average per\-sample depth is above \fIINT\fP [250]
.RE
.sp
\fB\-m, \-\-min\-ireads\fP \fIINT\fP
.RS 4
Minimum number gapped reads for indel candidates \fIINT\fP [1]
.RE
.sp
\fB\-M, \-\-max\-read\-len\fP \fIINT\fP
.RS 4
The maximum read length permitted by the BAQ algorithm [500].
Variants are still called on longer reads, but they will not be
passed through the BAQ method.  This limit exists to prevent
excessively long BAQ times and high memory usage.  Note if partial
BAQ is enabled with \fI\-D\fP then raising this parameter will likely
not have a significant a CPU cost.
.RE
.sp
\fB\-o, \-\-open\-prob\fP \fIINT\fP
.RS 4
Phred\-scaled gap open sequencing error probability. Reducing \fIINT\fP leads
to more indel calls. (The same short option is used for both \fB\-\-open\-prob\fP
and \fB\-\-output\fP.  When \-o\(cqs argument contains only an optional + or \- sign
followed by the digits 0 to 9, it is interpreted  as \fB\-\-open\-prob\fP.) [40]
.RE
.sp
\fB\-p, \-\-per\-sample\-mF\fP
.RS 4
Apply \fB\-m\fP and \fB\-F\fP thresholds per sample to increase sensitivity of calling.
By default both options are applied to reads pooled from all samples.
.RE
.sp
\fB\-P, \-\-platforms\fP \fISTR\fP
.RS 4
Comma\-delimited  list  of  platforms (determined by \fB@RG\-PL\fP) from which
indel candidates are obtained. It is recommended to collect indel
candidates from sequencing technologies that have low indel error rate
such as ILLUMINA [all]
.RE
.SS "Examples:"
.sp
Call SNPs and short INDELs, then mark low quality sites and sites with the read
depth exceeding a limit. (The read depth should be adjusted to about twice the
average read depth as higher read depths usually indicate problematic regions
which are often enriched for artefacts.) One may consider to add \fB\-C50\fP to
mpileup if mapping quality is overestimated  for reads containing  excessive
mismatches.  Applying this option usually helps for BWA\-backtrack alignments,
but may not other aligners.
.sp
.if n .RS 4
.nf
.fam C
    bcftools mpileup \-Ou \-f ref.fa aln.bam | \(rs
    bcftools call \-Ou \-mv | \(rs
    bcftools filter \-s LowQual \-e \*(AqQUAL<20 || DP>100\*(Aq > var.flt.vcf
.fam
.fi
.if n .RE
.SS "bcftools norm [\fIOPTIONS\fP] \fIfile.vcf.gz\fP"
.sp
Left\-align and normalize indels, check if REF alleles match the reference,
split multiallelic sites into multiple rows; recover multiallelics from
multiple rows. Left\-alignment and normalization will only be applied if
the \fB\-\-fasta\-ref\fP option is supplied.
.sp
\fB\-a, \-\-atomize\fP
.RS 4
Decompose complex variants, e.g. split MNVs into consecutive SNVs.
See also \fB\-\-atom\-overlaps\fP and \fB\-\-old\-rec\-tag\fP.
.RE
.sp
\fB\-\-atom\-overlaps\fP \fI.\fP|\fI*\fP
.RS 4
Alleles missing because of an overlapping variant can be set either
to missing (.) or to the star alele (*), as recommended by
the VCF specification. IMPORTANT: Note that asterisk is expaneded
by shell and must be put in quotes or escaped by a backslash:
.RE
.sp
.if n .RS 4
.nf
.fam C
    # Before atomization:
    100  CC  C,GG   1/2

    # After:
    #   bcftools norm \-a \-\-atom\-overlaps .
    100         C         G      ./1
    100         CC         C      1/.
    101         C         G      ./1

    # After:
    #   bcftools norm \-a \-\-atom\-overlaps \*(Aq*\*(Aq
    #   bcftools norm \-a \-\-atom\-overlaps \(rs*
    100         C         G,*    2/1
    100         CC         C,*    1/2
    101         C         G,*    2/1
.fam
.fi
.if n .RE
.sp
\fB\-c, \-\-check\-ref\fP \fIe\fP|\fIw\fP|\fIx\fP|\fIs\fP
.RS 4
what to do when incorrect or missing REF allele is encountered:
exit (\fIe\fP), warn (\fIw\fP), exclude (\fIx\fP), or set/fix (\fIs\fP) bad sites.
The \fIw\fP option can be combined with \fIx\fP and \fIs\fP. Note that \fIs\fP
can swap alleles and will update genotypes (GT) and AC counts,
but will not attempt to fix PL or other fields. Also note, and this
cannot be stressed enough, that \fIs\fP will NOT fix strand issues in
your VCF, do NOT use it for that purpose!!! (Instead see
.URL "http://samtools.github.io/bcftools/howtos/plugin.af\-dist.html" "" ""
and
\c
.URL "http://samtools.github.io/bcftools/howtos/plugin.fixref.html" "" ".)"
.RE
.sp
\fB\-d, \-\-rm\-dup\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIexact\fP
.RS 4
If a record is present multiple times, output only the first instance.
See also \fB\-\-collapse\fP in \fBCommon Options\fP.
.RE
.sp
\fB\-D, \-\-remove\-duplicates\fP
.RS 4
If a record is present in multiple files, output only the first instance.
Alias for \fB\-d exact\fP, deprecated.
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
do not normalize input records for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP. Note that duplicate removal ignores this option.
.RE
.sp
\fB\-f, \-\-fasta\-ref\fP \fIFILE\fP
.RS 4
reference sequence. Supplying this option will turn on left\-alignment
and normalization, however, see also the \fB\-\-do\-not\-normalize\fP
option below.
.RE
.sp
\fB\-\-force\fP
.RS 4
try to proceed with \fB\-m\-\fP even if malformed tags with incorrect number of fields
are encountered, discarding such tags. (Experimental, use at your own risk.)
.RE
.sp
\fB\-g, \-\-gff\-annot\fP \fIFILE\fP
.RS 4
when a GFF file is provided, follow HGVS 3\(cqrule and right\-align variants in transcripts on the forward
strand.  In case of overlapping transcripts, the default mode is to left\-align the variant. For a
description of the supported GFF3 file format see \fBbcftools csq\fP.
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
normalize only input records for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP. Note that duplicate removal ignores this option.
.RE
.sp
\fB\-\-keep\-sum\fP \fITAG\fP[,...]
.RS 4
keep vector sum constant when splitting multiallelic sites. Only AD tag
is currently supported. See also \c
.URL "https://github.com/samtools/bcftools/issues/360" "" ""
.RE
.sp
\fB\-m, \-\-multiallelics\fP \fB\-\fP|\fB+\fP[\fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIany\fP]
.RS 4
split multiallelic sites into biallelic records (\fB\-\fP) or join
biallelic sites into multiallelic records (\fB+\fP). An optional type string
can follow which controls variant types which should be split or merged
together: If only SNP records should be split or merged, specify \fIsnps\fP; if
both SNPs and indels should be merged separately into two records, specify
\fIboth\fP; if SNPs and indels should be merged into a single record, specify
\fIany\fP.
\~
.br
\~
.br
Note that multiallelic sites with both SNPs and indels will be split into
biallelic sites with both \fB\-m \-snps\fP and \fB\-m \-indels\fP.
.RE
.sp
\fB\-\-multi\-overlaps\fP \fI0\fP|\fI.\fP
.RS 4
use the reference (\fI0\fP) or missing (\fI.\fP) allele for overlapping alleles after
splitting multiallelic sites
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-N, \-\-do\-not\-normalize\fP
.RS 4
the \fI\-c s\fP option can be used to fix or set the REF allele from the
reference \fI\-f\fP. The \fI\-N\fP option will not turn on indel normalisation
as the \fI\-f\fP option normally implies
.RE
.sp
\fB\-\-old\-rec\-tag\fP \fISTR\fP
.RS 4
Add INFO/STR annotation with the original record. The format of the
annotation is CHROM|POS|REF|ALT|USED_ALT_IDX.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-strict\-filter\fP
.RS 4
when merging (\fI\-m+\fP), merged site is PASS only if all sites being merged PASS
.RE
.sp
\fB\-S, \-\-sort\fP \fIpos\fP|\fIlex\fP
.RS 4
when splitting sites or processing duplicates, sort records on output by
POS only (\fIpos\fP, the default) or by POS and lexicographically by REF+ALT (\fIlex\fP)
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-w, \-\-site\-win\fP \fIINT\fP
.RS 4
maximum distance between two records to consider when locally
sorting variants which changed position during the realignment
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "bcftools [plugin \fINAME\fP|+\fINAME\fP] \fI[OPTIONS]\fP \fIFILE\fP \(em \fI[PLUGIN OPTIONS]\fP"
.sp
A common framework for various utilities. The plugins can be used
the same way as normal commands only their name is prefixed with "+".
Most plugins accept two types of parameters: general options shared by all
plugins followed by a separator, and a list of plugin\-specific options.  There
are some exceptions to this rule, some plugins do not accept the common
options and implement their own parameters. Therefore please pay attention to
the usage examples that each plugin comes with.
.SS "VCF input options:"
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "VCF output options:"
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "Plugin options:"
.sp
\fB\-h, \-\-help\fP
.RS 4
list plugin\(cqs options
.RE
.sp
\fB\-l, \-\-list\-plugins\fP
.RS 4
List all available plugins.
.sp
By default, appropriate system directories are searched for installed plugins.
You can override this by setting the BCFTOOLS_PLUGINS environment variable
to a colon\-separated list of directories to search.
If BCFTOOLS_PLUGINS begins with a colon, ends with a colon, or contains
adjacent colons, the system directories are also searched at that position
in the list of directories.
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-V, \-\-version\fP
.RS 4
print version string and exit
.RE
.SS "List of plugins coming with the distribution:"
.sp
\fBad\-bias\fP
.RS 4
find positions with wildly varying ALT allele frequency (Fisher test on FMT/AD)
.RE
.sp
\fBadd\-variantkey\fP
.RS 4
add VariantKey INFO fields VKX and RSX
.RE
.sp
\fBaf\-dist\fP
.RS 4
collect AF deviation stats and GT probability distribution given AF and assuming HWE
.RE
.sp
\fBvrfs\fP
.RS 4
assess site noisiness (variant read frequency score) from a large number of unaffected parental samples
.RE
.sp
\fBallele\-length\fP
.RS 4
count the frequency of the length of REF, ALT and REF+ALT
.RE
.sp
\fBcheck\-ploidy\fP
.RS 4
check if ploidy of samples is consistent for all sites
.RE
.sp
\fBcheck\-sparsity\fP
.RS 4
print samples without genotypes in a region or chromosome
.RE
.sp
\fBcolor\-chrs\fP
.RS 4
color shared chromosomal segments, requires trio VCF with phased GTs
.RE
.sp
\fBcontrast\fP
.RS 4
runs a basic association test, per\-site or in a region, and checks for novel alleles and
genotypes in two groups of samples. Adds the following INFO annotations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
PASSOC  .. Fisher\(cqs exact test probability of genotypic association (REF vs non\-REF allele)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
FASSOC  .. proportion of non\-REF allele in controls and cases
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
NASSOC  .. number of control\-ref, control\-alt, case\-ref and case\-alt alleles
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
NOVELAL .. lists samples with a novel allele not observed in the control group
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
NOVELGT .. lists samples with a novel genotype not observed in the control group
.RE
.RE
.sp
\fBcounts\fP
.RS 4
a minimal plugin which counts number of SNPs, Indels, and total number of sites.
.RE
.sp
\fBdosage\fP
.RS 4
print genotype dosage. By default the plugin searches for PL, GL and GT, in
that order.
.RE
.sp
\fBfill\-from\-fasta\fP
.RS 4
fill INFO or REF field based on values in a fasta file
.RE
.sp
\fBfill\-tags\fP
.RS 4
set various INFO tags. The list of tags supported in this version:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AC         Number:A  Type:Integer  ..  Allele count in genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AC_Hom     Number:A  Type:Integer  ..  Allele counts in homozygous genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AC_Het     Number:A  Type:Integer  ..  Allele counts in heterozygous genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AC_Hemi    Number:A  Type:Integer  ..  Allele counts in hemizygous genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AF         Number:A  Type:Float    ..  Allele frequency
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/AN         Number:1  Type:Integer  ..  Total number of alleles in called genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/ExcHet     Number:A  Type:Float    ..  Test excess heterozygosity; 1=good, 0=bad
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/END        Number:1  Type:Integer  ..  End position of the variant
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/F_MISSING  Number:1  Type:Float    ..  Fraction of missing genotypes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/HWE        Number:A  Type:Float    ..  HWE test (PMID:15789306); 1=good, 0=bad
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/MAF        Number:A  Type:Float    ..  Minor Allele frequency
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/NS         Number:1  Type:Integer  ..  Number of samples with data
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO/TYPE       Number:.  Type:String   ..  The record type (REF,SNP,MNP,INDEL,etc)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
FORMAT/VAF      Number:A  Type:Float    ..  The fraction of reads with the alternate allele, requires FORMAT/AD or ADF+ADR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
FORMAT/VAF1     Number:1  Type:Float    ..  The same as FORMAT/VAF but for all alternate alleles cumulatively
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
TAG=func(TAG)   Number:1  Type:Integer  ..  Experimental support for user\-defined expressions such as "DP=sum(DP)"
.RE
.RE
.sp
\fBfixploidy\fP
.RS 4
sets correct ploidy
.RE
.sp
\fBfixref\fP
.RS 4
determine and fix strand orientation
.RE
.sp
\fBframeshifts\fP
.RS 4
annotate frameshift indels
.RE
.sp
\fBGTisec\fP
.RS 4
count genotype intersections across all possible sample subsets in a vcf file
.RE
.sp
\fBGTsubset\fP
.RS 4
output only sites where the requested samples all exclusively share a genotype
.RE
.sp
\fBguess\-ploidy\fP
.RS 4
determine sample sex by checking genotype likelihoods (GL,PL) or genotypes (GT)
in the non\-PAR region of chrX.
.RE
.sp
\fBgvcfz\fP
.RS 4
compress gVCF file by resizing non\-variant blocks according to specified criteria
.RE
.sp
\fBimpute\-info\fP
.RS 4
add imputation information metrics to the INFO field based on selected FORMAT tags
.RE
.sp
\fBindel\-stats\fP
.RS 4
calculates per\-sample or de novo indels stats. The usage and format is similar
to \fBsmpl\-stats\fP and \fBtrio\-stats\fP
.RE
.sp
\fBisecGT\fP
.RS 4
compare two files and set non\-identical genotypes to missing
.RE
.sp
\fBmendelian\fP
.RS 4
count Mendelian consistent / inconsistent genotypes (deprecated, use +mendelian2 instead)
.RE
.sp
\fBmendelian2\fP
.RS 4
count Mendelian consistent / inconsistent genotypes.
.RE
.sp
\fBmissing2ref\fP
.RS 4
sets missing genotypes ("./.") to ref allele ("0/0" or "0|0")
.RE
.sp
\fBparental\-origin\fP
.RS 4
determine parental origin of a CNV region
.RE
.sp
\fBprune\fP
.RS 4
annotate sites with or prune sites by the number of variants within a window, Lewontin\(cqs D
(doi:10.1093/molbev/msz265), Ragsdale\(cqs D (doi:10.1534/genetics.108.093153), or correlation
coefficient r\-squared.
.RE
.sp
\fBremove\-overlaps\fP
.RS 4
remove overlapping variants and duplicate sites
.RE
.sp
\fBscatter\fP
.RS 4
intended as an inverse to \f(CRbcftools concat\fP, scatter VCF by chunks or regions, creating multiple VCFs.
.RE
.sp
\fBsetGT\fP
.RS 4
general tool to set genotypes according to rules requested by the user
.RE
.sp
\fBsmpl\-stats\fP
.RS 4
calculates basic per\-sample stats. The usage and format is similar to
\fBindel\-stats\fP and \fBtrio\-stats\fP.
.RE
.sp
\fBsplit\fP
.RS 4
split VCF by sample, creating single\- or multi\-sample VCFs
.RE
.sp
\fBsplit\-vep\fP
.RS 4
extract fields from structured annotations such as INFO/CSQ created by VEP or INFO/BCSQ created by
bcftools/csq. These can be added as a new INFO field to the VCF or in a custom text format. See
.URL "http://samtools.github.io/bcftools/howtos/plugin.split\-vep.html" "" ""
for more.
.RE
.sp
\fBtag2tag\fP
.RS 4
Convert between similar tags, such as GL,PL,GP or QR,QA,QS or tags with localized alleles e.g. LPL,LAD.
See \c
.URL "http://samtools.github.io/bcftools/howtos/plugin.tag2tag.html" "" ""
for more.
.RE
.sp
\fBtrio\-dnm2\fP
.RS 4
screen variants for possible de\-novo mutations in trios
.RE
.sp
\fBtrio\-stats\fP
.RS 4
calculate transmission rate in trio children. The usage and format is similar to
\fBindel\-stats\fP and \fBsmpl\-stats\fP.
.RE
.sp
\fBtrio\-switch\-rate\fP
.RS 4
calculate phase switch rate in trio samples, children samples must have phased GTs
.RE
.sp
\fBvariant\-distance\fP
.RS 4
annotate sites with the distance to the nearest variant
.RE
.sp
\fBvariantkey\-hex\fP
.RS 4
generate unsorted VariantKey\-RSid index files in hexadecimal format
.RE
.sp
\fBvcf2table\fP
.RS 4
print the variants as a set of tables
.RE
.SS "Examples:"
.sp
.if n .RS 4
.nf
.fam C
# List options common to all plugins
bcftools plugin

# List available plugins
bcftools plugin \-l

# Run a plugin
bcftools plugin counts in.vcf

# Run a plugin using the abbreviated "+" notation
bcftools +counts in.vcf

# Run a plugin from an explicit location
bcftools +/path/to/counts.so in.vcf

# The input VCF can be streamed just like in other commands
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
.fam
.fi
.if n .RE
.SS "Plugins troubleshooting:"
.sp
Things to check if your plugin does not show up in the \fBbcftools plugin \-l\fP output:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Run with the \fB\-v\fP option for verbose output: \fBbcftools plugin \-lv\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Does the environment variable BCFTOOLS_PLUGINS include the correct path?
.RE
.SS "Plugins API:"
.sp
.if n .RS 4
.nf
.fam C
// Short description used by \*(Aqbcftools plugin \-l\*(Aq
const char *about(void);

// Longer description used by \*(Aqbcftools +name \-h\*(Aq
const char *usage(void);

// Called once at startup, allows initialization of local variables.
// Return 1 to suppress normal VCF/BCF header output, \-1 on critical
// errors, 0 otherwise.
int init(int argc, char **argv, bcf_hdr_t *in_hdr, bcf_hdr_t *out_hdr);

// Called for each VCF record, return NULL to suppress the output
bcf1_t *process(bcf1_t *rec);

// Called after all lines have been processed to clean up
void destroy(void);
.fam
.fi
.if n .RE
.SS "bcftools polysomy [\fIOPTIONS\fP] \fIfile.vcf.gz\fP"
.sp
Detect number of chromosomal copies in VCFs annotates with the Illumina\(cqs
B\-allele frequency (BAF) values. Note that this command is not compiled
in by default, see the section \fBOptional Compilation with GSL\fP in the INSTALL
file for help.
.SS "General options:"
.sp
\fB\-o, \-\-output\-dir\fP \fIpath\fP
.RS 4
output directory
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-sample\fP \fIstring\fP
.RS 4
sample name
.RE
.sp
\fB\-t, \-\-targets\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
verbose debugging output which gives hints about the thresholds and decisions made
by the program. Note that the exact output can change between versions.
See also \fBCommon Options\fP
.RE
.SS "Algorithm options:"
.sp
\fB\-b, \-\-peak\-size\fP \fIfloat\fP
.RS 4
the minimum peak size considered as a good match can be from the interval [0,1]
where larger is stricter
.RE
.sp
\fB\-c, \-\-cn\-penalty\fP \fIfloat\fP
.RS 4
a penalty for increasing copy number state. How this works: multiple peaks
are always a better fit than a single peak, therefore the program prefers
a single peak (normal copy number) unless the absolute deviation of the
multiple peaks fit is significantly smaller. Here the meaning of
"significant" is given by the \fIfloat\fP from the interval [0,1] where
larger is stricter.
.RE
.sp
\fB\-f, \-\-fit\-th\fP \fIfloat\fP
.RS 4
threshold for goodness of fit (normalized absolute deviation), smaller is stricter
.RE
.sp
\fB\-i, \-\-include\-aa\fP
.RS 4
include also the AA peak in CN2 and CN3 evaluation. This usually requires increasing \fB\-f\fP.
.RE
.sp
\fB\-m, \-\-min\-fraction\fP \fIfloat\fP
.RS 4
minimum distinguishable fraction of aberrant cells. The experience shows that trustworthy
are estimates of 20% and more.
.RE
.sp
\fB\-p, \-\-peak\-symmetry\fP \fIfloat\fP
.RS 4
a heuristics to filter failed fits where the expected peak symmetry is violated.
The \fIfloat\fP is from the interval [0,1] and larger is stricter
.RE
.SS "bcftools query [\fIOPTIONS\fP] \fIfile.vcf.gz\fP [\fIfile.vcf.gz\fP [...]]"
.sp
Extracts fields from VCF or BCF files and outputs them in user\-defined format.
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-\-force\-samples\fP
.RS 4
continue even when some samples requested via \fB\-s/\-S\fP do not exist
.RE
.sp
\fB\-f, \-\-format\fP \fIFORMAT\fP
.RS 4
learn by example, see below
.RE
.sp
\fB\-F, \-\-print\-filtered\fP \fISTR\fP
.RS 4
by default, samples failing \fB\-i/\-e\fP filtering expressions are suppressed from output
when FORMAT fields are queried (for example \fI%CHROM %POS [ %GT]\fP).  With \fB\-F\fP, such
fields will be still printed but instead of their actual value, \fISTR\fP will be used.
.RE
.sp
\fB\-H, \-\-print\-header\fP
.RS 4
print header. By default, the header is printed with column indices, e.g. "#[1]CHROM".
These can be suppressed by giving the option twice, "\f(CR\-HH\fP".
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-l, \-\-list\-samples\fP
.RS 4
list sample names and exit
.RE
.sp
\fB\-N, \-\-disable\-automatic\-newline\fP
.RS 4
disable automatic addition of a missing newline character at the end of the formatting
expression. By default, the program checks if the expression contains a newline
and appends it if not, to prevent formatting the entire output into a single
line by mistake. Note that versions prior to 1.18 had no automatic check and newline
had to be included explicitly.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-u, \-\-allow\-undef\-tags\fP
.RS 4
do not throw an error if there are undefined tags in the format string,
print "." instead
.RE
.sp
\fB\-v, \-\-vcf\-list\fP \fIFILE\fP
.RS 4
process multiple VCFs listed in the file
.RE
.sp
\fB\-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "Format:"
.sp
.if n .RS 4
.nf
.fam C
%CHROM          The CHROM column (similarly also other columns: POS, ID, REF, ALT, QUAL, FILTER)
%END            End position of the REF allele
%END0           End position of the REF allele in 0\-based coordinates
%FIRST_ALT      Alias for %ALT{0}
%FORMAT         Prints all FORMAT fields or a subset of samples with \-s or \-S
%GT             Genotype (e.g. 0/1)
%FUNCTION       Functions supported by the \-i/\-e filtering expressions (e.g. "[ %sSUM(FMT/AD)] %SUM(FMT/AD) %SUM(INFO/AD)")
%INFO           Prints the whole INFO column
%INFO/TAG       Any tag in the INFO column
%IUPACGT        Genotype translated to IUPAC ambiguity codes (e.g. M instead of C/A)
%LINE           Prints the whole line
%MASK           Indicates presence of the site in other files (with multiple files)
%N_PASS(expr)   Number of samples that pass the filtering expression (see *<<expressions,EXPRESSIONS>>*)
%POS0           POS in 0\-based coordinates
%PBINOM(TAG)    Calculate phred\-scaled binomial probability, the allele index is determined from GT
%SAMPLE         Sample name
%TAG{INT}       Curly brackets to print a subfield (e.g. INFO/TAG{1}, the indexes are 0\-based)
%TBCSQ          Translated FORMAT/BCSQ. See the csq command above for explanation and examples.
%TGT            Translated genotype (e.g. C/A)
%TYPE           Variant type (REF, SNP, MNP, INDEL, BND, OTHER)
%VKX            VariantKey, biallelic hexadecimal encoding of CHROM,POS,REF,ALT (https://github.com/tecnickcom/variantkey)
[]              Format fields must be enclosed in brackets to loop over all samples
\(rsn              new line
\(rst              tab character
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
Everything else is printed verbatim.
.fam
.fi
.if n .RE
.SS "Examples:"
.sp
.if n .RS 4
.nf
.fam C
# Print chromosome, position, ref allele and the first alternate allele
bcftools query \-f \*(Aq%CHROM  %POS  %REF  %ALT{0}\(rsn\*(Aq file.vcf.gz
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Similar to above, but use tabs instead of spaces, add sample name and genotype
bcftools query \-f \*(Aq%CHROM\(rst%POS\(rst%REF\(rst%ALT[\(rst%SAMPLE=%GT]\(rsn\*(Aq file.vcf.gz
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print FORMAT/GT fields followed by FORMAT/GT fields
bcftools query \-f \*(AqGQ:[ %GQ] \(rst GT:[ %GT]\(rsn\*(Aq file.vcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Make a BED file: chr, pos (0\-based), end pos (1\-based), id
bcftools query \-f\*(Aq%CHROM\(rst%POS0\(rst%END\(rst%ID\(rsn\*(Aq file.bcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print only samples with alternate (non\-reference) genotypes
bcftools query \-f\*(Aq[%CHROM:%POS %SAMPLE %GT\(rsn]\*(Aq \-i\*(AqGT="alt"\*(Aq file.bcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print all samples at sites with at least one alternate genotype
bcftools view \-i\*(AqGT="alt"\*(Aq file.bcf \-Ou | bcftools query \-f\*(Aq[%CHROM:%POS %SAMPLE %GT\(rsn]\*(Aq
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print phred\-scaled binomial probability from FORMAT/AD tag for all heterozygous genotypes
bcftools query \-i\*(AqGT="het"\*(Aq \-f\*(Aq[%CHROM:%POS %SAMPLE %GT %PBINOM(AD)\(rsn]\*(Aq file.vcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print the second value of AC field if bigger than 10. Note the (unfortunate) difference in
# index subscript notation: formatting expressions (\-f) uses "{}" while filtering expressions
# (\-i) use "[]". This is for historic reasons and backward\-compatibility.
bcftools query \-f \*(Aq%AC{1}\(rsn\*(Aq \-i \*(AqAC[1]>10\*(Aq file.vcf.gz
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Print all samples at sites where at least one sample has DP=1 or DP=2. In the second case
# print only samples with DP=1 or DP=2, the difference is in the logical operator used, || vs |.
bcftools query \-f \*(Aq[%SAMPLE %GT %DP\(rsn]\*(Aq \-i \*(AqFMT/DP=1 || FMT/DP=2\*(Aq file.vcf
bcftools query \-f \*(Aq[%SAMPLE %GT %DP\(rsn]\*(Aq \-i \*(AqFMT/DP=1 |  FMT/DP=2\*(Aq file.vcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Refer to ID column vs INFO/ID tag vs FORMAT/ID tag
bcftools query \-f \*(AqcolumnID=%ID   infoID=%INFO/ID  [fmtID=%ID ]  [columnID=%/ID]\*(Aq
.fam
.fi
.if n .RE
.SS "bcftools reheader [\fIOPTIONS\fP] \fIfile.vcf.gz\fP"
.sp
Modify header of VCF/BCF files, change sample names.
.sp
\fB\-f, \-\-fai\fP \fIFILE\fP
.RS 4
add to the header contig names and their lengths from the provided fasta index file (.fai).
Lengths of existing contig lines will be updated and contig lines not present in
the fai file will be removed
.RE
.sp
\fB\-h, \-\-header\fP \fIFILE\fP
.RS 4
new VCF header
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fIFILE\fP
.RS 4
new sample names, one name per line, in the same order as they appear
in the VCF file. Alternatively, only samples which need to be renamed
can be listed as "old_name new_name\(rsn" pairs separated by whitespaces,
each on a separate line. If a sample name contains spaces, the
spaces can be escaped using the backslash character, for example
"Not\(rs a\(rs good\(rs sample\(rs name".
.RE
.sp
\fB\-T, \-\-temp\-prefix\fP \fIPATH\fP
.RS 4
this option is ignored, but left for compatibility with earlier versions of bcftools.
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "bcftools roh [\fIOPTIONS\fP] \fIfile.vcf.gz\fP"
.sp
A program for detecting runs of homo/autozygosity. Only bi\-allelic sites
are considered. The results can be visualized in HTML/JavaScript using
the \fBroh\-viz\fP script.
.SS "The HMM model:"
.sp
.if n .RS 4
.nf
.fam C
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

  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 \- tAZ * ci) * AZ{i\-1} , tAZ * ci * (1\-AZ{i\-1})]
  P_{i+1}(HW) = oHW * max[(1 \- tHW * ci) * (1\-AZ{i\-1}) , tHW * ci * AZ{i\-1}]
.fam
.fi
.if n .RE
.SS "General Options:"
.sp
\fB\-\-AF\-dflt\fP \fIFLOAT\fP
.RS 4
in case allele frequency is not known, use the \fIFLOAT\fP. By default, sites where
allele frequency cannot be determined, or is 0, are skipped.
.RE
.sp
\fB\-\-AF\-tag\fP \fITAG\fP
.RS 4
use the specified INFO tag \fITAG\fP as an allele frequency estimate
instead of the default AC and AN tags. Sites which do not have \fITAG\fP
will be skipped.
.RE
.sp
\fB\-\-AF\-file\fP \fIFILE\fP
.RS 4
Read allele frequencies from a tab\-delimited file containing
the columns: CHROM\(rstPOS\(rstREF,ALT\(rstAF. The file can be compressed with
\fBbgzip\fP and indexed with tabix \-s1 \-b2 \-e2.  Sites which are not present in
the \fIFILE\fP or have different reference or alternate allele will be skipped.
Note that such a file can be easily created from a VCF using:
.RE
.sp
.if n .RS 4
.nf
.fam C
    bcftools query \-f\*(Aq%CHROM\(rst%POS\(rst%REF,%ALT\(rst%INFO/TAG\(rsn\*(Aq file.vcf | bgzip \-c > freqs.tab.gz
.fam
.fi
.if n .RE
.sp
\fB\-b, \-\-buffer\-size\fP \fIINT\fP[,\fIINT\fP]
.RS 4
when the entire many\-sample file cannot fit into memory, a sliding
buffer approach can be used. The first value is the number of sites
to keep in memory. If negative, it is interpreted as the maximum
memory to use, in MB. The second, optional, value sets the number
of overlapping sites. The default overlap is set to roughly 1% of
the buffer size.
.RE
.sp
\fB\-e, \-\-estimate\-AF\fP \fIFILE\fP
.RS 4
estimate the allele frequency by recalculating INFO/AC and INFO/AN on
the fly, using the specified \fITAG\fP which can be either FORMAT/GT ("GT")
or FORMAT/PL ("PL"). If \fITAG\fP is not given, "GT" is assumed.  Either all
samples ("\-") or samples listed in \fIFILE\fP will be included. For example,
use "PL,\-" to estimate AF from FORMAT/PL of all samples.
If neither \fB\-e\fP nor the other \fB\-\-AF\-...\fP options are given, the allele frequency is
estimated from AC and AN counts which are already present in the INFO field.
.RE
.sp
\fB\-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-G, \-\-GTs\-only\fP \fIFLOAT\fP
.RS 4
use genotypes (FORMAT/GT fields) ignoring genotype likelihoods (FORMAT/PL),
setting PL of unseen genotypes to \fIFLOAT\fP. Safe value to use is 30 to
account for GT errors.
.RE
.sp
\fB\-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-I, \-\-skip\-indels\fP
.RS 4
skip indels as their genotypes are usually enriched for errors
.RE
.sp
\fB\-m, \-\-genetic\-map\fP \fIFILE\fP
.RS 4
genetic map in the format required also by IMPUTE2. Only the first and
third column are used (position and Genetic_Map(cM)). The \fIFILE\fP can
be a single file or a file mask, where string "{CHROM}" is replaced with
chromosome name.
.RE
.sp
\fB\-M, \-\-rec\-rate\fP \fIFLOAT\fP
.RS 4
constant recombination rate per bp. In combination with \fB\-\-genetic\-map\fP,
the \fB\-\-rec\-rate\fP parameter is interpreted differently, as \fIFLOAT\fP\-fold increase of
transition probabilities, which allows the model to become more sensitive
yet still account for recombination hotspots. Note that also the range
of the values is therefore different in both cases: normally the
parameter will be in the range (1e\-3,1e\-9) but with \fB\-\-genetic\-map\fP
it will be in the range (10,1000).
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
Write output to the \fIFILE\fP, by default the output is printed on stdout
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIs\fP|\fIr\fP[\fIz\fP]
.RS 4
Generate per\-site output (\fIs\fP) or per\-region output (\fIr\fP). By default
both types are printed and the output is uncompressed. Add \fIz\fP for
a compressed output.
.RE
.sp
.if n .RS 4
.nf
.fam C
    # Output fields:
    RG = predicted homo/autozygous regions
        \- Sample
        \- Chromosome
        \- Start
        \- End
        \- Length (bp)
        \- Number of markers
        \- Quality .. average phred score in the region from the forward\-backward algorithm

    ST = per\-site output showing:
        \- Sample
        \- Chromosome
        \- Position
        \- State .. predicted state from the Viterbi algorithm, 0 for normal (HW, Hardy\-Weinberg) or 1 for autozygous (AZ)
        \- Quality .. quality score from the forward\-backward algorithm
.fam
.fi
.if n .RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "HMM Options:"
.sp
\fB\-a, \-\-hw\-to\-az\fP \fIFLOAT\fP
.RS 4
P(AZ|HW) transition probability from AZ (autozygous) to HW (Hardy\-Weinberg) state
.RE
.sp
\fB\-H, \-\-az\-to\-hw\fP \fIFLOAT\fP
.RS 4
P(HW|AZ) transition probability from HW to AZ state
.RE
.sp
\fB\-V, \-\-viterbi\-training\fP \fIFLOAT\fP
.RS 4
estimate HMM parameters using Baum\-Welch algorithm, using the convergence threshold
\fIFLOAT\fP, e.g. 1e\-10 (experimental)
.RE
.SS "bcftools sort [\fIOPTIONS\fP] file.bcf"
.sp
\fB\-m, \-\-max\-mem\fP \fIFLOAT\fP[\fIkMG\fP]
.RS 4
Maximum memory to use. Approximate, affects the number of temporary files written
to the disk. Note that if the command fails at this step because of too many open files,
your system limit on the number of open files ("ulimit") may need to be increased.
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-temp\-dir\fP \fIDIR\fP
.RS 4
Use this directory to store temporary files. If the last six characters of the string DIR are XXXXXX,
then these are replaced with a string that makes the directory name unique.
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "bcftools stats [\fIOPTIONS\fP] \fIA.vcf.gz\fP [\fIB.vcf.gz\fP]"
.sp
Parses VCF or BCF and produces text file stats which is suitable for machine
processing and can be plotted using \fBplot\-vcfstats\fP.  When two files are given,
the program generates separate stats for intersection and the complements. By
default only sites are compared, \fB\-s\fP/\fB\-S\fP must given to include also sample
columns.
When one VCF file is specified on the command line, then stats by non\-reference allele
frequency, depth distribution, stats by quality and per\-sample counts, singleton stats,
etc. are printed.
When two VCF files are given, then stats such as concordance (Genotype concordance by
non\-reference allele frequency, Genotype concordance by sample, Non\-Reference Discordance)
and correlation are also printed. Per\-site discordance (PSD) is also printed in \fB\-\-verbose\fP mode.
.sp
\fB\-\-af\-bins\fP \fILIST\fP|\fIFILE\fP
.RS 4
comma separated list of allele frequency bins (e.g. 0.1,0.5,1)
or a file listing the allele frequency bins one per line (e.g. 0.1\(rsn0.5\(rsn1)
.RE
.sp
\fB\-\-af\-tag\fP \fITAG\fP
.RS 4
allele frequency INFO tag to use for binning. By default the allele frequency is
estimated from AC/AN, if available, or directly from the genotypes (GT) if not.
.RE
.sp
\fB\-1, \-\-1st\-allele\-only\fP
.RS 4
consider only the 1st alternate allele at multiallelic sites
.RE
.sp
\fB\-c, \-\-collapse\fP \fIsnps\fP|\fIindels\fP|\fIboth\fP|\fIall\fP|\fIsome\fP|\fInone\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-d, \-\-depth\fP \fIINT\fP,\fIINT\fP,\fIINT\fP
.RS 4
ranges of depth distribution: min, max, and size of the bin
.RE
.sp
\fB\-\-debug\fP
.RS 4
produce verbose per\-site and per\-sample output
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-E, \-\-exons\fP \fIfile.gz\fP
.RS 4
tab\-delimited file with exons for indel frameshifts statistics. The columns
of the file are CHR, FROM, TO, with 1\-based, inclusive, positions. The file
is BGZF\-compressed and indexed with tabix
.RE
.sp
.if n .RS 4
.nf
.fam C
    tabix \-s1 \-b2 \-e3 file.gz
.fam
.fi
.if n .RE
.sp
\fB\-f, \-\-apply\-filters\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-F, \-\-fasta\-ref\fP \fIref.fa\fP
.RS 4
faidx indexed reference sequence file to determine INDEL context
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include only sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-I, \-\-split\-by\-ID\fP
.RS 4
collect stats separately for sites which have the ID column set ("known
sites") or which do not have the ID column set ("novel sites").
.RE
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-u, \-\-user\-tstv\fP \fI<TAG[:min:max:n]>\fP
.RS 4
collect Ts/Tv stats for any tag using the given binning [0:1:100]
.RE
.sp
\fB\-v, \-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.SS "bcftools view [\fIOPTIONS\fP] \fIfile.vcf.gz\fP [\fIREGION\fP [...]]"
.sp
View, subset and filter VCF or BCF files by position and filtering expression.
Convert between VCF and BCF. Former \fBbcftools subset\fP.
.SS "Output options"
.sp
\fB\-G, \-\-drop\-genotypes\fP
.RS 4
drop individual genotype information (after subsetting if \fB\-s\fP option is set)
.RE
.sp
\fB\-h, \-\-header\-only\fP
.RS 4
output the VCF header only (see also \fBbcftools head\fP)
.RE
.sp
\fB\-H, \-\-no\-header\fP
.RS 4
suppress the header in VCF output
.RE
.sp
\fB\-\-with\-header\fP
.RS 4
output both VCF header and records (this is the default, but the option
is useful for explicitness or to reset the effects of \fB\-h\fP or \fB\-H\fP)
.RE
.sp
\fB\-l, \-\-compression\-level\fP [\fI0\-9\fP]
.RS 4
compression level. 0 stands for uncompressed, 1 for best speed and 9 for
best compression.
.RE
.sp
\fB\-\-no\-version\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-O, \-\-output\-type\fP \fIb\fP|\fIu\fP|\fIz\fP|\fIv\fP[0\-9]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP:
output file name. If not present, the default is to print to standard output (stdout).
.sp
\fB\-r, \-\-regions\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-R, \-\-regions\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-regions\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-t, \-\-targets\fP \fIchr\fP|\fIchr:pos\fP|\fIchr:from\-to\fP|\fIchr:from\-\fP[,...]
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-T, \-\-targets\-file\fP \fIfile\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-targets\-overlap\fP \fI0\fP|\fI1\fP|\fI2\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-threads\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-\-verbosity\fP \fIINT\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-W\fP[\fIFMT\fP]\fB, \-W\fP[=\fIFMT\fP]\fB, \-\-write\-index\fP[=\fIFMT\fP]
.RS 4
Automatically index the output file.  \fIFMT\fP is optional and can be
one of "tbi" or "csi" depending on output file format.
.RE
.SS "Subset options:"
.sp
\fB\-A, \-\-trim\-unseen\-alleles\fP
.RS 4
remove the unseen allele \fI<*>\fP or \fI<NON_REF>\fP at variant sites when the option is given once (\-A) or
at all sites when the options is given twice (\fI\-AA\fP).
.RE
.sp
\fB\-a, \-\-trim\-alt\-alleles\fP
.RS 4
remove alleles not seen in the genotype fields from the ALT column. Note that if no alternate allele
remains after trimming, the record itself is not removed but ALT is set to ".".
If the option \fB\-s\fP or \fB\-S\fP is given, removes alleles not seen in the subset.
INFO and FORMAT tags declared as Type=A, G or R will be trimmed as well.
.RE
.sp
\fB\-\-force\-samples\fP
.RS 4
only warn about unknown subset samples
.RE
.sp
\fB\-I, \-\-no\-update\fP
.RS 4
do not (re)calculate INFO fields for the subset (currently INFO/AC and INFO/AN)
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP. Note that it is possible to create
multiple subsets simultaneously using the \fBsplit\fP plugin.
.RE
.sp
\fB\-S, \-\-samples\-file\fP \fIFILE\fP
.RS 4
see \fBCommon Options\fP. Note that it is possible to create
multiple subsets simultaneously using the \fBsplit\fP plugin.
.RE
.SS "Filter options:"
.sp
Note that filter options below dealing with counting the number of alleles
will, for speed, first check for the values of AC and AN in the INFO column to
avoid parsing all the genotype (FORMAT/GT) fields in the VCF. This means
that filters like \fI\-\-uncalled\fP, \-\-exclude\-uncalled\*(Aq, or \fI\-\-min\-af 0.1\fP will be calculated from INFO/AC and
INFO/AN when available or FORMAT/GT otherwise. However, it will not attempt to use any other existing field,
like INFO/AF for example. For that, use \fI\-\-exclude AF<0.1\fP instead.
.sp
Also note that one must be careful when sample subsetting and filtering is performed in a single command
because the order of internal operations can influence the result. For example, the \fB\-i/\-e\fP filtering
is performed before sample removal, but the \fB\-P\fP filtering is performed after,
and some are inherently ambiguous, for example allele counts can be taken from the INFO
column when present but calculated on the fly when absent. Therefore it is strongly recommended to spell out the
required order explicitly by separating such commands into two steps. (Make sure to use the \fB\-O u\fP option
when piping!)
.sp
\fB\-c, \-\-min\-ac\fP \fIINT\fP[\fI:nref\fP|\fI:alt1\fP|\fI:minor\fP|\fI:major\fP|:\*(Aqnonmajor\*(Aq]
.RS 4
minimum allele count (INFO/AC) of sites to be printed.
Specifying the type of allele is optional and can be set to
non\-reference (\fInref\fP, the default), 1st alternate  (\fIalt1\fP), the least
frequent (\fIminor\fP), the most frequent (\fImajor\fP) or sum of all but the
most frequent (\fInonmajor\fP) alleles.
.RE
.sp
\fB\-C, \-\-max\-ac\fP \fIINT\fP[\fI:nref\fP|\fI:alt1\fP|\fI:minor\fP|:\*(Aqmajor\*(Aq|:\*(Aqnonmajor\*(Aq]
.RS 4
maximum allele count (INFO/AC) of sites to be printed.
Specifying the type of allele is optional and can be set to
non\-reference (\fInref\fP, the default), 1st alternate  (\fIalt1\fP), the least
frequent (\fIminor\fP), the most frequent (\fImajor\fP) or sum of all but the
most frequent (\fInonmajor\fP) alleles.
.RE
.sp
\fB\-e, \-\-exclude\fP \fIEXPRESSION\fP
.RS 4
exclude sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-f, \-\-apply\-filters\fP \fILIST\fP
.RS 4
see \fBCommon Options\fP
.RE
.sp
\fB\-g, \-\-genotype\fP [^][\fIhom\fP|\fIhet\fP|\fImiss\fP]
.RS 4
include only sites with one or more homozygous (\fIhom\fP), heterozygous
(\fIhet\fP) or missing (\fImiss\fP) genotypes. When prefixed with \fI^\fP, the logic
is reversed; thus \fI^het\fP excludes sites with heterozygous genotypes.
.RE
.sp
\fB\-i, \-\-include\fP \fIEXPRESSION\fP
.RS 4
include sites for which \fIEXPRESSION\fP is true. For valid expressions see
\fBEXPRESSIONS\fP.
.RE
.sp
\fB\-k, \-\-known\fP
.RS 4
print known sites only (ID column is not ".")
.RE
.sp
\fB\-m, \-\-min\-alleles\fP \fIINT\fP
.RS 4
print sites with at least \fIINT\fP alleles listed in REF and ALT columns
.RE
.sp
\fB\-M, \-\-max\-alleles\fP \fIINT\fP
.RS 4
print sites with at most \fIINT\fP alleles listed in REF and ALT columns.
Use \fB\-m2 \-M2 \-v snps\fP to only view biallelic SNPs.
.RE
.sp
\fB\-n, \-\-novel\fP
.RS 4
print novel sites only (ID column is ".")
.RE
.sp
\fB\-p, \-\-phased\fP
.RS 4
print sites where all samples are phased. Haploid genotypes are
considered phased. Missing genotypes considered unphased unless the
phased bit is set.
.RE
.sp
\fB\-P, \-\-exclude\-phased\fP
.RS 4
exclude sites where all samples are phased
.RE
.sp
\fB\-q, \-\-min\-af\fP \fIFLOAT\fP[\fI:nref\fP|\fI:alt1\fP|\fI:minor\fP|\fI:major\fP|\fI:nonmajor\fP]
.RS 4
minimum allele frequency (INFO/AC / INFO/AN) of sites to be printed.
Specifying the type of allele is optional and can be set to
non\-reference (\fInref\fP, the default), 1st alternate  (\fIalt1\fP), the least
frequent (\fIminor\fP), the most frequent (\fImajor\fP) or sum of all but the
most frequent (\fInonmajor\fP) alleles.
.RE
.sp
\fB\-Q, \-\-max\-af\fP \fIFLOAT\fP[\fI:nref\fP|\fI:alt1\fP|\fI:minor\fP|\fI:major\fP|\fI:nonmajor\fP]
.RS 4
maximum allele frequency (INFO/AC / INFO/AN) of sites to be printed.
Specifying the type of allele is optional and can be set to
non\-reference (\fInref\fP, the default), 1st alternate  (\fIalt1\fP), the least
frequent (\fIminor\fP), the most frequent (\fImajor\fP) or sum of all but the
most frequent (\fInonmajor\fP) alleles.
.RE
.sp
\fB\-u, \-\-uncalled\fP
.RS 4
print sites without a called genotype, i.e. print sites with all genotypes
missing. Note that the missingness is determined from INFO/AN and AC tags
when available to avoid parsing sample fields.
.RE
.sp
\fB\-U, \-\-exclude\-uncalled\fP
.RS 4
exclude sites without a called genotype, i.e. print sites with at least one
non\-missing genotype. Note that the missingness is determined from INFO/AN
and AC tags when available to avoid parsing sample fields.
.RE
.sp
\fB\-v, \-\-types\fP \fIsnps\fP|\fIindels\fP|\fImnps\fP|\fIother\fP
.RS 4
comma\-separated list of variant types to select. Site is selected if
any of the ALT alleles is of the type requested. Types are determined
by comparing the REF and ALT alleles in the VCF record not INFO tags
like INFO/INDEL or INFO/VT. Use \fB\-\-include\fP to select based on INFO
tags.
.RE
.sp
\fB\-V, \-\-exclude\-types\fP \fIsnps\fP|\fIindels\fP|\fImnps\fP|\fIref\fP|\fIbnd\fP|\fIother\fP
.RS 4
comma\-separated list of variant types to exclude. Site is excluded if
any of the ALT alleles is of the type requested. Types are determined
by comparing the REF and ALT alleles in the VCF record not INFO tags
like INFO/INDEL or INFO/VT. Use \fB\-\-exclude\fP to exclude based on INFO tags.
.RE
.sp
\fB\-x, \-\-private\fP
.RS 4
print sites where only the subset samples carry an non\-reference allele.
Requires \fB\-\-samples\fP or \fB\-\-samples\-file\fP.
.RE
.sp
\fB\-X, \-\-exclude\-private\fP
.RS 4
exclude sites where only the subset samples carry an non\-reference allele
.RE
.SS "bcftools help [\fICOMMAND\fP] | bcftools \-\-help [\fICOMMAND\fP]"
.sp
Display  a  brief usage message listing the bcftools commands available.
If the name of a command is also given, e.g., bcftools help view, the detailed
usage message for that particular command is displayed.
.SS "bcftools [\fI\-\-version\fP|\fI\-v\fP]"
.sp
Display the version numbers and copyright information for bcftools and the
important libraries used by bcftools.
.SS "bcftools [\fI\-\-version\-only\fP]"
.sp
Display the full bcftools version number in a machine\-readable format.
.SH "SCRIPTS"
.SS "gff2gff"
.sp
Attempts to fix a GFF file to be correctly parsed by \fBcsq\fP.
.sp
.if n .RS 4
.nf
.fam C
zcat in.gff.gz | gff2gff | gzip \-c > out.gff.gz
.fam
.fi
.if n .RE
.SS "plot\-vcfstats [\fIOPTIONS\fP] \fIfile.vchk\fP [...]"
.sp
Script for processing output of \fBbcftools stats\fP. It can merge
results from multiple outputs (useful when running the stats for each
chromosome separately), plots graphs and creates a PDF presentation.
.sp
\fB\-m, \-\-merge\fP
.RS 4
Merge vcfstats files to STDOUT, skip plotting.
.RE
.sp
\fB\-p, \-\-prefix\fP \fIDIR\fP
.RS 4
The output directory. This directory will be created if it does not exist.
.RE
.sp
\fB\-P, \-\-no\-PDF\fP
.RS 4
Skip the PDF creation step.
.RE
.sp
\fB\-r, \-\-rasterize\fP
.RS 4
Rasterize PDF images for faster rendering. This is the default and the opposite of \fB\-v, \-\-vectors\fP.
.RE
.sp
\fB\-s, \-\-sample\-names\fP
.RS 4
Use sample names for xticks rather than numeric IDs.
.RE
.sp
\fB\-t, \-\-title\fP \fISTRING\fP
.RS 4
Identify files by these titles in plots. The option can be given multiple
times, for each ID in the \fBbcftools stats\fP output. If not
present, the script will use abbreviated source file names for the titles.
.RE
.sp
\fB\-v, \-\-vectors\fP
.RS 4
Generate vector graphics for PDF images, the opposite of \fB\-r, \-\-rasterize\fP.
.RE
.sp
\fB\-T, \-\-main\-title\fP \fISTRING\fP
.RS 4
Main title for the PDF.
.RE
.sp
\fBExample:\fP
.sp
.if n .RS 4
.nf
.fam C
# Generate the stats
bcftools stats \-s \- > file.vchk
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Plot the stats
plot\-vcfstats \-p outdir file.vchk
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# The final looks can be customized by editing the generated
# \*(Aqoutdir/plot.py\*(Aq script and re\-running manually
cd outdir && python plot.py && pdflatex summary.tex
.fam
.fi
.if n .RE
.SS "roh\-viz [\fIOPTIONS\fP]"
.sp
Script for visualizing the output of \fBbcftools roh\fP. It creates
a HTML/JavaScript document which can be interactively viewed in your favorite
web browser.
.sp
\fB\-i, \-\-RoH\-file\fP \fIFILE\fP
.RS 4
Output of bcftools/roh
.RE
.sp
\fB\-l, \-\-min\-length\fP \fINUM\fP
.RS 4
Mimimum length of ROH [1e6]
.RE
.sp
\fB\-o, \-\-output\fP \fIFILE\fP
.RS 4
HTML output file
.RE
.sp
\fB\-r, \-\-regions\fP \fILIST\fP
.RS 4
List of chromosomes/regions
.RE
.sp
\fB\-s, \-\-samples\fP \fILIST\fP
.RS 4
List of samples to show
.RE
.sp
\fB\-v, \-\-VCF\-file\fP \fIFILE\fP
.RS 4
VCF file to determine homozygosity rate
.RE
.sp
\fB\-h, \-?, \-\-help\fP
This help message
.sp
\fBExample:\fP
.sp
.if n .RS 4
.nf
.fam C
# Find RoH regions
bcftools roh \-\-AF\-dflt 0.5 \-G 30 \-Or \-o roh.txt file.bcf
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# Create HTML/JavaScript visualization
roh\-viz \-r roh.txt \-v file.bcf \-o output.html
.fam
.fi
.if n .RE
.SH "FILTERING EXPRESSIONS"
.sp
These filtering expressions are accepted by most of the commands.
.sp
.B Valid expressions may contain:
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
numerical constants, string constants, file names (indicated by the prefix \fI@\fP)
.sp
.if n .RS 4
.nf
.fam C
1, 1.0, 1e\-4
"String"
@file_name
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
arithmetic operators (addition, multiplication, subtraction, division, modulo)
.sp
.if n .RS 4
.nf
.fam C
+, *, \-, /, %
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
comparison operators
.sp
.if n .RS 4
.nf
.fam C
== (same as =), >, >=, <=, <, !=
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
regex operators "\(rs~" and its negation "!~". The expressions are case sensitive unless "/i" is added.
.sp
.if n .RS 4
.nf
.fam C
INFO/HAYSTACK ~ "needle"
INFO/HAYSTACK ~ "NEEDless/i"
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
parentheses
.sp
.if n .RS 4
.nf
.fam C
(, )
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
logical operators. See also the examples below and the \c
.URL "http://samtools.github.io/bcftools/howtos/filtering.html" "filtering tutorial"
about the distinction between "&&" vs "&" and "||" vs "|".
.sp
.if n .RS 4
.nf
.fam C
&&,  &, ||,  |
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
INFO tags, FORMAT tags, column names
.sp
.if n .RS 4
.nf
.fam C
INFO/DP or DP
FORMAT/DV, FMT/DV, or DV
FILTER, QUAL, ID, CHROM, POS, REF, ALT[0]
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
the FILTER column can be queried as follows:
.sp
.if n .RS 4
.nf
.fam C
FILTER="PASS"
FILTER="."
FILTER="A"          .. exact match, for example "A;B" does not pass
FILTER="A;B"        .. exact match, "A;B" and "B;A" pass, everything else fails
FILTER!="A"         .. exact match, for example "A;B" does pass
FILTER~"A"          .. subset match, for example both "A" and "A;B" pass
FILTER~"A;B"        .. subset match, pass only if both "A" and "B" are present
FILTER!~"A"         .. complement match, for example both "A" and "A;B" fail
FILTER!~"A;B"       .. complement match, fail if both "A" and "B" are present
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
1 (or 0) to test the presence (or absence) of a flag
.sp
.if n .RS 4
.nf
.fam C
FlagA=1 && FlagB=0
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"." to test missing values
.sp
.if n .RS 4
.nf
.fam C
DP=".", DP!=".", ALT="."
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
missing genotypes can be matched regardless of phase and ploidy (".|.", "./.", ".", "0|.")
using these expressions
.sp
.if n .RS 4
.nf
.fam C
GT="mis", GT~"\(rs.", GT!~"\(rs."
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
missing genotypes can be matched including the phase and ploidy (".|.", "./.", ".")
using these expressions
.sp
.if n .RS 4
.nf
.fam C
GT=".|.", GT="./.", GT="."
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
sample genotype: reference (haploid or diploid), alternate (hom or het,
haploid or diploid), missing genotype, homozygous, heterozygous, haploid,
ref\-ref hom, alt\-alt hom, ref\-alt het, alt\-alt het, haploid ref, haploid alt
(case\-insensitive)
.sp
.if n .RS 4
.nf
.fam C
GT="ref"
GT="alt"
GT="mis"
GT="hom"
GT="het"
GT="hap"
GT="RR"
GT="AA"
GT="RA" or GT="AR"
GT="Aa" or GT="aA"
GT="R"
GT="A"
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
TYPE for variant type in REF,ALT columns (indel,snp,mnp,ref,bnd,other,overlap, see \fBTERMINOLOGY\fP). Use the regex
operator "\(rs~" to require at least one allele of the given type or the equal sign "="
to require that all alleles are of the given type. Compare
.sp
.if n .RS 4
.nf
.fam C
TYPE="snp"
TYPE~"snp"
TYPE!="snp"
TYPE!~"snp"
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
array subscripts (0\-based), "*" for any element, "\-" to indicate a range. Note that
for querying FORMAT vectors, the colon ":" can be used to select a sample and an
element of the vector, as shown in the examples below.
.sp
.if n .RS 4
.nf
.fam C
INFO/AF[0] > 0.3             .. first AF value bigger than 0.3
FORMAT/AD[0:0] > 30          .. first AD value of the first sample bigger than 30
FORMAT/AD[0:1]               .. first sample, second AD value
FORMAT/AD[1:0]               .. second sample, first AD value
DP4[*] == 0                  .. any DP4 value
FORMAT/DP[0]   > 30          .. DP of the first sample bigger than 30
FORMAT/DP[1\-3] > 10          .. samples 2\-4
FORMAT/DP[1\-]  < 7           .. all samples but the first
FORMAT/DP[0,2\-4] > 20        .. samples 1, 3\-5
FORMAT/AD[0:1]               .. first sample, second AD field
FORMAT/AD[0:*], AD[0:] or AD[0] .. first sample, any AD field
FORMAT/AD[*:1] or AD[:1]        .. any sample, second AD field
(DP4[0]+DP4[1])/(DP4[2]+DP4[3]) > 0.3
CSQ[*] ~ "missense_variant.*deleterious"
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
in addition to array subscripts shown above, it is possible to subscript arrays
of Number=R tags by alleles found in FORMAT/GT (starting with version 1.17).
For example
.sp
.if n .RS 4
.nf
.fam C
FORMAT/AD[GT] > 10        .. require support of more than 10 reads for each allele
FORMAT/AD[0:GT] > 10      .. same as above, but in the first sample
sSUM(FORMAT/AD[GT]) > 20  .. require total sample depth bigger than 20
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
with many samples it can be more practical to provide a file with sample names,
one sample name per line
.sp
.if n .RS 4
.nf
.fam C
GT[@samples.txt]="het" & binom(AD)<0.01
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
function on FORMAT tags (over samples) and INFO tags (over vector fields):
maximum; minimum; arithmetic mean (AVG is synonymous with MEAN); median;
standard deviation from mean; sum; string length; absolute value; number of
elements:
.sp
.if n .RS 4
.nf
.fam C
MAX, MIN, AVG, MEAN, MEDIAN, STDEV, SUM, STRLEN, ABS, COUNT
.fam
.fi
.if n .RE
.sp
Note that functions above evaluate to a single value across all samples and
are intended to select sites, not samples, even when applied on FORMAT tags.
However, when prefixed with SMPL_ (or "s" for brevity, e.g. SMPL_MAX or sMAX),
they will evaluate to a vector of per\-sample values when applied on FORMAT tags:
.sp
.if n .RS 4
.nf
.fam C
SMPL_MAX, SMPL_MIN, SMPL_AVG, SMPL_MEAN, SMPL_MEDIAN, SMPL_STDEV, SMPL_SUM,
sMAX, sMIN, sAVG, sMEAN, sMEDIAN, sSTDEV, sSUM
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
two\-tailed binomial and fisher test. Note that for N=0 the test evaluates to a missing
value and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
homozygous genotypes.
.sp
.if n .RS 4
.nf
.fam C
binom(FMT/AD)                .. GT can be used to determine the correct index
binom(AD[0],AD[1])           .. or the fields can be given explicitly
phred(binom())               .. the same as binom but phred\-scaled
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
fisher(INFO/DP4)
fisher(FORMAT/DP4)
fisher(FMT/ADF,FMT/ADR)              .. GT can be used to determine the correct indices
fisher(FMT/ADF[:0,1],FMT/ADR[:0,1])  .. or the fields can be given explicitly
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
variables calculated on the fly if not present: number of alternate alleles;
number of samples; count of alternate alleles; minor allele count (similar to
AC but always picks the allele with frequency smaller than 0.5); frequency of alternate alleles (AF=AC/AN);
frequency of minor alleles (MAF=MAC/AN); number of alleles in called genotypes;
number of samples with missing genotype; fraction of samples with missing genotype;
indel length (deletions negative, insertions positive, balanced substitutions zero)
.sp
.if n .RS 4
.nf
.fam C
N_ALT, N_SAMPLES, AC, MAC, AF, MAF, AN, N_MISSING, F_MISSING, ILEN
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
the number (N_PASS) or fraction (F_PASS) of samples which pass the expression
.sp
.if n .RS 4
.nf
.fam C
N_PASS(GQ>90 & GT!="mis") > 90
F_PASS(GQ>90 & GT!="mis") > 0.9
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
custom perl filtering. Note that this command is not compiled in by default, see
the section \fBOptional Compilation with Perl\fP in the INSTALL file for help
and misc/demo\-flt.pl for a working example. The demo defined the perl subroutine
"severity" which can be invoked from the command line as follows:
.sp
.if n .RS 4
.nf
.fam C
perl:path/to/script.pl; perl.severity(INFO/CSQ) > 3
.fam
.fi
.if n .RE
.RE
.sp
.B Notes:
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
String comparisons and regular expressions are case\-insensitive
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Comma in strings is interpreted as a separator and when multiple values are compared, the OR logic is used.
Consequently, the following two expressions are equivalent but not the third:
.sp
.if n .RS 4
.nf
.fam C
\-i \*(AqTAG="hello,world"\*(Aq
\-i \*(AqTAG="hello" || TAG="world"\*(Aq
\-i \*(AqTAG="hello" && TAG="world"\*(Aq
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Variables and function names are case\-insensitive, but not tag names. For example,
"qual" can be used instead of "QUAL", "strlen()" instead of "STRLEN()" , but
not "dp" instead of "DP".
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
When querying multiple values, all elements are tested and the OR logic is
used on the result. For example, when querying "TAG=1,2,3,4", it will be evaluated as follows:
.sp
.if n .RS 4
.nf
.fam C
\-i \*(AqTAG[*]=1\*(Aq   .. true, the record will be printed
\-i \*(AqTAG[*]!=1\*(Aq  .. true
\-e \*(AqTAG[*]=1\*(Aq   .. false, the record will be discarded
\-e \*(AqTAG[*]!=1\*(Aq  .. false
\-i \*(AqTAG[0]=1\*(Aq   .. true
\-i \*(AqTAG[0]!=1\*(Aq  .. false
\-e \*(AqTAG[0]=1\*(Aq   .. false
\-e \*(AqTAG[0]!=1\*(Aq  .. true
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
When arithmetic operators are used on vectors A and B, the following logic is used to
compute the resulting vector C:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
C_i = A_i + B_i when length(A)==B(A) and sets length(C)=length(A)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
C_i = A_i + B_0 when length(B)=1 and sets length(C)=length(A)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
C_i = A_0 + B_i when length(A)=1 and sets length(C)=length(B)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
throw an error when length(A)!=length(B) AND length(A)!=1 AND length(B)!=1
.RE
.RE
.sp
\fBExamples:\fP
.sp
.if n .RS 4
.nf
.fam C
MIN(DV)>5       .. selects the whole site, evaluates min across all values and samples
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
SMPL_MIN(DV)>5  .. selects matching samples, evaluates within samples
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
MIN(DV/DP)>0.3
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
MIN(DP)>10 & MIN(DV)>3
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
FMT/DP>10  & FMT/GQ>10 .. both conditions must be satisfied within one sample
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
FMT/DP>10 && FMT/GQ>10 .. the conditions can be satisfied in different samples
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
QUAL>10 |  FMT/GQ>10   .. true for sites with QUAL>10 or a sample with GQ>10, but selects only samples with GQ>10
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
QUAL>10 || FMT/GQ>10   .. true for sites with QUAL>10 or a sample with GQ>10, plus selects all samples at such sites
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
TYPE="snp" && QUAL>=10 && (DP4[2]+DP4[3] > 2)
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
COUNT(GT="hom")=0      .. no homozygous genotypes at the site
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
AVG(GQ)>50             .. average (arithmetic mean) of genotype qualities bigger than 50
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
ID=@file               .. selects lines with ID present in the file
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
ID!=@~/file            .. skip lines with ID present in the ~/file
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
INFO/TAG=@file         .. selects lines with INFO/TAG value present in the file
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
MAF[0]<0.05    .. select rare variants at 5% cutoff
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
POS>=100   .. restrict your range query, e.g. 20:100\-200 to strictly sites with POS in that range.
.fam
.fi
.if n .RE
.sp
\fBShell expansion:\fP
.sp
Note that expressions must often be quoted because some characters
have special meaning in the shell.
An example of expression enclosed in single quotes which cause
that the whole expression is passed to the program as intended:
.sp
.if n .RS 4
.nf
.fam C
bcftools view \-i \*(AqID!="." & MAF[0]<0.01\*(Aq
.fam
.fi
.if n .RE
.sp
Please refer to the documentation of your shell for details.
.SH "TERMINOLOGY"
.sp
The program and the documentation uses the following terminology, multiple terms can be used
interchangeably for the same VCF record type
.sp
.if n .RS 4
.nf
.fam C
REF   ALT
\-\-\-\-\-\-\-\-\-
C     .         .. reference allele / non\-variant site / ref\-only site
C     T         .. SNP or SNV (single\-nucleotide polymorphism or variant), used interchangeably
CC    TT        .. MNP (multi\-nucleotide polymorphism)
CAAA  C         .. indel, deletion (regardless of length)
C     CAAA      .. indel, insertion (regardless of length)
C     <*>       .. gVCF block, the allele <*> is a placeholder for alternate allele possibly missed because of low coverage
C     <NON_REF> .. synonymous to <*>
C     *         .. overlapping deletion
C     <INS>     .. symbolic allele, known also as \*(Aqother [than above]\*(Aq
.fam
.fi
.if n .RE
.SH "PERFORMANCE"
.sp
HTSlib was designed with BCF format in mind. When parsing VCF files, all records
are internally converted into BCF representation. Simple operations, like removing
a single column from a VCF file, can be therefore done much faster with standard
UNIX commands, such as \fBawk\fP or \fBcut\fP.
Therefore it is recommended to use BCF as input/output format whenever possible to avoid
large overhead of the VCF \(-> BCF \(-> VCF conversion.
.SH "BUGS"
.sp
Please report any bugs you encounter on the github website: \c
.URL "http://github.com/samtools/bcftools" "" ""
.SH "AUTHORS"
.sp
Heng Li from the Sanger Institute wrote the original C version of htslib,
samtools and bcftools. Bob Handsaker from the Broad Institute implemented the
BGZF library. Petr Danecek is maintaining and further developing bcftools, together
with the rest of the \c
.URL "https://www.sanger.ac.uk/tool/samtools\-bcftools\-htslib" "samtools team" "."
Many other people contributed to the program
and to the file format specifications, both directly and indirectly by
providing patches, testing and reporting bugs. We thank them all.
.SH "RESOURCES"
.sp
BCFtools GitHub website: \c
.URL "http://github.com/samtools/bcftools" "" ""
.sp
Samtools GitHub website: \c
.URL "http://github.com/samtools/samtools" "" ""
.sp
HTSlib GitHub website: \c
.URL "http://github.com/samtools/htslib" "" ""
.sp
File format specifications: \c
.URL "http://samtools.github.io/hts\-specs" "" ""
.sp
BCFtools documentation: \c
.URL "http://samtools.github.io/bcftools" "" ""
.sp
BCFtools wiki page: \c
.URL "https://github.com/samtools/bcftools/wiki" "" ""
.SH "COPYING"
.sp
The MIT/Expat License or GPL License, see the LICENSE document for details.
Copyright (c) Genome Research Ltd.