CLI Reference

CLI Reference#

Every command accepts --backend-storage and --storage-option to read VCZ data from a remote URL (S3, GCS, Azure, HTTP); for example:

vcztools view --backend-storage fsspec s3://bucket/sample.vcz

See Storage backends for the available backends and their connection options.

vcztools view#

Convert VCZ dataset to VCF with efficient subsetting and filtering. Intended as a drop-in replacement for bcftools view, where we replace the VCF file path with a VCZ dataset URL.

This is an early version and not feature complete: if you are missing a particular piece of functionality please open an issue at sgkit-dev/vcztools#issues

Usage

vcztools view [OPTIONS] PATH

Options

-o, --output <output>#

File path to write output to (defaults to stdout ‘-‘).

-h, --header-only#

Output the VCF header only.

-H, --no-header#

Suppress the header in VCF output.

--no-version#

Do not append version and command line information to the output VCF header.

-I, --no-update#

Do not recalculate INFO fields for the sample subset. Mutually exclusive with –fill-tags.

-G, --drop-genotypes#

Drop genotypes.

--fill-tags <fill_tags>#

Comma-separated list of INFO tags to (re)compute and emit, replacing any source value. Supported: AC, AF, AN, NS. Mutually exclusive with –no-update and -G.

--encode-threads <encode_threads>#

Worker threads for per-chunk VCF line encoding. With >1, each chunk is split into this many contiguous row blocks encoded in parallel. Default: 4.

Selection options

-r, --regions <regions>#

Regions to include.

-R, --regions-file <regions_file>#

File of regions to include.

-t, --targets <targets>#

Target regions to include.

-T, --targets-file <targets_file>#

File of target regions to include.

-s, --samples <samples>#

Samples to include.

-S, --samples-file <samples_file>#

File of sample names to include.

--force-samples#

Only warn about unknown sample subsets.

-i, --include <include>#

Filter expression to include variant sites.

-e, --exclude <exclude>#

Filter expression to exclude variant sites.

-v, --types <types>#

Comma-separated list of variant types to include (snps,indels,mnps,other). A site is selected if any of its alleles matches one of the listed types.

-V, --exclude-types <exclude_types>#

Comma-separated list of variant types to exclude.

-m, --min-alleles <min_alleles>#

Print sites with at least INT alleles listed in REF and ALT.

-M, --max-alleles <max_alleles>#

Print sites with at most INT alleles listed in REF and ALT.

Zarr store options

--backend-storage <backend_storage>#

Zarr backend storage: omit for local-only (default), ‘fsspec’, ‘obstore’, or ‘icechunk’. The default supports .zip → ZipStore and local directories → LocalStore; URLs require an explicit backend.

--storage-option <storage_options>#

Backend storage option as KEY=VALUE (repeatable). VALUE is parsed as JSON if possible, falling back to a string.

Reader options

--readahead-workers <readahead_workers>#

Worker threads servicing the cross-chunk readahead pool. Default: 32.

--readahead-buffer-size <readahead_bytes>#

Cap on the readahead window. Accepts a byte count or a size string with suffix (e.g. ‘100M’, ‘2G’, ‘256MiB’). Default: 256MiB.

Logging options

--log-level <log_level>#

Logging verbosity.

Default:

'WARNING'

Options:

WARNING | INFO | DEBUG

--log-file <log_file>#

Write log output to FILE instead of stderr.

Arguments

PATH#

Required argument

vcztools query#

Transform VCZ into user-defined formats with efficient subsetting and filtering. Intended as a drop-in replacement for bcftools query, where we replace the VCF file path with a VCZ dataset URL.

This is an early version and not feature complete: if you are missing a particular piece of functionality please open an issue at sgkit-dev/vcztools#issues

Usage

vcztools query [OPTIONS] PATH

Options

-o, --output <output>#

File path to write output to (defaults to stdout ‘-‘).

-l, --list-samples#

List the sample IDs and exit.

-f, --format <format>#

The format of the output.

-N, --disable-automatic-newline#

Disable automatic addition of a missing newline character at the end of the formatting expression.

Selection options

-r, --regions <regions>#

Regions to include.

-R, --regions-file <regions_file>#

File of regions to include.

--force-samples#

Only warn about unknown sample subsets.

-s, --samples <samples>#

Samples to include.

-S, --samples-file <samples_file>#

File of sample names to include.

-t, --targets <targets>#

Target regions to include.

-T, --targets-file <targets_file>#

File of target regions to include.

-i, --include <include>#

Filter expression to include variant sites.

-e, --exclude <exclude>#

Filter expression to exclude variant sites.

Zarr store options

--backend-storage <backend_storage>#

Zarr backend storage: omit for local-only (default), ‘fsspec’, ‘obstore’, or ‘icechunk’. The default supports .zip → ZipStore and local directories → LocalStore; URLs require an explicit backend.

--storage-option <storage_options>#

Backend storage option as KEY=VALUE (repeatable). VALUE is parsed as JSON if possible, falling back to a string.

Reader options

--readahead-workers <readahead_workers>#

Worker threads servicing the cross-chunk readahead pool. Default: 32.

--readahead-buffer-size <readahead_bytes>#

Cap on the readahead window. Accepts a byte count or a size string with suffix (e.g. ‘100M’, ‘2G’, ‘256MiB’). Default: 256MiB.

Logging options

--log-level <log_level>#

Logging verbosity.

Default:

'WARNING'

Options:

WARNING | INFO | DEBUG

--log-file <log_file>#

Write log output to FILE instead of stderr.

Arguments

PATH#

Required argument

vcztools index#

Query the number of records in a VCZ dataset. This subcommand only implements the –nrecords and –stats options and does not build any indexes.

Usage

vcztools index [OPTIONS] PATH

Options

-n, --nrecords#

Print the number of records (variants).

-s, --stats#

Print per contig stats.

Zarr store options

--backend-storage <backend_storage>#

Zarr backend storage: omit for local-only (default), ‘fsspec’, ‘obstore’, or ‘icechunk’. The default supports .zip → ZipStore and local directories → LocalStore; URLs require an explicit backend.

--storage-option <storage_options>#

Backend storage option as KEY=VALUE (repeatable). VALUE is parsed as JSON if possible, falling back to a string.

Logging options

--log-level <log_level>#

Logging verbosity.

Default:

'WARNING'

Options:

WARNING | INFO | DEBUG

--log-file <log_file>#

Write log output to FILE instead of stderr.

Arguments

PATH#

Required argument

vcztools view-bgen#

Generate BGEN output from a VCZ dataset.

By default stream the .bgen payload to stdout (symmetric with view). With -o STEM, write foo.bgen + foo.bgen.bgi + foo.sample; sidecars are individually suppressible (–no-bgi, –no-sample-file).

Phase is propagated per-variant from call_genotype_phased if present; pass --unphased to force every variant unphased . Sample/region selection mirrors bcftools view (-s/-S/-r/-R/-t/-T/-v/-V/-m/-M). Multi-allelic variants are rejected by default; pass -M 2 (or --max-alleles 2) to skip them.

Unlike vcztools view / query, -i/-e filters are evaluated over the selected samples: with a -s/-S subset, AC/AN/AF/NS in a filter expression are recomputed for that subset rather than read from the file’s stored (full-cohort) INFO.

See the “BGEN” documentation page for details.

Usage

vcztools view-bgen [OPTIONS] PATH

Options

-o, --output <output>#

Output stem; taken verbatim. Absent: stream .bgen to stdout (no sidecars). Present: -o foo writes foo.bgen plus, by default, foo.bgen.bgi and foo.sample.

--compression-level <compression_level>#

zlib compression level for the BGEN genotype probability blocks. Default: 1 for variable-size output; required to be 0 when –fixed-variant-size is set. 1 is fast and within ~10-30% of the size of level 6 on hard-call BGEN; -1 = zlib default (~6); 0 = stored (no compression); 9 = max.

--fixed-variant-size#

Produce a fixed-stride BGEN where every variant block is exactly the same number of bytes wide (random-access, BgenEncoder path). Requires –compression-level=0 (default in this mode) and uniform ploidy across the store. The –total-string-length and –pad-byte options feed the fixed-stride encoder’s per-variant string-slot budget and the filler byte for the padding slot beyond its leading ‘.’; they are inert without –fixed-variant-size. See the ‘Fixed-size random-access encoding’ docs section.

--no-bgi#

Skip the bgenix .bgen.bgi SQLite index sidecar.

--no-sample-file#

Skip the Oxford .sample sidecar. Distinct from -S/–samples-file, which filters input.

--no-header-samples#

Omit sample IDs from the BGEN header (clears SAMPLE_IDS_PRESENT). Combine with –no-sample-file at your peril: most downstream tools require sample IDs from one source or the other.

--unphased#

Force every variant’s phased flag to 0, ignoring call_genotype_phased. Required for qctool -snp-stats, which rejects per-haplotype-per-allele probabilities.

--pad-byte <pad_byte>#

Single ASCII char used to fill the padding slot beyond its leading ‘.’. Default: ‘.’.

--total-string-length <total_string_length>#

Combined byte budget (default 64) for the five BGEN string slots.

--variant-id-field <variant_id_field>#

Which BGEN slot carries the zarr variant_id. The other slot is written as a literal ‘.’ for every variant.

Default:

'rsid'

Options:

rsid | varid

Selection options

-r, --regions <regions>#

Regions to include.

-R, --regions-file <regions_file>#

File of regions to include.

-t, --targets <targets>#

Target regions to include.

-T, --targets-file <targets_file>#

File of target regions to include.

-s, --samples <samples>#

Samples to include.

-S, --samples-file <samples_file>#

File of sample names to include.

--force-samples#

Only warn about unknown sample subsets.

-i, --include <include>#

Filter expression to include variant sites.

-e, --exclude <exclude>#

Filter expression to exclude variant sites.

-v, --types <types>#

Comma-separated list of variant types to include (snps,indels,mnps,other). A site is selected if any of its alleles matches one of the listed types.

-V, --exclude-types <exclude_types>#

Comma-separated list of variant types to exclude.

-m, --min-alleles <min_alleles>#

Print sites with at least INT alleles listed in REF and ALT.

-M, --max-alleles <max_alleles>#

Print sites with at most INT alleles listed in REF and ALT.

Zarr store options

--backend-storage <backend_storage>#

Zarr backend storage: omit for local-only (default), ‘fsspec’, ‘obstore’, or ‘icechunk’. The default supports .zip → ZipStore and local directories → LocalStore; URLs require an explicit backend.

--storage-option <storage_options>#

Backend storage option as KEY=VALUE (repeatable). VALUE is parsed as JSON if possible, falling back to a string.

Reader options

--readahead-workers <readahead_workers>#

Worker threads servicing the cross-chunk readahead pool. Default: 32.

--readahead-buffer-size <readahead_bytes>#

Cap on the readahead window. Accepts a byte count or a size string with suffix (e.g. ‘100M’, ‘2G’, ‘256MiB’). Default: 256MiB.

Logging options

--log-level <log_level>#

Logging verbosity.

Default:

'WARNING'

Options:

WARNING | INFO | DEBUG

--log-file <log_file>#

Write log output to FILE instead of stderr.

Arguments

PATH#

Required argument