Biosynthetic Gene Cluster Annotation

biosynthetic-gene-cluster-annotation

Summary

Annotate biosynthetic domains within BGC sequences by scanning against PFAM 35.0 HMM models using pyHMMER, producing normalized domain-feature vectors for downstream clustering and comparative analysis. This skill leverages the pyHMMER library to replace external HMMER binaries, enabling in-memory processing without intermediate files.

When to use

When you have BGC sequences in FASTA or GenBank format and need to identify and extract biosynthetic Pfam domains for feature-based clustering, similarity search, or functional characterization. Use this skill if you are building a domain-feature matrix for cosine-like distance-based BGC clustering or querying a BGC against a Gene Cluster Family database.

When NOT to use

• Input is already a pre-calculated domain-feature matrix or normalized vector table — skip directly to clustering.
• BGC sequences are not in FASTA or GenBank format and cannot be parsed by the pyHMMER interface.
• You require domain annotations from non-PFAM sources (e.g. custom HMM databases or protein family databases other than Pfam 35.0).

Inputs

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

Outputs

• Domain hit table (gene identifiers, Pfam accessions, coordinates, e-values, bit-scores)
• Normalized domain-feature matrix (l2-normalized vectors)
• TSV export of pre-calculated BGC domain annotations
• TSV export of GCF-level domain profiles

How to apply

Load BGC sequences (FASTA or GenBank format) and initialize the pyHMMER interface with PFAM 35.0 HMM models from the bigslice-models-2022-11-30 database. Scan each BGC sequence against the Pfam HMM profiles using pyHMMER with default e-value and bit-score cutoffs to identify biosynthetic domains. Extract domain hits (gene identifiers, Pfam accessions, domain coordinates, e-values, bit-scores) and aggregate into a domain-feature table. Normalize the resulting domain presence/absence or bit-score vectors using l2-normalization to prepare for cosine-like distance clustering. Export the normalized domain-feature matrix and detailed hit information to TSV output files for downstream analysis.

Related tools

• pyHMMER (Cython-based Python interface to HMMER3 that performs in-memory HMM-based domain scanning against PFAM profiles without external binary dependencies or intermediate files) — https://github.com/althonos/pyhmmer
• BiG-SLiCE (Orchestrates the biosynthetic domain detection workflow, manages PFAM 35.0 HMM databases, normalizes domain features via l2-normalization, and exports results to TSV) — https://github.com/medema-group/bigslice
• PFAM 35.0 (Provides the HMM profiles for biosynthetic and general protein domain detection; updated version used by BiG-SLiCE v2)

Examples

from pyhmmer.plan7 import HMMFile; from pyhmmer.easel import SequenceFile; hits = hmmsearch(HMMFile('PFAM_35.0.hmm'), SequenceFile('bgc.fasta')); normalized_scores = l2_normalize(extract_bitscore_vector(hits)); export_to_tsv(normalized_scores, 'bgc_domain_features.tsv')

Evaluation signals

• Domain hit table contains expected columns (gene ID, Pfam accession, e-value, bit-score, domain coordinates) with no missing or malformed entries.
• E-values and bit-scores fall within biologically plausible ranges (e-values ≤ default threshold, bit-scores > 0 for significant hits).
• Normalized domain-feature vectors have l2-norm equal to 1.0 (or near 1.0 accounting for floating-point precision).
• TSV exports are parseable and contain consistent row counts across related output files (e.g., BGC and GCF tables).
• Cosine-like distances computed between pairs of normalized domain vectors fall in the range [0, 1] and exhibit expected similarity patterns (e.g., identical BGCs have distance ≈ 0).

Limitations

• HMM-based annotation is limited to Pfam 35.0 profiles; novel or non-canonical biosynthetic domains not represented in PFAM may be missed.
• E-value and bit-score cutoffs are set to defaults; sequences near the detection boundary may be incorrectly included or excluded, requiring manual review for edge cases.
• L2-normalization assumes domain feature vectors are comparable; highly imbalanced domain compositions (e.g., very short vs. very long BGCs) may distort cosine-like distance metrics.
• The skill does not perform sequence alignment or phylogenetic placement; domain hits are purely presence/absence or quantitative (bit-score) without evolutionary context.

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] 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] Clustering now uses cosine-like (via l2-normalization) distances: "Clustering now uses cosine-like (via l2-normalization) distances"
• [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] pHMM databases have been updated to PFAM 35.0: "pHMM databases have been updated to PFAM 35.0"
• [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."