vcfexpress

[!CAUTION] While the output of vcfexpress is tested and reliable, the error messages might be lacking. Please report.

This is an experiment on how to implement user-expressions that can filter (and modify) a VCF and specify an output template. It uses lua as the expression language. It is fast Because of the speed and flexibility, we can, for example implement CSQ parsing in lua, just as a user could. The resulting functionality is as fast or faster than other tools that have this built in.

For the optional output template, it uses luau string templates where luau is lua with some extensions and very good speed.

Installation

• For rust users: cargo install vcfexpress
• Otherwise see Releases for a static linux binary

Examples

Further examples are collected here and we encourage users to suggest helpful examples or snippets.

speed

see speed

Lua API

Full documentation of lua attributes and methods is here

```lua variant.chrom -> string variant.REF (get/set) -> string variant.ALT (get/set) -> vec variant.id (get/set) -> string variant.start -> integer variant.stop -> integer variant.pos (get/set) -> integer -- 0-based variant.qual (get/set) -> number variant.filters (get/set) -> vec variant.FILTER (get/set) -> string (only first one reported) variant.genotypes -> vec variant:format("fieldname") -> vec -- optional 0-based 2nd arg to info() gets just the desired index. variant:info("fieldname") -> number|string|bool|vec -- useful to pprint(variant:sample("mysample")) to see available fields. variant:sample("samplename") -> table -- get all samples at once, more efficient than calling sample() multiple times variant:samples() -> table<samplename=table> -- e.g. s = variant:samples(); s.NA12878.DP tostring(variant) -> string -- tab-delimited vcf/variant output.

genotypes = variant.genotypes genotype = genotypes[i] -- get single genotype for 1 sample tostring(genotype) -- e.g. "0/1" genotype.alts -- integer for number of non-zero, non-unknown alleles

allele = genotype[1] allele.phased -> bool allele.allele -> integer e.g. 0 for "0" allele

header.samples (set/get) -> vec -- TODO: allow setting samples before iteration. header:infoget("DP") -> table header:formatget("AD") -> table

-- these header:add* are available only in the prelude. currently only Number=1 is supported. header:addinfo({Type="Integer", Number=1, Description="asdf", ID="new field"}) header:addformat({Type="Integer", Number=1, Description="xyz", ID="new format field"}) header:addfilter({ID="LowQual", Description="Qual less than 50"})

sample = variant:sample("NA12878") sample.DP -- any fields in the row are available. special case for GT. use pprint to see structure: pprint(sample) --[[ { .GQ = 63, .DP = 23, .GT = { -- GT gives index into alt alles (or -1 for .) [1] = 0, [2] = 1}, .AD = { [1] = 23, [2] = 0}, .PL = { [1] = 0, [2] = 63, [3] = 945}, -- this is the genotype phase. so with GT, this is 0|1 .phase = { [1] = false, [2] = true}} --]] ```

Usage

``` Filter a VCF/BCF and optionally print by template expression. If no template is given the output will be VCF/BCF

Usage: vcfexpress filter [OPTIONS]

Arguments: Path to input VCF or BCF file

Options: -e, --expression boolean Lua expression(s) to filter the VCF or BCF file -s, --set-expression expression(s) to set existing INFO field(s) (new ones can be added in prelude) e.g. --set-expression "AFmax=math.max(variant:info('AF'), variant:info('AFx'))" -t, --template