Tabix Index

A tabix index is a sidecar file that turns a BGZF-compressed, coordinate-sorted tab-delimited file into a random-access database: given chr19:44,905,791-44,909,393, it returns the byte ranges in the compressed file that could contain those records. It was introduced as a generalization of BAM indexing to any TAB-delimited genome position file, which is why the same tool indexes VCF, BED, GFF, and custom formats.¹

How it works

Two pieces have to line up. First, compression: the file must be in BGZF, not plain gzip. BGZF is gzip with the file split into blocks of at most 64 kB, each a valid gzip member with its size recorded in the extra field. A virtual file offset packs the block’s offset in the file (48 bits) with the offset inside the decompressed block (16 bits) into one 64-bit integer, so you can decompress exactly one block and start reading mid-record.

Second, the index. Tabix uses a UCSC-style binning scheme: the genome is divided into a hierarchy of bins (16 kb at the finest level, then 128 kb, 1 Mb, 8 Mb, 64 Mb, 512 Mb), each record is assigned to the smallest bin containing it, and each bin stores a list of virtual-offset chunks. A separate linear index stores, for each 16 kb window, the smallest virtual offset of any record overlapping it, which lets the query discard chunks that start too early. A region query collects the bins that overlap it, unions their chunks, prunes with the linear index, then decompresses and filters the resulting records.

The .tbi header also records which columns hold sequence, start, and end, whether coordinates are 0- or 1-based, the comment character, and how many header lines to skip. That is the whole “generic” part: -p vcf is shorthand for -s 1 -b 2 -e 2 -c '#' with 1-based coordinates.

In your own data

The actual commands, on a VCF produced by DeepVariant or GATK:

bcftools sort -Oz -o sample.vcf.gz sample.vcf
bcftools index -t sample.vcf.gz        # writes sample.vcf.gz.tbi
# or, equivalently:
bgzip -@ 8 sample.vcf && tabix -p vcf sample.vcf.gz

Then query:

bcftools view -r chr19:44905791-44909393 sample.vcf.gz
tabix sample.vcf.gz chr19:44905791-44909393

Failure modes we hit repeatedly:

• [E::hts_idx_push] Chromosome blocks not continuous. The file is not sorted, or contigs are interleaved. Run bcftools sort (use -T to point at a disk with space; a 100 GB VCF will spill).
• not a BGZF file. Someone ran gzip instead of bgzip. Check with htsfile sample.vcf.gz, which prints VCF version 4.2 BGZF-compressed variant calling data. A plain-gzip file decompresses fine and silently fails to index.
• [E::hts_idx_push] Chromosome ... length exceeds 2^29. The .tbi format caps contigs at 512 Mbp. For chr1 in a standard human build this never triggers, but it does for polyploid plant genomes or concatenated references. Use CSI: bcftools index -c sample.vcf.gz or tabix --csi -p vcf, which uses a configurable depth (-m 14 gives a 16 kb minimum bin by default).
• Truncated index from a killed job. The .tbi is written at the end, so a partial file usually errors out rather than returning wrong answers, but always confirm the .tbi mtime is newer than the .vcf.gz.
• Contig naming. chr19 vs 19 is the single most common reason a region query returns nothing with no error. tabix -l sample.vcf.gz lists the sequence names in the index.

Tabix is also what makes remote access work: bcftools view -r chr1:1000000-1001000 https://.../file.vcf.gz fetches the index and then issues HTTP range requests for the relevant blocks. GWAS summary statistics stored as VCF with a tabix index get the same behavior, which is the argument for the GWAS-VCF specification.² R packages like seqminer use tabix ranges to pull only the variants in a gene before running burden tests.³ Long-read methylation viewers index per-read modification calls the same way, so plotting a locus does not require loading the genome.⁴

Limitations

The index answers one question: which byte ranges might overlap this interval. It cannot find a variant by rsID, by allele, or by sample genotype without scanning. For “which samples carry this variant” across thousands of genomes, a positional index is the wrong data structure, and variation-graph or succinct indexes built for variant search scale better.⁵ Tabix also compresses nothing extra: a GWAS summary file stays as large as BGZF makes it, whereas format-aware schemes get substantially smaller files with comparable query speed.⁶

Practical ceilings: a .tbi for a dense whole-genome VCF runs a few megabytes, which is fine, but a query for a 100 Mb region will decompress 100 Mb of data, so tabix helps with narrow intervals, not whole-chromosome sweeps. And tools that walk the file linearly (VCF summarizers, pairwise distance calculators) get no benefit from the index at all.⁷⁸ Any clinical reading of what a variant means is a conversation with a clinician or genetic counselor, not a tabix query.

Woolf Software builds longitudinal molecular profiles of individuals: whole-genome sequencing, RNA sequencing, proteomics, blood biomarkers, and continuous glucose data, integrated into one model of you. Build your profile.