Home

Index, extract, validate, and inspect uncompressed FASTA with one static executable.

Install | Five-minute start | Cheat sheet | Troubleshooting

I built z-fasta to keep four common FASTA jobs in one place: check a file, index it, pull out the records you need, and understand what is inside. When exact behavior matters, this Wiki gets specific about coordinates, sidecars, output, and failure modes.

Note

This Wiki documents z-fasta v0.4.0. Run z-fasta --version before following version-specific behavior.

Start with this workflow

z-fasta validate reference.fa
z-fasta index reference.fa
z-fasta get reference.fa chr1:1000-2000
z-fasta stats reference.fa

Four commands take you from an unfamiliar reference to a checked, indexed, queryable file. The extraction uses 1-based inclusive coordinates.

reference.fa
    |
    +-> validate
    |
    +-> index -> reference.fa.zfi
                       |
                       +-> get   -> selected FASTA
                       |
                       +-> stats -> sequence report

What are you here to do?

• Try z-fasta for the first time: Install it, then work through the five-minute example.
• Extract a sequence or interval: Start with Extracting sequences for records, regions, names files, and transforms.
• Use BED or preserve feature strand: Go to BED and strand workflows. It keeps the two coordinate systems explicit.
• Understand or clean up an odd FASTA: Read Validation and repair before changing the source.
• Share an index with FAI-based tools: Read Index formats before choosing --emit-fai.
• Recover from an error: Match the stderr message in Troubleshooting.

Why use z-fasta?

• One dependency-free executable for Linux and macOS on x86_64 and arm64.
• Default .zfi indexes embed names, source identity, and side tables for messy records.
• Positional GET behavior is checked for byte equality with samtools faidx on the verified path.
• BED, names, reverse-complement, and messy-layout extraction have dedicated correctness coverage.
• Stats scans indexed sequence spans and reports nucleotide or protein composition, Nx, auN, quartiles, and extrema.
• Validate counts every documented structure, identifier, alphabet, and layout problem in one streaming pass, then can write a repaired copy to a separate file.

Know the boundary

I intentionally keep z-fasta focused on uncompressed FASTA. FASTQ is coming as a separate project, z-fastq, with the same focus on speed, low memory use, and portability. Supporting gzip or BGZF well would require real work on deflate performance, and I have not been able to justify that work yet. If your workflow starts outside that boundary, Choosing a FASTA tool will save you time.

The reading path I recommend

1. Install the binary.
2. Run the first workflow.
3. Keep the command cheat sheet nearby.
4. Open a command page when the basic workflow needs more control.
5. Use the concept pages when index choice, coordinates, identifiers, or classification affect correctness.