# Pfam Domain Hit Extraction

> Use when 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.

- Skill: `holobiomicslab/pfam-domain-hit-extraction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/pfam-domain-hit-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/pfam-domain-hit-extraction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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](https://github.com/althonos/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"