biopython-alignment

name	biopython-alignment
description	Sequence alignment and alignment file processing with Biopython (Bio.Align/Bio.AlignIO), triggered when you need global/local pairwise alignment, MSA read/write/format conversion, or alignment statistics/filtering.
license	MIT
author	AIPOCH

Source: https://github.com/aipoch/medical-research-skills

biopython-alignment

When to Use

• You need global alignment between two protein (or nucleotide) sequences and want a reproducible score and aligned strings.
• You need local alignment to find the best matching fragment/subsequence between two DNA/RNA/protein sequences.
• You need to read, write, or convert multiple sequence alignment (MSA) files (e.g., FASTA/Clustal/Stockholm) using Biopython I/O.
• You want to compute alignment statistics (e.g., identity, coverage, conservation per column) and filter alignments by thresholds.
• You need to apply substitution matrices (e.g., BLOSUM62) and tune gap penalties for biologically meaningful scoring.

Key Features

• Pairwise alignment via Bio.Align.PairwiseAligner (global and local modes).
• Alignment scoring with configurable match/mismatch and gap penalties.
• Protein substitution matrices via Bio.Align.substitution_matrices (e.g., BLOSUM/PAM).
• MSA parsing and serialization via Bio.AlignIO (read/write/format conversion).
• Basic alignment statistics: identity, aligned length, coverage, and MSA column conservation.

Dependencies

• biopython>=1.81
• numpy>=1.21

Example Usage

# -*- coding: utf-8 -*-
"""
Runnable examples for:
1) Global protein alignment
2) Local DNA alignment (best fragment)
3) MSA parsing + column conservation

Requires: biopython, numpy
"""

from __future__ import annotations

from io import StringIO
import numpy as np

from Bio.Align import PairwiseAligner
from Bio.Align import substitution_matrices
from Bio import AlignIO


def global_protein_alignment(seq_a: str, seq_b: str) -> None:
    matrix = substitution_matrices.load("BLOSUM62")

    aligner = PairwiseAligner()
    aligner.mode = "global"
    aligner.substitution_matrix = matrix
    aligner.open_gap_score = -10.0
    aligner.extend_gap_score = -0.5

    alignments = aligner.align(seq_a, seq_b)
    best = alignments[0]

    print("=== Global protein alignment (best) ===")
    print("Score:", best.score)
    print(best)


def local_dna_alignment_best_fragment(seq_a: str, seq_b: str) -> None:
    aligner = PairwiseAligner()
    aligner.mode = "local"
    aligner.match_score = 2.0
    aligner.mismatch_score = -1.0
    aligner.open_gap_score = -2.0
    aligner.extend_gap_score = -0.5

    best = aligner.align(seq_a, seq_b)[0]

    
    
    a_blocks, b_blocks = best.aligned
    a_start, a_end = a_blocks[]
    b_start, b_end = b_blocks[]

    ()
    (, best.score)
    (best)
    (, seq_a[a_start:a_end], )
    (, seq_b[b_start:b_end], )


 () -> :
    handle = StringIO(fasta_text)
    msa = AlignIO.read(handle, )  

    
    arr = np.array([((rec.seq))  rec  msa], dtype=)
    n_seqs, aln_len = arr.shape

    
    
    conservation = []
     j  (aln_len):
        col = arr[:, j]
        col = col[col != ]
         col.size == :
            conservation.append()
            
        values, counts = np.unique(col, return_counts=)
        conservation.append((counts.() / counts.()))

    ()
    (, n_seqs, , aln_len)
    (, [(x, )  x  conservation])


 () -> :
    
    seq_a = 
    seq_b = 
    global_protein_alignment(seq_a, seq_b)

    
    seq_a = 
    seq_b = 
    local_dna_alignment_best_fragment(seq_a, seq_b)

    
    fasta_text = 
    msa_column_conservation(fasta_text)


 __name__ == :
    main()

Implementation Details

• Pairwise alignment engine: uses Bio.Align.PairwiseAligner, which performs dynamic programming alignment under the selected mode:
  • mode="global": aligns full-length sequences end-to-end.
  • mode="local": finds the highest-scoring matching region (best subsequence pair).
• Scoring configuration:
  • For proteins, prefer substitution_matrix (e.g., BLOSUM62) plus gap penalties (open_gap_score, extend_gap_score).
  • For nucleotides, a simple scheme is common: match_score, mismatch_score, and gap penalties.
• Selecting the best alignment: aligner.align(a, b) returns an iterable of alignments sorted by score; use [0] for the top-scoring result.
• Local “best fragment” extraction:
  • alignment.aligned returns aligned coordinate blocks for each sequence.
  • The first block (start, end) typically corresponds to the highest-scoring contiguous aligned region; slice the original sequences with these coordinates to obtain the fragment.
• MSA I/O and statistics:
  • Bio.AlignIO.read(handle, fmt) parses an alignment into a MultipleSeqAlignment.
  • Column conservation can be computed as:
    max_count(non-gap residues in column) / total_non_gap_count(column).
• Operational conventions (recommended):
  • Store runtime configuration in config/task_config.json and invoke scripts as python scripts/<task_name>.py.
  • Avoid stacking many CLI -- parameters; keep parameters in the config file.
  • Always specify encoding="utf-8" for file I/O; for JSON output use ensure_ascii=False.