> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PyHMMER
> [PyHMMER](https://github.com/althonos/pyhmmer) is a Python library that binds [HMMER3](http://hmmer.org/) for [profile hidden Markov model](https://en.wikipedia.org/wiki/Hidden_Markov_model) sequence search and domain annotation. It exposes the five canonical HMMER programs (`hmmsearch`, `hmmscan`, `phmmer`, `nhmmer`, `jackhmmer`) as Python functions, returns structured per-hit and per-domain results, and reaches the sensitivity of HMMER while staying entirely in-process.
**License:** PyHMMER is open source and free for academic and commercial use under an MIT license. Please refer to [the license](https://github.com/althonos/pyhmmer/blob/master/COPYING) for full terms.
This toolkit is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.
```bibtex theme={null}
@article{larralde2023pyhmmer,
title={pyHMMER: a Python library binding to HMMER for efficient sequence analysis},
author={Larralde, Martin and Zeller, Georg},
journal={Bioinformatics},
volume={39},
number={5},
pages={btad214},
year={2023},
publisher={Oxford University Press},
doi={10.1093/bioinformatics/btad214}
}
```
| Function | Description | |
| ------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_pyhmmer_hmmscan()` | Search sequences against HMM database using PyHMMER | Docs Source |
| `run_pyhmmer_hmmsearch()` | Search HMM profile(s) against sequences using PyHMMER | Docs Source |
| `run_pyhmmer_jackhmmer()` | Iteratively search protein sequences against protein database using PyHMMER | Docs Source |
| `run_pyhmmer_nhmmer()` | Search nucleotide sequences against nucleotide database using PyHMMER | Docs Source |
| `run_pyhmmer_phmmer()` | Search protein sequences against protein database using PyHMMER | Docs Source |
## Background
[PyHMMER](https://github.com/althonos/pyhmmer) ([Larralde & Zeller, 2023](https://doi.org/10.1093/bioinformatics/btad214)) is a Cython binding to the HMMER C API that ships the HMMER source itself, so a single `pip install` provides both the Python interface and the compiled search engine. The underlying [HMMER3](http://hmmer.org/) algorithm ([Eddy, 2011](https://doi.org/10.1371/journal.pcbi.1002195)) builds a profile hidden Markov model from a [multiple sequence alignment](https://en.wikipedia.org/wiki/Multiple_sequence_alignment), where each match state stores position-specific emission probabilities and the transitions between states model insertions and deletions. Search proceeds through a cascade of accelerated filters: a [SIMD](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data)-vectorised multiple-segment Viterbi (MSV) filter, a vectorised Viterbi filter, and a Forward/Backward filter, each tightening the candidate set before the final scored alignment. Each hit carries a database-size-independent bit score together with an [E-value](https://en.wikipedia.org/wiki/E-value) derived from extreme-value-distribution theory. The E-value calibrates the expected number of false-positive hits at that bit score for the database being searched.
Profile HMMs detect homology that pairwise methods such as [BLAST](https://en.wikipedia.org/wiki/BLAST_\(biotechnology\)) miss because they encode an entire family's position-specific conservation pattern rather than the similarity of two sequences alone. HMMER3 brought profile-HMM search within roughly the runtime envelope of BLAST while keeping that sensitivity advantage. PyHMMER preserves the algorithm exactly and adds Python-native multithreading, in-memory HMM and sequence handles, and structured result objects. Coordinates returned for HMM matches, target alignments, and envelopes are reported as 1-indexed, inclusive intervals to match biological residue selection conventions.
### Learning Resources
* [pyhmmer documentation](https://pyhmmer.readthedocs.io/) (Martin Larralde) - the canonical API reference, with worked examples for every binding and a guide to feeding HMM and sequence files in and out of memory.
* [HMMER User's Guide](http://hmmer.org/) (The Eddy/Rivas Laboratory, Harvard) - reference for the HMMER 3 command-line surface, the MSV/Viterbi/Forward filter cascade, E-value statistics, and the gathering/noise/trusted cutoff system used by Pfam HMMs.
* [Pfam (via InterPro)](https://www.ebi.ac.uk/interpro/) (EMBL-EBI) - the standard curated HMM library that ships gathering, noise, and trusted cutoffs, and the typical target database for `hmmscan` domain annotation.
## Tools
### PyHMMER Profile Search (`pyhmmer-hmmsearch`)
Searches one or more HMM profiles against a set of protein sequences and returns the sequences (and the per-domain alignments within them) that match each profile.
#### API Reference
Source
Path to an HMM file containing one or more profile HMMs. The file should be in HMMER3 format (typically `.hmm` extension). Can contain multiple HMM profiles; all will be searched against the target sequences.
Target protein sequences to search. Inherited from `PyHmmerInput`. Can be a single sequence string or a list of sequence strings.
Source
Use the HMM's stored bit-score cutoff in place of E-value reporting. `gathering` is the Pfam-curated default for inclusion; `noise` is the most permissive; `trusted` is the strictest. None = use E-value/score thresholds. Default: None. Pyhmmer raises `MissingCutoffs` if the HMM file lacks the requested cutoff line — set None for HMMs without curated thresholds.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
CPU threads (0 = auto). Inherited from `PyHmmerConfig`.
Sequence-level E-value cap to report. Inherited from `PyHmmerConfig`.
Sequence-level bit-score floor. Inherited from `PyHmmerConfig`.
Per-domain E-value cap to report. Inherited from `PyHmmerConfig`.
Per-domain bit-score floor. Inherited from `PyHmmerConfig`.
Sequence-level E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Per-domain E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Effective database size. Inherited from `PyHmmerConfig`.
Significant hit count. Inherited from `PyHmmerConfig`.
Disable MSV/Vit/Fwd filters. Inherited from `PyHmmerConfig`.
Source
List of sequence-level hits from the search. Each SequenceHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
E-value of the hit.
Bit score of the full sequence.
Bias correction for the sequence score.
Sum of domain scores.
Whether the hit passes reporting thresholds.
Whether the hit passes inclusion thresholds.
P-value of the hit.
Number of domains found in the hit.
List of domain-level hits from the search. Each DomainHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
Length of the HMM profile.
Start position of the domain match in the HMM (1-indexed).
End position of the domain match in the HMM (1-indexed).
Start position of the domain match in the target (1-indexed).
End position of the domain match in the target (1-indexed).
Length of the target sequence.
Conditional E-value of the domain.
Independent E-value of the domain.
Bit score of the domain.
Bias correction of the domain score.
Index of the domain within the hit (0-indexed).
Envelope start position in the target (1-indexed).
Envelope end position in the target (1-indexed).
Bit score of the domain envelope.
Whether the domain passes inclusion thresholds.
Whether the domain passes reporting thresholds.
P-value of the domain.
#### Applications
Use this when the question is "which proteins belong to family X." Build or download an HMM for a family of interest, then sweep a proteome, a [metagenome](https://en.wikipedia.org/wiki/Metagenomics), or a designed library to enumerate members and pull out their domain coordinates for downstream filtering or alignment.
#### Usage Tips
* **`bit_cutoffs="gathering"` activates the Pfam-curated thresholds and replaces the E-value filter.** Each Pfam HMM ships a hand-curated gathering (`--cut_ga`) cutoff that defines family membership, together with the auto-derived noise (`--cut_nc`) and trusted (`--cut_tc`) cutoffs that bracket the curated set. Use `"gathering"` for routine Pfam annotation; ad-hoc HMMs without stored cutoffs raise `MissingCutoffs`.
* **The default `evalue_threshold=10.0` is intentionally permissive.** Tighten to `0.001` for confident annotation or `1e-10` for stringent homology detection; loose thresholds are useful only when you plan to post-filter on `included` or `domain_included`.
### PyHMMER HMM Scan (`pyhmmer-hmmscan`)
Searches one or more query protein sequences against an HMM database and returns the profiles that match each query.
#### API Reference
Source
Path to an HMM database file containing multiple profile HMMs. The file should be in HMMER3 format and typically represents a comprehensive database like Pfam. All HMMs in the database will be searched against the query sequences.
Query protein sequences to search. Inherited from `PyHmmerInput`. Can be a single sequence string or a list of sequence strings.
Source
Use the HMM's stored bit-score cutoff in place of E-value reporting. `gathering` is the Pfam-curated default for inclusion; `noise` is the most permissive; `trusted` is the strictest. None = use E-value/score thresholds. Default: None. Pyhmmer raises `MissingCutoffs` if the HMM file lacks the requested cutoff line — set None for HMMs without curated thresholds.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
CPU threads (0 = auto). Inherited from `PyHmmerConfig`.
Sequence-level E-value cap to report. Inherited from `PyHmmerConfig`.
Sequence-level bit-score floor. Inherited from `PyHmmerConfig`.
Per-domain E-value cap to report. Inherited from `PyHmmerConfig`.
Per-domain bit-score floor. Inherited from `PyHmmerConfig`.
Sequence-level E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Per-domain E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Effective database size. Inherited from `PyHmmerConfig`.
Significant hit count. Inherited from `PyHmmerConfig`.
Disable MSV/Vit/Fwd filters. Inherited from `PyHmmerConfig`.
Source
List of sequence-level hits from the search. Each SequenceHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
E-value of the hit.
Bit score of the full sequence.
Bias correction for the sequence score.
Sum of domain scores.
Whether the hit passes reporting thresholds.
Whether the hit passes inclusion thresholds.
P-value of the hit.
Number of domains found in the hit.
List of domain-level hits from the search. Each DomainHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
Length of the HMM profile.
Start position of the domain match in the HMM (1-indexed).
End position of the domain match in the HMM (1-indexed).
Start position of the domain match in the target (1-indexed).
End position of the domain match in the target (1-indexed).
Length of the target sequence.
Conditional E-value of the domain.
Independent E-value of the domain.
Bit score of the domain.
Bias correction of the domain score.
Index of the domain within the hit (0-indexed).
Envelope start position in the target (1-indexed).
Envelope end position in the target (1-indexed).
Bit score of the domain envelope.
Whether the domain passes inclusion thresholds.
Whether the domain passes reporting thresholds.
P-value of the domain.
#### Applications
Use this when the question is "what does this protein contain." Run a query proteome against [Pfam](https://www.ebi.ac.uk/interpro/) to annotate each protein with its domain architecture, then filter on `domain_included` to keep curated hits.
#### Usage Tips
* **Pick `hmmscan` versus `hmmsearch` by what you are querying with.** `hmmscan` takes sequences as queries and a database of HMMs as the target; `hmmsearch` is the reverse. For one or a few queries against Pfam, `hmmscan` is the natural choice; for one HMM against a large sequence database, `hmmsearch` is much faster.
* **`bit_cutoffs="gathering"` applies here too and is the recommended Pfam annotation default.** As with `hmmsearch`, the cutoff is read from the HMM file and ad-hoc HMMs without stored cutoffs will fail with `MissingCutoffs`.
### PyHMMER Single-Sequence Protein Search (`pyhmmer-phmmer`)
Searches one or more protein query sequences against a target protein database by building a temporary HMM around each query.
#### API Reference
Source
Target protein sequences to search against. Can be a single sequence string or a list of sequence strings. The query sequences will be compared against these targets.
Query protein sequences. Inherited from `PyHmmerInput`. Can be a single sequence string or a list of sequence strings. These sequences will be used to build temporary HMM profiles on-the-fly.
Source
CPU threads; 0 = auto-detect. Default 0.
Sequence-level E-value cap to report. Default 10.0.
Sequence-level bit-score floor. Overrides E-value when set. Default None.
Per-domain E-value cap to report. Default 10.0.
Per-domain bit-score floor. Overrides domain E-value when set. Default None.
Sequence-level inclusion E-value. Default 0.01.
Per-domain inclusion E-value. Default 0.01.
Effective database size for E-value calc. None = use the actual target count.
Significant hit count for domain E-value calc. None = use actual.
Disable MSV/Vit/Fwd heuristic filters. Slower but maximally sensitive. Default False.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Source
List of sequence-level hits from the search. Each SequenceHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
E-value of the hit.
Bit score of the full sequence.
Bias correction for the sequence score.
Sum of domain scores.
Whether the hit passes reporting thresholds.
Whether the hit passes inclusion thresholds.
P-value of the hit.
Number of domains found in the hit.
List of domain-level hits from the search. Each DomainHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
Length of the HMM profile.
Start position of the domain match in the HMM (1-indexed).
End position of the domain match in the HMM (1-indexed).
Start position of the domain match in the target (1-indexed).
End position of the domain match in the target (1-indexed).
Length of the target sequence.
Conditional E-value of the domain.
Independent E-value of the domain.
Bit score of the domain.
Bias correction of the domain score.
Index of the domain within the hit (0-indexed).
Envelope start position in the target (1-indexed).
Envelope end position in the target (1-indexed).
Bit score of the domain envelope.
Whether the domain passes inclusion thresholds.
Whether the domain passes reporting thresholds.
P-value of the domain.
#### Applications
Use this for HMM-grade sensitivity when no pre-built profile is available. Typical workflows include finding remote homologs of a newly characterised protein in a reference proteome and running a sequence-based homology pass when the family of interest is too narrow or too new to have a curated HMM.
#### Usage Tips
* **A single-query, single-target search will not converge.** `phmmer` builds the HMM from the query against the target database's residue statistics; a database of one sequence has no background to estimate against. Use `phmmer` with a real target proteome, not a synthetic pair.
### PyHMMER Nucleotide Search (`pyhmmer-nhmmer`)
Searches nucleotide query sequences against a nucleotide target database with the same profile-HMM machinery used for proteins.
#### API Reference
Source
Target nucleotide sequences to search against. Can be a single sequence string or a list of sequence strings.
Query nucleotide sequences. Inherited from `PyHmmerInput`. Can be a single sequence string or a list of sequence strings.
Source
Strand to search. `both` (default) runs the forward strand and its reverse complement; `watson` runs only the forward strand; `crick` runs only the reverse complement.
Available options: `both`, `watson`, `crick`
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
CPU threads (0 = auto). Inherited from `PyHmmerConfig`.
Sequence-level E-value cap to report. Inherited from `PyHmmerConfig`.
Sequence-level bit-score floor. Inherited from `PyHmmerConfig`.
Per-domain E-value cap to report. Inherited from `PyHmmerConfig`.
Per-domain bit-score floor. Inherited from `PyHmmerConfig`.
Sequence-level E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Per-domain E-value cap for inclusion. Inherited from `PyHmmerConfig`.
Effective database size. Inherited from `PyHmmerConfig`.
Significant hit count. Inherited from `PyHmmerConfig`.
Disable MSV/Vit/Fwd filters. Inherited from `PyHmmerConfig`.
Source
List of sequence-level hits from the search. Each SequenceHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
E-value of the hit.
Bit score of the full sequence.
Bias correction for the sequence score.
Sum of domain scores.
Whether the hit passes reporting thresholds.
Whether the hit passes inclusion thresholds.
P-value of the hit.
Number of domains found in the hit.
List of domain-level hits from the search. Each DomainHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
Length of the HMM profile.
Start position of the domain match in the HMM (1-indexed).
End position of the domain match in the HMM (1-indexed).
Start position of the domain match in the target (1-indexed).
End position of the domain match in the target (1-indexed).
Length of the target sequence.
Conditional E-value of the domain.
Independent E-value of the domain.
Bit score of the domain.
Bias correction of the domain score.
Index of the domain within the hit (0-indexed).
Envelope start position in the target (1-indexed).
Envelope end position in the target (1-indexed).
Bit score of the domain envelope.
Whether the domain passes inclusion thresholds.
Whether the domain passes reporting thresholds.
P-value of the domain.
#### Applications
Use this to find homologs of transposable elements, non-coding RNAs, regulatory elements, and other nucleotide features that diverge fast enough to slip past direct sequence alignment. Pair it with [Dfam](https://www.dfam.org/) - the curated profile-HMM library of transposable-element families that was co-designed with nhmmer - or with custom-built nucleotide HMMs when annotating genomes and metagenomic contigs.
#### Usage Tips
* **`strand` defaults to `"both"` and searches the forward and reverse-complement strands.** Set `"watson"` to restrict to forward or `"crick"` to restrict to reverse-complement when the orientation of a hit is meaningful (e.g., on annotated coding strands).
### PyHMMER Iterative Protein Search (`pyhmmer-jackhmmer`)
Performs iterative protein-sequence search against a target protein database, rebuilding the HMM from each round's included hits to extend the search outward across remote homologs.
#### API Reference
Source
Target protein sequences to search against. Can be a single sequence string or a list of sequence strings.
Query protein sequences. Inherited from `PyHmmerInput`. Can be a single sequence string or a list of sequence strings.
Source
Maximum jackhmmer iterations; stops early on convergence. Default 5.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
CPU threads (0 = auto). Inherited from `PyHmmerConfig`.
Sequence-level E-value cap to report. Inherited from `PyHmmerConfig`.
Sequence-level bit-score floor. Inherited from `PyHmmerConfig`.
Per-domain E-value cap to report. Inherited from `PyHmmerConfig`.
Per-domain bit-score floor. Inherited from `PyHmmerConfig`.
Sequence-level inclusion E-value. Inherited from `PyHmmerConfig`. Critical for jackhmmer — the included set seeds the next iteration's HMM.
Per-domain inclusion E-value. Inherited from `PyHmmerConfig`.
Effective database size for E-value calc. Inherited from `PyHmmerConfig`.
Significant hit count for domain E-value. Inherited from `PyHmmerConfig`.
Disable MSV/Vit/Fwd filters. Inherited from `PyHmmerConfig`.
Source
List of sequence-level hits from the search. Each SequenceHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
E-value of the hit.
Bit score of the full sequence.
Bias correction for the sequence score.
Sum of domain scores.
Whether the hit passes reporting thresholds.
Whether the hit passes inclusion thresholds.
P-value of the hit.
Number of domains found in the hit.
List of domain-level hits from the search. Each DomainHit contains:
Name of the query HMM.
Accession of the query HMM. `"-"` if unavailable.
Description of the query HMM. `"-"` if unavailable.
Index of the query (0-indexed).
Name of the target sequence.
Accession of the target sequence. `"-"` if unavailable.
Description of the target sequence. `"-"` if unavailable.
Length of the HMM profile.
Start position of the domain match in the HMM (1-indexed).
End position of the domain match in the HMM (1-indexed).
Start position of the domain match in the target (1-indexed).
End position of the domain match in the target (1-indexed).
Length of the target sequence.
Conditional E-value of the domain.
Independent E-value of the domain.
Bit score of the domain.
Bias correction of the domain score.
Index of the domain within the hit (0-indexed).
Envelope start position in the target (1-indexed).
Envelope end position in the target (1-indexed).
Bit score of the domain envelope.
Whether the domain passes inclusion thresholds.
Whether the domain passes reporting thresholds.
P-value of the domain.
#### Applications
Use this when you need to reach divergent family members that a single-pass `phmmer` would miss, for example when seeding a new family from one characterised representative or expanding a manually curated set to its full evolutionary breadth.
#### Usage Tips
* **`inclusion_evalue_threshold` is the lever that controls iterative drift.** Each iteration rebuilds the HMM from hits that pass the inclusion thresholds (`--incE` / `--incdomE`, defaults `0.01`). A looser inclusion threshold pulls in more sequences per round and increases the risk of pulling in unrelated families; tighten it when iterations start drifting.
* **`max_iterations` defaults to 5 and the search exits early on convergence.** Raising it rarely helps if the search has already converged on a stable set, and a higher cap multiplies runtime on long-running jobs.
## Toolkit Notes
These apply to every PyHMMER tool in this toolkit (`pyhmmer-hmmsearch`, `pyhmmer-hmmscan`, `pyhmmer-phmmer`, `pyhmmer-nhmmer`, `pyhmmer-jackhmmer`).
* **Runs on CPU with SIMD acceleration.** The HMMER3 filter cascade is SIMD-vectorised on x86 platforms. pyhmmer compiles HMMER from source at install time and inherits whatever instruction sets the build host exposes, with no GPU acceleration to enable.
* **Self-contained after install.** The HMMER C library is compiled into the PyHMMER wheel, so no separate HMMER install or PATH lookup is needed; HMM databases such as Pfam-A still have to be downloaded separately.
* **`num_threads` parallelises within a single search.** Default `0` auto-detects the available cores. Memory scales with HMM database size; Pfam-A (around 20,000 HMMs) needs roughly 2 GB of RAM held resident.
* **Reporting versus inclusion thresholds are independent filters.** `evalue_threshold` / `score_threshold` (and their `domain_*` siblings) control what appears in the output, while `inclusion_evalue_threshold` marks the stricter "trusted" subset via the `included` and `domain_included` flags. `jackhmmer` seeds the next iteration's HMM from the included set, so the inclusion threshold drives iterative behaviour while reporting only affects what is returned.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/47e34afa5ea240a3b406e323dc38aa5dc85f223e/proto_tools/tools/gene_annotation/pyhmmer/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/gene\_annotation/pyhmmer
