bcftools frameshifts plugin

A simple tool to annotate the effect of indel variants.

Adds an OOF (out-of-frame) subfield to the INFO field of indel records found in the input, where

OOF=1 indicates that the indel results in a frameshift
OOF=0 indicates an in-frame indel

The information about indel effects is extracted from the BED input, which is supposed to describe the reference genome exons.

If a variant record lists several ALT alleles, some of them indels, then OOF will be a comma-separated list of status indicators. In the list a third OOF status code of -1 will be used to indicate ALT alleles that are not associated with a change in sequence length or that don't affect an exon.

The formal definition (added to the VCF header) of the OOF subfield is:

INFO=<ID=OOF,Number=A,Type=Integer,Description="Frameshift Indels: out-of-frame (1), in-frame (0), not-applicable (-1 or missing)">

Region Selections

Regions can be specified in a VCF, BED, or tab-delimited file (the default). The columns of the tab-delimited file are: CHROM, POS, and, optionally, POS_TO, where positions are 1-based and inclusive. 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 FILE will be respected, the VCF will be processed in the order in which chromosomes first appear in FILE. However, within chromosomes, the VCF will always be processed in ascending genomic coordinate order no matter what order they appear in FILE. Note that overlapping regions in FILE can result in duplicated out of order positions in the output. This option requires indexed VCF/BCF files.

Targets

Similar to regions, but the next position is accessed by streaming the whole VCF/BCF rather than using the tbi/csi index. Both regions and targets options can be applied simultaneously: regions uses the index to jump to a region and targets discards positions which are not in the targets. Unlike regions, 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 two is that regions checks both start and end positions of indels, whereas targets checks start positions only.

For the bcftools call command, with the option -C alleles, 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 index. Such a file can be easily created from a VCF using:

bcftools query -f'%CHROM\t%POS\t%REF,%ALT\n' file.vcf | bgzip -c > als.tsv.gz && tabix -s1 -b2 -e2 als.tsv.gz

Expressions

Valid expressions may contain:

numerical constants, string constants
```
1, 1.0, 1e-4
"String"
```
arithmetic operators
```
+,*,-,/
```
comparison operators
```
== (same as =), >, >=, <=, <, !=
```
regex operators "~" and its negation "!~"
```
INFO/HAYSTACK ~ "needle"
```
parentheses
```
(, )
```
logical operators
```
&& (same as &), ||,  |
```

INFO tags, FORMAT tags, column names

INFO/DP or DP
FORMAT/DV, FMT/DV, or DV
FILTER, QUAL, ID, REF, ALT[0]

1 (or 0) to test the presence (or absence) of a flag
```
FlagA=1 && FlagB=0
```
"." to test missing values
```
DP=".", DP!=".", ALT="."
```
missing genotypes can be matched regardless of phase and ploidy (".|.", "./.", ".") using this expression
```
GT="."
```
TYPE for variant type in REF,ALT columns (indel,snp,mnp,ref,other)
```
TYPE="indel" | TYPE="snp"
```

array subscripts, "*" for any field

(DP4[0]+DP4[1])/(DP4[2]+DP4[3]) > 0.3
DP4[*] == 0
CSQ[*] ~ "missense_variant.*deleterious"

function on FORMAT tags (over samples) and INFO tags (over vector fields)
```
MAX, MIN, AVG, SUM, STRLEN, ABS
```
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 is always smaller than 0.5); frequency of alternate alleles (AF=AC/AN); frequency of minor alleles (MAF=MAC/AN); number of alleles in called genotypes
```
N_ALT, N_SAMPLES, AC, MAC, AF, MAF, AN
```

Notes:

String comparisons and regular expressions are case-insensitive
If the subscript "*" is used in regular expression search, the whole field is treated as one string. For example, the regex STR[*]~"B,C" will be true for the string vector INFO/STR=AB,CD.
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".

Examples:

MIN(DV)>5
MIN(DV/DP)>0.3
MIN(DP)>10 & MIN(DV)>3
FMT/DP>10  & FMT/GQ>10 .. both conditions must be satisfied within one sample
FMT/DP>10 && FMT/GQ>10 .. the conditions can be satisfied in different samples
QUAL>10 |  FMT/GQ>10   .. selects only GQ>10 samples
QUAL>10 || FMT/GQ>10   .. selects all samples at QUAL>10 sites
TYPE="snp" && QUAL>=10 && (DP4[2]+DP4[3] > 2)
MIN(DP)>35 && AVG(GQ)>50
ID=@file       .. selects lines with ID present in the file
ID!=@~/file    .. skip lines with ID present in the ~/file
MAF[0]<0.05    .. select rare variants at 5% cutoff