pyhmmer: Python Interface to HMMER3

0.12.0 · active · verified Fri Apr 10

pyhmmer provides high-performance Cython bindings and a Pythonic interface to the HMMER3 C library, enabling powerful sequence analysis using Hidden Markov Models. It is used for searching protein and nucleic acid sequence databases, identifying remote homologs, and building profile HMMs. The current stable version is 0.12.0, with a release cadence of several minor versions per year, indicating active development.

Warnings

gotcha pyhmmer is a wrapper around the HMMER3 C library. While `pip install pyhmmer` attempts to download and compile HMMER3 from source, this process can fail if necessary system build tools (like a C compiler, e.g., gcc/clang, and development libraries) are not installed or correctly configured on your system.
Fix: Ensure you have a C compiler and build essentials installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS). For more robust HMMER3 dependency management, especially on Windows or complex environments, consider installing `pyhmmer` via Bioconda (`conda install -c bioconda pyhmmer`). If HMMER3 is installed manually, set the `HMMER_DIR` environment variable to its installation prefix before building pyhmmer.
breaking As a 0.x series library, `pyhmmer`'s API is still evolving and is subject to changes between minor versions (e.g., 0.10.x to 0.11.x, or 0.11.x to 0.12.x). This can include renaming of classes, methods, changes in function signatures, or modifications to the structure of result objects, potentially breaking existing code without a deprecation warning.
Fix: Always review the changelog and migration guides (if available) when upgrading `pyhmmer` across minor versions. Test your code thoroughly after any upgrade. Pin your `pyhmmer` version in `requirements.txt` to avoid unexpected breakage in production environments.
gotcha HMMER operations, especially with large HMM databases or extensive sequence queries, can be highly memory-intensive due to the underlying C library. Insufficient RAM can lead to crashes or degraded performance. While `pyhmmer` manages C memory, improper handling of objects or large batch sizes can exacerbate memory pressure.
Fix: Monitor memory usage for your specific workloads. For very large datasets, consider processing sequences in batches rather than loading everything into memory at once. Ensure `pyhmmer.pipeliner.Pipeline` and other resource-heavy objects are properly scoped (e.g., within functions or with explicit `del` if not garbage collected quickly enough) to allow for memory cleanup.
gotcha The `pyhmmer` library operates with specific `Alphabet` types (amino, DNA, RNA). Mismatching the alphabet between an HMM and the sequences being searched will lead to incorrect results or runtime errors. Additionally, sequence data (`Sequence.sequence` and `Sequence.name`) must be provided as `bytes`, not strings.
Fix: Explicitly define and pass the correct `Alphabet` (e.g., `Alphabet.amino()`, `Alphabet.dna()`) to all relevant `pyhmmer` objects, ensuring consistency. Always encode sequence data and names to `bytes` before passing them to `pyhmmer.easel.Sequence` or similar constructors.

Install

pip install pyhmmer Standard installation
conda install -c bioconda pyhmmer Conda installation (recommended for managing HMMER3 dependency)

Imports

Alphabet
```
from pyhmmer.easel import Alphabet
```
Sequence
```
from pyhmmer.easel import Sequence
```
HMM
```
from pyhmmer.hmm import HMM
```
Pipeline
```
from pyhmmer.pipeliner import Pipeline
```
HMMFile
```
from pyhmmer.plan7 import HMMFile
```

Quickstart

This quickstart demonstrates how to create a simple HMM from a sequence, define target sequences, and perform a basic HMMER search using `pyhmmer.pipeliner.Pipeline`. It then iterates through the search results to display hits and their associated domains. Note that sequence names and data must be bytes.

import pyhmmer
from pyhmmer.easel import Alphabet, Sequence
from pyhmmer.hmm import HMM
from pyhmmer.pipeliner import Pipeline

# 1. Define the alphabet for sequences and HMMs
alphabet = Alphabet.amino()

# 2. Create a simple HMM from a seed sequence (or load from .hmm file)
# For a real application, you would typically load an HMM from a file
# using `pyhmmer.plan7.HMMFile('your_file.hmm').read_one()`
seed_sequence = Sequence(name=b"seed_seq", sequence=b"AGILRVAG")
hmm = HMM.from_sequence(seed_sequence, alphabet)
hmm.name = b"my_simple_hmm"

# 3. Create target sequences to search against
target_sequences = [
    Sequence(name=b"target1", sequence=b"AGILRVAGGPPPL"),
    Sequence(name=b"target2", sequence=b"GPPPLGGAGILRV"),
    Sequence(name=b"target3", sequence=b"XXXXXAGILRVXXXX") # Contains mismatching chars
]

# 4. Initialize the HMMER pipeline
# The pipeline manages memory and resources for the search process
pipeline = Pipeline(alphabet)

# 5. Run the search: search the HMM against the target sequences
# This method returns a pyhmmer.search.SearchResult object
results = pipeline.search_hmm(hmm, target_sequences)

# 6. Process and print the results
found_hits = False
for hit in results.hits:
    found_hits = True
    print(f"\n--- Hit Found ---")
    print(f"Query HMM: {hit.query_name.decode()}")
    print(f"Target Sequence: {hit.target_name.decode()}")
    print(f"  E-value: {hit.evalue:.2e}, Bit Score: {hit.score:.2f}")
    for dom in hit.domains:
        print(f"    Domain: Query {dom.query_start}-{dom.query_end} (HMM positions)")
        print(f"            Target {dom.target_start}-{dom.target_end} (Sequence positions)")

if not found_hits:
    print("No significant hits found for the HMM against target sequences.")

view raw JSON →