bcftools emulation

bcftools emulation#

vcztools is a drop-in replacement for a subset of bcftools: the view, query and index commands take the same flags and produce the same output, with a VCZ store in place of a VCF/BCF file.

Every command below is run against the example dataset data/sample.vcz.zip (9 variants across 3 samples; see Reading VCZ for its contents). For the full flag list, see CLI Reference.

Viewing records#

vcztools view writes VCF. With no options it emits the complete file — header plus every record:

!vcztools view data/sample.vcz.zip

##fileformat=VCFv4.3
##source=bio2zarr-0.2.0
##INFO=<ID=AA,Number=1,Type=String,Description="Ancestral Allele">
##INFO=<ID=AC,Number=2,Type=Integer,Description="Allele count in genotypes, for each ALT allele, in the same order as listed">
##INFO=<ID=AF,Number=2,Type=Float,Description="Allele Frequency">
##INFO=<ID=AN,Number=1,Type=Integer,Description="Total number of alleles in called genotypes">
##INFO=<ID=DB,Number=0,Type=Flag,Description="dbSNP membership, build 129">
##INFO=<ID=DP,Number=1,Type=Integer,Description="Total Depth">
##INFO=<ID=H2,Number=0,Type=Flag,Description="HapMap2 membership">
##INFO=<ID=NS,Number=1,Type=Integer,Description="Number of Samples With Data">
##FILTER=<ID=PASS,Description="All filters passed">
##FILTER=<ID=s50,Description="Less than 50% of samples have data">
##FILTER=<ID=q10,Description="Quality below 10">
##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
##FORMAT=<ID=DP,Number=1,Type=Integer,Description="Read Depth">
##FORMAT=<ID=GQ,Number=1,Type=Integer,Description="Genotype Quality">
##FORMAT=<ID=HQ,Number=2,Type=Integer,Description="Haplotype Quality">
##contig=<ID=19>
##contig=<ID=20>
##contig=<ID=X>
##vcztools_viewCommand=view data/sample.vcz.zip; Date=2026-06-08 12:16:56.519846
##fileDate=20090805
##reference=1000GenomesPilot-NCBI36
##phasing=partial
##ALT=<ID=DEL:ME:ALU,Description="Deletion of ALU element">
##ALT=<ID=CNV,Description="Copy number variable region">
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	NA00001	NA00002	NA00003

19	111	.	A	C	9.6	.	.	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	.	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AF=0.017;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	.	GT	0/0	0|0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	.	GT	0	0/1	0|2

-H suppresses the header, which keeps the remaining examples compact:

!vcztools view -H data/sample.vcz.zip

19	111	.	A	C	9.6	.	.	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	.	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AF=0.017;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	.	GT	0/0	0|0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	.	GT	0	0/1	0|2

-s selects a subset of samples. INFO fields are recomputed for the subset by default:

!vcztools view -H -s NA00001,NA00003 data/sample.vcz.zip

19	111	.	A	C	9.6	.	AC=1;AN=4	GT:HQ	0|0:10,15	0/1:3,3
19	112	.	A	G	10	.	AC=1;AN=4	GT:HQ	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AC=2;AF=0.5;AN=4;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AC=0;AF=0.017;AN=4;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AC=1,3;AF=0.333,0.667;AN=4;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;AN=4;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,0;AN=2;DP=9;NS=3	GT:DP:GQ	0/1:4:.	./.:3:40
20	1235237	.	T	.	.	.	AN=2	GT	0/0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	AC=0,1,0;AN=3	GT	0	0|2

Per-record queries#

vcztools query extracts fields in a custom format. -l lists the samples:

!vcztools query -l data/sample.vcz.zip

NA00001
NA00002
NA00003

-f takes a format string; %-tags pull out site fields and a […] block loops over samples:

!vcztools query -f '%CHROM\t%POS\t%REF\t%ALT\t%INFO/DP\n' data/sample.vcz.zip

19	111	A	C	.
19	112	A	G	.
20	14370	G	A	14
20	17330	T	A	11
20	1110696	A	G,T	10
20	1230237	T	.	13
20	1234567	G	GA,GAC	9
20	1235237	T	.	.
X	10	AC	A,ATG,C	.

!vcztools query -f '%CHROM\t%POS\t%REF\t%ALT[\t%GT]\n' data/sample.vcz.zip

19	111	A	C	0|0	0|0	0/1
19	112	A	G	0|0	0|0	0/1
20	14370	G	A	0|0	1|0	1/1
20	17330	T	A	0|0	0|1	0/0
20	1110696	A	G,T	1|2	2|1	2/2
20	1230237	T	.	0|0	0|0	0/0
20	1234567	G	GA,GAC	0/1	0/2	./.
20	1235237	T	.	0/0	0|0	./.
X	10	AC	A,ATG,C	0	0/1	0|2

Counting records#

vcztools index does not build .csi/.tbi index files; it only answers the bcftools -n/-s queries. -n prints the total number of records:

!vcztools index -n data/sample.vcz.zip

9

-s prints per-contig statistics:

!vcztools index -s data/sample.vcz.zip

19	.	2
20	.	6
X	.	1

Region and target selection#

-r/--regions restricts output to one or more genomic intervals:

!vcztools view -H -r 20:1000000-1300000 data/sample.vcz.zip

20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	.	GT	0/0	0|0	./.

-t/--targets selects the same way but with bcftools’ streaming semantics (the two differ on how records straddling a region boundary are treated):

!vcztools view -H -t 20:1000000-1300000 data/sample.vcz.zip

20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	.	GT	0/0	0|0	./.

vcztools resolves regions and targets directly from the Zarr arrays, so no external index is required. The -R/--regions-file and -T/--targets-file variants read the same interval specifications from a file.

Recomputing INFO tags#

--fill-tags (re)computes selected INFO tags from the genotypes and emits them, replacing any stored value — the equivalent of piping bcftools output through +fill-tags. The supported tags are AC, AN, AF and NS:

!vcztools view -H --fill-tags AC,AN,AF,NS data/sample.vcz.zip

19	111	.	A	C	9.6	.	AC=1;AF=0.167;AN=6;NS=3	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	AC=1;AF=0.167;AN=6;NS=3	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AC=3;AF=0.5;AN=6;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AC=1;AF=0.167;AN=6;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AC=2,4;AF=0.333,0.667;AN=6;DB;DP=10;NS=3	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;AN=6;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AF=0.25,0.25;AN=4;DP=9;NS=2	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	AN=4;NS=2	GT	0/0	0|0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	AC=1,1,0;AF=0.2,0.2,0;AN=5;NS=3	GT	0	0/1	0|2

The tags are filled even for sites whose source INFO was empty. With a sample subset the counts are recomputed over the selected samples:

!vcztools view -H -s NA00001,NA00003 --fill-tags AC,AN data/sample.vcz.zip

19	111	.	A	C	9.6	.	AC=1;AN=4	GT:HQ	0|0:10,15	0/1:3,3
19	112	.	A	G	10	.	AC=1;AN=4	GT:HQ	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AC=2;AF=0.5;AN=4;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AC=0;AF=0.017;AN=4;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AC=1,3;AF=0.333,0.667;AN=4;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;AN=4;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,0;AN=2;DP=9;NS=3	GT:DP:GQ	0/1:4:.	./.:3:40
20	1235237	.	T	.	.	.	AN=2	GT	0/0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	AC=0,1,0;AN=3	GT	0	0|2

--fill-tags is mutually exclusive with -I/--no-update and -G/--drop-genotypes.

Filtering#

-i/--include and -e/--exclude take bcftools filter expressions over the site fields. Keep the high-quality sites:

!vcztools view -H -i 'QUAL>10' data/sample.vcz.zip

20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40

Drop a particular FILTER value:

!vcztools view -H -e 'FILTER="q10"' data/sample.vcz.zip

19	111	.	A	C	9.6	.	.	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	.	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.
20	1234567	microsat1	G	GA,GAC	50	PASS	AA=G;AC=1,1;AN=4;DP=9;NS=3	GT:DP:GQ	0/1:4:.	0/2:2:17	./.:3:40
20	1235237	.	T	.	.	.	.	GT	0/0	0|0	./.
X	10	rsTest	AC	A,ATG,C	10	PASS	.	GT	0	0/1	0|2

Expressions can reference INFO fields:

!vcztools view -H -i 'INFO/DP>10' data/sample.vcz.zip

20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AF=0.017;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.
20	1230237	.	T	.	47	PASS	AA=T;DP=13;NS=3	GT:DP:GQ:HQ	0|0:.:54:56,60	0|0:4:48:51,51	0/0:2:61:.,.

-v/--types (and -V/--exclude-types) filter by variant type:

!vcztools view -H -v snps data/sample.vcz.zip

19	111	.	A	C	9.6	.	.	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	.	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AF=0.017;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.
20	1110696	rs6040355	A	G,T	67	PASS	AA=T;AF=0.333,0.667;DB;DP=10;NS=2	GT:DP:GQ:HQ	1|2:6:21:23,27	2|1:0:2:18,2	2/2:4:35:.,.

-m/--min-alleles and -M/--max-alleles filter on the number of alleles; -m2 -M2 keeps only biallelic sites:

!vcztools view -H -m2 -M2 data/sample.vcz.zip

19	111	.	A	C	9.6	.	.	GT:HQ	0|0:10,15	0|0:10,10	0/1:3,3
19	112	.	A	G	10	.	.	GT:HQ	0|0:10,10	0|0:10,10	0/1:3,3
20	14370	rs6054257	G	A	29	PASS	AF=0.5;DB;DP=14;H2;NS=3	GT:DP:GQ:HQ	0|0:1:48:51,51	1|0:8:48:51,51	1/1:5:43:.,.
20	17330	.	T	A	3	q10	AF=0.017;DP=11;NS=3	GT:DP:GQ:HQ	0|0:3:49:58,50	0|1:5:3:65,3	0/0:3:41:.,.

See also#