pyfaidx

pyfaidx is a Python module designed for fast random access to subsequences in FASTA files. It implements pure Python classes for indexing, retrieval, and in-place modification of FASTA files using a .fai index format that is compatible with Samtools' faidx function.

Key features include:

• Fast Random Access: Uses a small flat index file (.fai) to load minimal amounts of data into memory.
• API Compatibility: Compatible with the pygr seqdb module.
• CLI Tool: Includes a faidx command-line script for complex FASTA file manipulation without writing code.

You can install pyfaidx via PyPI using pip. The package is tested on Linux and macOS using Python 3.7+.

To install for the current user (if you do not have root access):

pip install pyfaidx

Alternatively, you can download a release and install from the source directory:

pip install .

Note for Python 2 users: If you are using Python 2.6 or 2.7, you must use version v0.7.2 or earlier.

By default, Fasta objects are read-only. To modify the contents of your FASTA file in-place, pass mutable=True to the constructor. This returns MutableFastaRecord objects.

Warning: Any changes made to a sequence via assignment will be written to the file immediately and permanently.

from pyfaidx import Fasta

# Enable in-place modification
genes = Fasta('tests/data/genes.fasta', mutable=True)

# Replace a segment with a new string of the same length
genes['NM_001282543.1'][:10] = 'NNNNNNNNNN'

You can access FASTA files stored on remote filesystems (like S3) by passing an fsspec file object to the Fasta constructor (new in v0.7.0).

import fsspec
from pyfaidx import Fasta

# Open a file from S3 using fsspec
of = fsspec.open("s3://broad-references/hg19/v0/Homo_sapiens_assembly19.fasta", anon=True)

# Pass the file object to Fasta
genes = Fasta(of)

If you install pyfaidx using the --user flag, you must manually add the local bin directory to your $PATH to use the faidx command-line script.

• Linux: Add /home/$USER/.local/bin to your $PATH.
• macOS: Add /Users/$USER/Library/Python/{python version}/bin to your $PATH.

To improve performance during sequential access (e.g., reading through a chromosome), you can use a read-ahead buffer by setting the read_ahead parameter in the Fasta constructor. This can reduce runtime by up to 1/2 for sequential accesses to buffered regions.

from pyfaidx import Fasta

# Initialize with a read-ahead buffer (e.g., 10,000 bases)
genes = Fasta('tests/data/genes.fasta', read_ahead=10000)

# Sequential access is now faster
for i in range(0, 100000, 100):
    print(genes['NM_001282543.1'][i:i+100])

When reading a FASTA file, if multiple entries result in the same key (after applying key_function), the duplicate_action parameter determines the behavior:

• "stop": Raises a ValueError.
• "first": Keeps only the first occurrence.
• "last": Keeps only the last occurrence.
• "longest": Keeps the sequence with the greatest length.
• "shortest": Keeps the sequence with the smallest length.
• "drop": Drops the duplicate key entirely.

A FastaRecord represents a single contig/chromosome from a FASTA file. It behaves like a sequence container:

• Slicing: Supports __getitem__ with integers or slices. Slices return a Sequence object (or a string if as_raw=True was set in the parent Fasta object).
• Iteration: __iter__ provides a line-based generator that respects the original file's line lengths.
• Properties:
  • len(record): Returns the total length of the contig.
  • record.long_name: Returns the full defline (description) from the FASTA header.
  • record.unpadded_len: Returns the length of the contig excluding leading/trailing 'N' padding.
  • record.variant_sites: (Only for FastaVariant) Returns a tuple of SNP positions.

MutableFastaRecord inherits from FastaRecord and adds __setitem__ support to allow in-place modification of the underlying file.

You can modify an existing FASTA file in-place using the faidx CLI to mask sequences.

Masking Options:

• --mask-with-default-seq: Replaces sequence content with the character provided in --default-seq (e.g., -s N).
• --mask-by-case: Converts the sequence to lowercase.

Note: Masking requires the FASTA file to be opened in mutable mode (handled internally by the CLI).

# Mask regions in a BED file with 'N'
faidx input.fasta --bed regions.bed --mask-with-default-seq -s N

# Convert the entire file to lowercase
faidx input.fasta --mask-by-case

You can perform standard DNA operations on Sequence objects using .complement, .reverse, or the unary negation operator - for the reverse complement.

from pyfaidx import Fasta

genes = Fasta('tests/data/genes.fasta')
segment = genes['NM_001282543.1'][200:230]

# Complement
print(segment.complement)

# Reverse
print(segment.reverse)

# Reverse complement (using unary minus)
print(-segment)