Pfam domain hit extraction

PFAM Domain Hit Extraction from BGC Sequences

Summary

Extract biosynthetic protein domains and their annotations from BGC sequences by scanning against PFAM 35.0 HMM models using pyHMMER, producing a normalized feature table for downstream clustering. This skill replaces the slower external HMMER binary with an in-process Cython-bound implementation, enabling reproducible domain detection without intermediate files.

When to use

You have BGC sequences (in FASTA or GenBank format) and need to identify conserved biosynthetic domains to build a feature vector for BGC similarity clustering or to annotate gene functions. This is the entry point when you want to detect Pfam hits that will later be l2-normalized for cosine-like distance clustering in BiG-SLiCE v2.

When NOT to use

• Input is already a pre-computed normalized feature table — skip to clustering.
• You require HMMER binary outputs (multiple fixed-width tabular files) — use external HMMER instead of pyHMMER.
• Your workflow must run on Windows or non-UNIX systems — HMMER and pyHMMER do not support these platforms.

Inputs

• BGC sequences in FASTA format
• BGC sequences in GenBank format
• PFAM 35.0 HMM database (bigslice-models-2022-11-30)

Outputs

• Domain hit table (gene ID, Pfam accession, coordinates, e-value, bit-score)
• L2-normalized domain-feature matrix (TSV)
• Hit details export (TSV)

How to apply

Load BGC sequences and initialize the pyHMMER interface with the bigslice-models-2022-11-30 PFAM 35.0 HMM database. Scan each BGC sequence against Pfam HMM models using pyHMMER's hmmscan with default e-value and bit-score cutoffs to identify domain hits. For each domain match, extract the gene identifier, Pfam accession, domain coordinate boundaries, e-value, and bit-score. Aggregate hits into a feature table where rows are genes/domains and columns track presence/absence or bit-score magnitudes. Apply l2-normalization to each feature vector to prepare for downstream cosine-like distance-based clustering. Export the normalized domain-feature matrix and raw hit details to TSV format for external analysis or input to BiG-SLiCE clustering.

Related tools

• pyHMMER (In-process Cython-bound HMMER3 interface; performs domain scanning against HMM profiles without external binaries or intermediate files.) — https://github.com/althonos/pyhmmer
• BiG-SLiCE (Orchestrates the full BGC clustering pipeline; wraps pyHMMER-based domain extraction and applies l2-normalization for cosine-like distance clustering.) — https://github.com/medema-group/bigslice
• PFAM 35.0 (Reference HMM profile database containing biosynthetic and sub-Pfam models; fetched via bigslice-models-2022-11-30.)

Examples

from pyhmmer.plan7 import HMMFile; from pyhmmer.easel import SequenceFile; hmmdb = HMMFile('bigslice-models-2022-11-30/biosynthetic.hmm'); seqs = SequenceFile('input_bgc.fasta'); hits = [h for query in seqs for h in hmmsearch(hmmdb, [query])]

Evaluation signals

• Each domain hit has a valid Pfam accession matching the PFAM 35.0 database.
• E-values and bit-scores fall within expected ranges (e.g., e-value ≤ threshold, bit-score ≥ 0).
• L2-normalized feature vectors have unit norm (L2 norm ≈ 1.0 ± small floating-point error).
• Feature matrix row count equals the total number of unique domain hits; column count equals number of unique genes/sequences.
• TSV export files parse without formatting errors and contain no null or missing critical fields (accession, coordinates, scores).

Limitations

• Domain detection sensitivity and specificity depend on PFAM 35.0 model quality and the chosen e-value/bit-score thresholds; these are not tuned for every BGC type.
• L2-normalization compresses absolute bit-score magnitude into the unit sphere, which may reduce discriminative power for very weak domain hits.
• pyHMMER is restricted to UNIX-like systems (Linux, macOS); Windows users must use external HMMER binaries or alternative platforms.
• No changelog is available in the provided sources, so parameter or output format changes between versions may not be explicitly documented.

Evidence

• [other] Scan each BGC sequence against the Pfam HMM models using pyHMMER with default e-value threshold and bit-score cutoffs to identify biosynthetic domains.: "Scan each BGC sequence against the Pfam HMM models using pyHMMER with default e-value threshold and bit-score cutoffs to identify biosynthetic domains."
• [other] Extract domain hits (gene identifiers, Pfam accessions, domain coordinates, e-values, bit-scores) and aggregate into a feature table.: "Extract domain hits (gene identifiers, Pfam accessions, domain coordinates, e-values, bit-scores) and aggregate into a feature table."
• [other] Normalize domain presence/absence or bit-score vectors using l2-normalization to prepare for downstream cosine-like distance clustering.: "Normalize domain presence/absence or bit-score vectors using l2-normalization to prepare for downstream cosine-like distance clustering."
• [readme] Switching from HMMER to pyHMMER (speed-ups, can now be fully installed via pip): "Switching from HMMER to pyHMMER (speed-ups, can now be fully installed via pip)"
• [readme] no intermediate files: Everything happens in memory, in Python objects you have control on, making it easier to pass your inputs to HMMER without needing to write them to a temporary file.: "no intermediate files: Everything happens in memory, in Python objects you have control on, making it easier to pass your inputs to HMMER without needing to write them to a temporary file."
• [readme] Clustering now uses cosine-like (via l2-normalization) distances: "Clustering now uses cosine-like (via l2-normalization) distances"