tabix(1)

💅 tabix(1) — the bestie's guide to the generic indexer 💅

ok so you opened the manual for tabix, from the Bioinformatics tools manual set, and honestly? you came to the right place. sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ NAME ✨

tabix — the generic indexer for TAB-delimited genome position files. that's it, that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

tabix [-0lf] [-p gff|bed|sam|vcf] [-s seqCol] [-b begCol] [-e endCol]
[-S lineSkip] [-c metaChar] in.tab.bgz [region1 [region2 [...]]]

---

🦋 DESCRIPTION 🦋

okay so here's what's happening. tabix takes a TAB-delimited genome position file called in.tab.bgz and indexes it — and when there's no region on the command line, it creates an index file for you: either in.tab.bgz.tbi or in.tab.bgz.csi. two possible names, one iconic little sidecar file. ✨

the input data file has got to be position sorted, and compressed by bgzip, which has a gzip(1)-like interface. no cap. if it's not sorted and bgzipped, we're not doing this.

once it's indexed, tabix can quickly retrieve the data lines that overlap regions you specify in the format "chr:beginPos-endPos". and heads up bestie — the coordinates in that region format are 1-based and inclusive. 💅

and the fast data retrieval also works over the network if you give a URI as the file name — and in that case, if the index file isn't already sitting locally, it'll be downloaded for you. it's giving self-sufficient. 🫶

now, the .tbi and BAI index formats can handle individual chromosomes up to 512 Mbp (2^29 bases) in length. so if your input file might contain data lines with begin or end positions greater than that, you will need to use a CSI index. periodt.

also: multiple threads can be used for operations — except listing of sequence names. that one's a solo act. 🙈

---

🎀 INDEXING OPTIONS 🎀

• -0, --zero-based — tells tabix that the position in the data file is 0-based half-open (like the UCSC files do it) rather than 1-based. know the difference, it matters.
• -b, --begin INT — which column is the start chromosomal position. default is [4].
• -c, --comment CHAR — skip lines that start with the character CHAR. default is [#]. very "ignore the haters" of it.
• -C, --csi — produce a CSI format index instead of the classical tabix or BAI style indices. big chromosome energy. 🔥
• -e, --end INT — which column is the end chromosomal position. fun fact: the end column can be the same as the start column. default [5].
• -f, --force — force overwrite of the index file if one's already there. ruthless. slay.
• -m, --min-shift INT — set the minimal interval size for CSI indices to 2^INT. default [14].
• -p, --preset STR — the input format for indexing. valid values are: gff, bed, sam, vcf. ⚠️ this option should not be applied together with any of -s, -b, -e, -c and -0. and it's not used for data retrieval, because this setting is stored in the index file. default is [gff].
• -s, --sequence INT — which column is the sequence name. heads up: -s, -b, -e, -S, -c and -0 are all stored in the index file, and thus not used in data retrieval. default [1].
• -S, --skip-lines INT — skip the first INT lines in the data file. default [0].

---

🧚 QUERYING AND OTHER OPTIONS 🧚

• -h, --print-header — print the header/meta lines too, not just the data.
• -H, --only-header — print only the header/meta lines. main character only, everyone else go home. 💀
• -l, --list-chroms — list the sequence names stored in the index file.
• -r, --reheader FILE — replace the header with the content of FILE.
• -R, --regions FILE — restrict to the regions listed in the FILE. the FILE can be a BED file (this requires a .bed, .bed.gz, or .bed.bgz file name extension) or a TAB-delimited file with CHROM, POS, and, optionally, POS_TO columns, where positions are 1-based and inclusive. and ooh — when this option is in use, the input file may not be sorted. plot twist. 😭
• -T, --targets FILE — similar to -R, but the entire input will be read sequentially and regions not listed in FILE will be skipped.
• -D — do not download the index file before opening it. valid for remote files only.
• --cache INT — set the BGZF block cache size to INT megabytes. default [10]. this is of most benefit when the -R option is used, since that can cause blocks to be read more than once. setting the size to 0 will disable the cache.
• --separate-regions — use this when you've supplied multiple regions on the command line and you need to quickly see which file records belong to which region. how? a line with the name of the region — preceded by the file-specific comment symbol — gets inserted in the output before its corresponding group of records. labelled. organized. iconic. 🎀
• --verbosity INT — set the verbosity of logging messages printed to stderr. default is 3, which turns on error and warning messages; 2 reduces warning messages; 1 prints only error messages and 0 is mostly silent. values higher than 3 produce additional informational and debugging messages. pick your noise level, bestie.
• -@, --threads INT — set the number of threads to use for the operation. default is 0, where no extra threads are in use.

---

🌈 EXAMPLE 🌈

like, here's the whole ritual, start to finish:

(grep "^#" in.gff; grep -v "^#" in.gff | sort -t"`printf '\t'`" -k1,1
-k4,4n) | bgzip > sorted.gff.gz;

tabix -p gff sorted.gff.gz;

tabix sorted.gff.gz chr1:10,000,000-20,000,000;

sort it, bgzip it, index it, query it. the whole arc. 🦋

---

💜 NOTES 💜

ok so technically, it is straightforward to achieve overlap queries using the standard B-tree index (with or without binning) implemented in all SQL databases, or the R-tree index in PostgreSQL and Oracle. like, sure. but there are still so many reasons to use tabix:

1. firstly, tabix directly works with a lot of widely used TAB-delimited formats such as GFF/GTF and BED. we do not need to design a database schema or specialized binary formats. and the data do not need to be duplicated in different formats, either. no duplicates, no drama.
2. secondly, tabix works on compressed data files while most SQL databases do not. the GenCode annotation GTF can be compressed down to 4%. absolutely ate.
3. thirdly, tabix is fast. the same indexing algorithm is known to work efficiently for an alignment with a few billion short reads. SQL databases probably cannot easily handle data at this scale. ngl, that's a lot.
4. last but not the least, tabix supports remote data retrieval. one can put the data file and the index at an FTP or HTTP server, and other users or even web services will be able to get a slice without downloading the entire file. sharing is caring. 🫶

---

👑 AUTHOR 👑

Tabix was written by Heng Li. the BGZF library was originally implemented by Bob Handsaker and modified by Heng Li for remote file access and in-memory caching. legends, both of them. 💖

---

🔥 SEE ALSO 🔥

• bgzip(1)
• samtools(1)

---

and that's the whole thing, bestie — this page you've been reading lives in htslib-1.22.1, dated 14 July 2025, so go forth and index responsibly. 🎀💅✨