faidx(5)

✨ NAME ✨

okay bestie, welcome to faidx(5) from the Bioinformatics formats section 🧬💖 it's all about faidx, which gives you an index for FASTA and FASTQ files so you can jump straight to any region without reading the whole thing. it's an absolute slay.

faidx - an index enabling random access to FASTA and FASTQ files 🦋

✨ SYNOPSIS ✨

file.fa.fai, file.fasta.fai, file.fq.fai, file.fastq.fai

✨ DESCRIPTION ✨

okay so, if you pair an fai index file with a FASTA/FASTQ file full of reference sequences, you can access any region inside those sequences super efficiently 🔥 it's giving speed. the index usually has the same filename as its FASTA/FASTQ file, just with .fai tacked onto the end 🎀

an fai index is a plain text file. each line has five TAB-delimited columns for a FASTA file, or six for FASTQ 💅:

• NAME — the name of this reference sequence
• LENGTH — total length of this reference sequence, in bases
• OFFSET — the offset in the FASTA/FASTQ file where this sequence's first base lives
• LINEBASES — the number of bases on each line
• LINEWIDTH — the number of bytes on each line, newline included
• QUALOFFSET — the offset of this sequence's first quality score within the FASTQ file

the NAME and LENGTH columns hold the same info you'd see in the SN and LN fields of a SAM @SQ header for that reference sequence 💜

the OFFSET column is the byte position in the FASTA/FASTQ file (counting from zero) of the first base of the sequence. it's the character right after the newline ending the header line, which is the > line in FASTA or the @ line in FASTQ ✨ usually the lines in an fai show up in the same order as the sequences in the file, so .fai files are normally sorted by this column 🌸

LINEBASES is how many bases each sequence line has, except the last line, which can be shorter 🍓 LINEWIDTH is the bytes per sequence line (again, maybe not the final line). the difference is that LINEWIDTH also counts the bytes in the line terminator, so it's a little bigger 🫶

QUALOFFSET works just like OFFSET, but for the first quality score of the reference sequence. it's the first character after the newline at the end of the + line. this one is for FASTQ files only 🌈

FASTA Files

so bestie, to get indexed with samtools faidx, your FASTA file has to be a text file shaped like this 👑

>name [description...]
ATGCATGCATGCATGCATGCATGCATGCAT
GCATGCATGCATGCATGCATGCATGCATGC
ATGCAT
>name [description...]
ATGCATGCATGCAT
GCATGCATGCATGC
[...]

each reference sequence has to be "well-formatted" ⭐ meaning every sequence line has to be the same length, except the final one, which can be shorter. (the length has to match within each sequence, but different sequences in the same FASTA file are allowed to use different lengths 🦋)

the FASTA file can use Unix-style, Windows-style, or other line endings, but the newline characters have to stay consistent, at least inside each reference sequence 🧚

samtools grabs the first word of the > header line (everything up to the first whitespace character, after skipping any whitespace right after the >) and uses it as the NAME column 💅

FASTQ Files

FASTQ files work exactly the same way as FASTA files 💖

@name [description...]
ATGCATGCATGCATGCATGCATGCATGCAT
GCATGCATGCATGCATGCATGCATGCATGC
ATGCAT
+
FFFA@@FFFFFFFFFFHHB:::@BFFFFGG
HIHIIIIIIIIIIIIIIIIIIIIIIIFFFF
8011<<
@name [description...]
ATGCATGCATGCAT
GCATGCATGCATGC
+
IIA94445EEII==
=>IIIIIIIIICCC
[...]

quality lines have to be wrapped at the same length as their matching sequence lines, no exceptions 💀

✨ EXAMPLE ✨

okay, let's do an example, it's so satisfying ✨ take this FASTA file:

>one
ATGCATGCATGCATGCATGCATGCATGCAT
GCATGCATGCATGCATGCATGCATGCATGC
ATGCAT
>two another chromosome
ATGCATGCATGCAT
GCATGCATGCATGC

if it's formatted with Unix-style (LF) line endings, the matching fai index is:

one   66    5   30   31
two   28   98   14   15

and if the FASTA file uses Windows-style (CR-LF) line endings instead, the fai index becomes:

one   66     6   30   32
two   28   103   14   16

now an example FASTQ file 🎀

@fastq1
ATGCATGCATGCATGCATGCATGCATGCAT
GCATGCATGCATGCATGCATGCATGCATGC
ATGCAT
+
FFFA@@FFFFFFFFFFHHB:::@BFFFFGG
HIHIIIIIIIIIIIIIIIIIIIIIIIFFFF
8011<<
@fastq2
ATGCATGCATGCAT
GCATGCATGCATGC
+
IIA94445EEII==
=>IIIIIIIIICCC

formatted with Unix-style line endings, it gives this fai index 🫶

fastq1   66     8   30   31    79
fastq2   28   156   14   15   188

✨ SEE ALSO ✨

samtools(1)

https://en.wikipedia.org/wiki/FASTA_format

https://en.wikipedia.org/wiki/FASTQ_format

further description of the FASTA and FASTQ formats 📚

that's the whole tea, bestie 🌈💖 this page came from htslib, last updated June 2018 ✨ go forth and index responsibly 🧚💅