BGEN conversion

BGEN conversion#

vcztools view-bgen transcodes a VCZ store into the Oxford BGEN format. Without -o it streams the .bgen payload to stdout; with -o STEM it writes STEM.bgen plus the STEM.bgen.bgi (bgenix index) and STEM.sample (Oxford text) sidecars. The format details are documented in the BGEN file format page; this page walks through the command.

The examples run against the example dataset data/sample.vcz.zip (see Reading VCZ).

Basic conversion#

As with PLINK, multi-allelic sites are rejected, so -M 2 skips them. The sample data is mixed-phase; --unphased emits every variant unphased (see the BGEN file format page for the phasing rules):

!vcztools view-bgen data/sample.vcz.zip -M 2 --unphased -o sample

This writes the payload and its two sidecars:

!ls sample.bgen sample.bgen.bgi sample.sample

sample.bgen  sample.bgen.bgi  sample.sample

The .bgen is binary. The Oxford .sample sidecar lists the samples:

!cat sample.sample

ID_1 ID_2 missing
0 0 0
NA00001 NA00001 0
NA00002 NA00002 0
NA00003 NA00003 0

Subsetting by sample#

Pass -s (or -S FILE) to convert only a subset of samples:

!vcztools view-bgen data/sample.vcz.zip -M 2 --unphased -s NA00001,NA00003 -o subset

The .sample sidecar now lists just those samples:

!cat subset.sample

ID_1 ID_2 missing
0 0 0
NA00001 NA00001 0
NA00003 NA00003 0

Only the selected samples are read from the store, so subsetting a handful of samples out of a very wide cohort is cheap — the full cohort is never materialised.

Filtering over the sample subset#

-i/-e expression filters that reference sample-derived INFO fields (AC, AN, AF, NS) are evaluated over the selected samples. With a -s/-S subset, those values are recomputed for that subset rather than read from the file’s stored (full-cohort) INFO, so view-bgen -s cohort.txt -i 'AC>0' keeps the variants polymorphic in your cohort.

This is deliberately different from vcztools view and vcztools query, which follow bcftools and evaluate -i/-e against the original record’s stored INFO. A BGEN fileset feeds an association analysis on the exported cohort, so filters should reflect that cohort, not the source dataset; it is also cheaper on large datasets, since only the selected samples are read. The allele-based filters (-m/-M/-v/-V) remain record-level.

Sidecars and compression#

Streaming mode (no -o) writes only the .bgen payload. With -o, suppress either sidecar with --no-bgi or --no-sample-file. The genotype blocks are zlib-compressed; --compression-level tunes the level (default 1).