Version Compatibility

Reference examples tested with: BioPython 1.83+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Alignment File I/O

Read, write, and convert multiple sequence alignment files in various formats.

Required Import

Goal: Load modules for reading, writing, and manipulating multiple sequence alignments.

Approach: Import AlignIO for file I/O and supporting classes for programmatic alignment construction.

python
from Bio import AlignIO
from Bio.Align import MultipleSeqAlignment
from Bio.SeqRecord import SeqRecord
from Bio.Seq import Seq

Supported Formats

| Format | Extension | Read | Write | Description | |--------|-----------|------|-------|-------------| | clustal | .aln | Yes | Yes | Clustal W/X output | | fasta | .fasta, .fa | Yes | Yes | Aligned FASTA | | phylip | .phy | Yes | Yes | Interleaved PHYLIP | | phylip-sequential | .phy | Yes | Yes | Sequential PHYLIP | | phylip-relaxed | .phy | Yes | Yes | PHYLIP with long names | | stockholm | .sto, .stk | Yes | Yes | Pfam/Rfam annotated | | nexus | .nex | Yes | Yes | NEXUS format | | emboss | .txt | Yes | No | EMBOSS tools output | | fasta-m10 | .txt | Yes | No | FASTA -m 10 output | | maf | .maf | Yes | Yes | Multiple Alignment Format | | mauve | .xmfa | Yes | No | progressiveMauve output | | msf | .msf | Yes | No | GCG MSF format |

Reading Alignments

"Read an alignment file" → Parse an alignment file into an alignment object with sequences and metadata accessible.

Goal: Load alignment data from files in various formats (Clustal, PHYLIP, Stockholm, FASTA).

Approach: Use AlignIO.read() for single-alignment files or AlignIO.parse() for files containing multiple alignments.

Single Alignment File

python
from Bio import AlignIO

alignment = AlignIO.read('alignment.aln', 'clustal')
print(f'Alignment length: {alignment.get_alignment_length()}')
print(f'Number of sequences: {len(alignment)}')

Multiple Alignments in One File

python
for alignment in AlignIO.parse('multi_alignment.sto', 'stockholm'):
    print(f'Alignment with {len(alignment)} sequences, length {alignment.get_alignment_length()}')

Read as List

python
alignments = list(AlignIO.parse('alignments.phy', 'phylip'))
print(f'Read {len(alignments)} alignments')

Writing Alignments

Goal: Save alignment data to files in standard formats for downstream tools or archival.

Approach: Use AlignIO.write() with the target format specifier, supporting single or multiple alignments and file handles.

Write Single Alignment

python
AlignIO.write(alignment, 'output.fasta', 'fasta')

Write Multiple Alignments

python
alignments = [alignment1, alignment2, alignment3]
count = AlignIO.write(alignments, 'output.sto', 'stockholm')
print(f'Wrote {count} alignments')

Write to Handle

python
with open('output.aln', 'w') as handle:
    AlignIO.write(alignment, handle, 'clustal')

Format Conversion

"Convert alignment format" → Transform an alignment file from one format to another (e.g., Clustal to PHYLIP).

Goal: Convert alignment files between formats for compatibility with different analysis tools.

Approach: Use AlignIO.convert() for direct one-step conversion, or read-modify-write for cases requiring intermediate manipulation.

Direct Conversion (Most Efficient)

python
AlignIO.convert('input.aln', 'clustal', 'output.phy', 'phylip')

With Alphabet Specification

python
AlignIO.convert('input.sto', 'stockholm', 'output.nex', 'nexus', molecule_type='DNA')

Manual Conversion (When Modification Needed)

python
alignment = AlignIO.read('input.aln', 'clustal')
# ... modify alignment ...
AlignIO.write(alignment, 'output.fasta', 'fasta')

Accessing Alignment Data

Goal: Navigate and extract data from alignment objects including sequences, columns, and slices.

Approach: Use iteration, indexing, and column slicing on the alignment object.

python
alignment = AlignIO.read('alignment.aln', 'clustal')

# Iterate over sequences
for record in alignment:
    print(f'{record.id}: {record.seq}')

# Access by index
first_seq = alignment[0]
last_seq = alignment[-1]

# Slice columns
column_slice = alignment[:, 10:20]  # Columns 10-19

# Get specific column
column = alignment[:, 5]  # Column 5 as string

Working with Alignment Objects

Get Alignment Properties

python
alignment = AlignIO.read('alignment.aln', 'clustal')

length = alignment.get_alignment_length()
num_seqs = len(alignment)
seq_ids = [record.id for record in alignment]

Slice Alignments

python
# Get subset of sequences
subset = alignment[0:5]  # First 5 sequences

# Get subset of columns
trimmed = alignment[:, 50:150]  # Columns 50-149

# Combine slicing
region = alignment[0:5, 50:150]  # 5 sequences, columns 50-149

Creating Alignments Programmatically

Goal: Build an alignment object from sequences defined in code rather than read from a file.

Approach: Construct SeqRecord objects with gap characters and wrap them in a MultipleSeqAlignment.

python
from Bio.Align import MultipleSeqAlignment
from Bio.SeqRecord import SeqRecord
from Bio.Seq import Seq

records = [
    SeqRecord(Seq('ACTGACTGACTG'), id='seq1'),
    SeqRecord(Seq('ACTGACT-ACTG'), id='seq2'),
    SeqRecord(Seq('ACTG-CTGACTG'), id='seq3'),
]
alignment = MultipleSeqAlignment(records)
AlignIO.write(alignment, 'new_alignment.fasta', 'fasta')

Format-Specific Notes

PHYLIP Format

python
# Standard PHYLIP (10 char names, interleaved)
alignment = AlignIO.read('file.phy', 'phylip')

# Sequential PHYLIP
alignment = AlignIO.read('file.phy', 'phylip-sequential')

# Relaxed PHYLIP (allows longer names)
alignment = AlignIO.read('file.phy', 'phylip-relaxed')

Stockholm Format (with Annotations)

python
alignment = AlignIO.read('pfam.sto', 'stockholm')

# Access annotations
for record in alignment:
    print(record.id, record.annotations)

Clustal Format

python
# Clustal preserves conservation symbols in file but not when parsed
alignment = AlignIO.read('clustal.aln', 'clustal')

Batch Processing Multiple Files

Goal: Convert a directory of alignment files from one format to another in bulk.

Approach: Glob for input files and iterate, reading each alignment and writing to the target format.

python
from pathlib import Path

input_dir = Path('alignments/')
output_dir = Path('converted/')

for input_file in input_dir.glob('*.aln'):
    alignment = AlignIO.read(input_file, 'clustal')
    output_file = output_dir / f'{input_file.stem}.fasta'
    AlignIO.write(alignment, output_file, 'fasta')

Alternative: Bio.Align Module I/O

Goal: Use the modern Bio.Align module for alignment I/O with access to newer features like counts and substitutions.

Approach: Use Align.read(), Align.parse(), and Align.write() which return Alignment objects instead of MultipleSeqAlignment.

The newer Bio.Align module provides its own I/O functions that return Alignment objects (instead of MultipleSeqAlignment). These support additional formats and provide access to modern alignment features.

python
from Bio import Align

# Read single alignment (returns Alignment object)
alignment = Align.read('alignment.aln', 'clustal')

# Parse multiple alignments
for alignment in Align.parse('multi.sto', 'stockholm'):
    print(f'Alignment with {len(alignment)} sequences')

# Write alignment
Align.write(alignment, 'output.fasta', 'fasta')

When to Use Which

| Use Case | Module | |----------|--------| | Legacy code, MultipleSeqAlignment needed | Bio.AlignIO | | Modern features (counts, substitutions) | Bio.Align | | Format conversion | Either works | | Working with pairwise alignments | Bio.Align |

Quick Reference: Common Operations

| Task | Code | |------|------| | Read single alignment | AlignIO.read(file, format) | | Read multiple alignments | AlignIO.parse(file, format) | | Write alignment(s) | AlignIO.write(align, file, format) | | Convert format | AlignIO.convert(in_file, in_fmt, out_file, out_fmt) | | Get length | alignment.get_alignment_length() | | Get sequence count | len(alignment) | | Slice columns | alignment[:, start:end] |

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | ValueError: No records | Empty file | Check file path and format | | ValueError: More than one record | Multiple alignments with read() | Use parse() instead | | ValueError: Sequences different lengths | Invalid alignment | Ensure all sequences same length | | ValueError: unknown format | Unsupported format string | Check supported formats list |

Related Skills

• pairwise-alignment - Create pairwise alignments with PairwiseAligner
• msa-parsing - Analyze alignment content and annotations
• msa-statistics - Calculate conservation and identity
• sequence-io/format-conversion - Convert sequence (non-alignment) formats