What a FASTA .fai index stores
Each tab-separated row records a sequence name, residue length, byte offset of its first residue, bases per full sequence line, and total bytes per line including the terminator. That makes exact random access possible without scanning the whole reference for every query. LF and CRLF files therefore have different offsets and line widths even when their sequences are identical.
Indexability checks
Within each FASTA record, every non-final sequence line must use the same number of bases and the same byte width. Only the final line may be shorter. This audit also reports blank lines, sequence bytes outside printable ASCII, duplicate first-word names, empty records, content before the first header, and characters outside IUPAC nucleotide codes. The latter is only a warning because protein FASTA files are valid inputs too.
Validation boundary
This generates and checks the five-column uncompressed FASTA index, not every samtools feature. It does not create BGZF .gzi indexes, parse FASTQ, build sequence dictionaries, compare biological assemblies, calculate cryptographic sequence digests, normalize headers, or prove that residues are scientifically correct. Before production use, verify the downloaded index with your current samtools/htslib workflow.
Frequently asked questions
Why does changing line endings invalidate an index?
Offsets and line widths count bytes. Replacing LF with CRLF adds one byte per line, moving later records even though the displayed sequence is unchanged.
Can I inspect protein FASTA?
Yes. Protein letters outside the nucleotide alphabet appear in the “Other” count and produce a warning, but offsets and lengths are still generated.
Are region coordinates zero-based?
No. Region extraction uses 1-based inclusive coordinates, the convention used by samtools faidx.
Authoritative reference
The htslib faidx manual defines the five columns, first-word naming, byte offsets, wrapping requirement, and line-width behavior implemented here.
Inspect a VOTable catalog · Audit a SAC waveform · Browse scientific-data tools