Plan7

High-level interface to the Plan7 data model.

Plan7 is the model architecture used by HMMER since HMMER2.

See also

Details about the Plan 7 architecture in the HMMER documentation.

Alignment

class pyhmmer.plan7.Alignment

A single alignment of a sequence to a profile.

hmm_accession

The accession of the query, or its name if it has none.

New in version 0.1.4.

Type

bytes

hmm_from

The start coordinate of the alignment in the query HMM.

Type

int

hmm_name

The name of the query HMM.

Type

bytes

hmm_sequence

The sequence of the query HMM in the alignment.

Type

str

hmm_to

The end coordinate of the alignment in the query HMM.

Type

int

identity_sequence

The identity sequence between the query and the target.

Type

str

target_from

The start coordinate of the alignment in the target sequence.

Type

int

target_name

The name of the target sequence.

Type

bytes

target_sequence

The sequence of the target sequence in the alignment.

Type

str

target_to

The end coordinate of the alignment in the target sequence.

Type

int

Background Model

class pyhmmer.plan7.Background

The null background model of HMMER.

__init__(alphabet, uniform=False)

Create a new background model for the given alphabet.

Parameters

  • alphabet (pyhmmer.easel.Alphabet) – The alphabet to create the background model with.

  • uniform (bool) – Whether or not to create the null model with uniform frequencies. Defaults to False.

copy()

Create a copy of the null model with the same parameters.

L

The mean of the null model length distribution, in residues.

Type

int

Builder

class pyhmmer.plan7.Builder

A factory for constructing new HMMs from raw sequences.

New in version 0.2.0.

__init__(alphabet, *, architecture='fast', weighting='pb', effective_number='entropy', prior_scheme='alpha', symfrac=0.5, fragthresh=0.5, wid=0.62, esigma=45.0, eid=0.62, EmL=200, EmN=200, EvL=200, EvN=200, EfL=100, EfN=200, Eft=0.04, seed=42, ere=None, popen=None, pextend=None)

Create a new sequence builder with the given configuration.

Parameters

alphabet (Alphabet) – The alphabet the builder expects the sequences to be in.

Keyword Arguments

  • popen (float) – The gap open probability to use with the score system. Default depends on the alphabet: 0.02 for proteins, 0.03125 for nucleotides.

  • pextend (float) – The gap extend probability to use with the score system. Default depends on the alphabet: 0.4 for proteins, 0.75 for nucleotides.

build(sequence, background)

Build a new HMM from sequence using the builder configuration.

Parameters

  • sequence (DigitalSequence) – A single biological sequence in digital mode to build a HMM with.

  • background (pyhmmer.plan7.background) – The background model to use to create the HMM.

Raises

ValueError – When either sequence or background have the wrong alphabet for this builder.

build_msa(msa, background)

Build a new HMM from msa using the builder configuration.

Parameters

  • msa (DigitalMSA) – A multiple sequence alignment in digital mode to build a HMM with.

  • background (pyhmmer.plan7.background) – The background model to use to create the HMM.

Raises

ValueError – When either msa or background have the wrong alphabet for this builder.

New in version 0.3.0.

copy()

Create a duplicate Builder instance with the same arguments.

seed

The seed used by the internal random number generator.

Setting the seed will effectively reinitialize the internal RNG. In the special case the seed is 0, a one-time arbitrary seed will be chosen and the RNG will no be reseeded for reproducibility.

Type

int

Domains

class pyhmmer.plan7.Domain

A single domain in a query Hit.

c_evalue

The conditional e-value for the domain.

Type

float

i_evalue

The independent e-value for the domain.

Type

float

score

The overall score in bits, null-corrected.

Type

float

class pyhmmer.plan7.Domains

A read-only view over the domains of a single Hit.

Hits

class pyhmmer.plan7.Hit

A high-scoring database hit found by the comparison pipeline.

accession

The accession of the database hit, if any.

Type

bytes or None

description

The description of the database hit, if any.

Type

bytes or None

domains

The list of domains aligned to this hit.

Type

Domains

evalue

The e-value of the hit.

Type

float

name

The name of the database hit.

Type

bytes

pre_score

Bit score of the sequence before null2 correction.

Type

float

score

Bit score of the sequence with all domains after correction.

Type

float

class pyhmmer.plan7.TopHits

A ranked list of top-scoring hits.

TopHits are thresholded using the parameters from the pipeline, and are sorted by key when you obtain them from a Pipeline instance:

>>> abc = thioesterase.alphabet
>>> hits = Pipeline(abc).search_hmm(thioesterase, proteins)
>>> hits.is_sorted()
True

Use len to query the number of top hits, and the usual indexing notation to extract a particular Hit:

>>> len(hits)
1
>>> hits[0].name
b'938293.PRJEB85.HG003687_113'
__init__()

Create an empty TopHits instance.

clear()

Free internals to allow reusing for a new pipeline run.

is_sorted(by='key')

Check whether or not the hits are sorted with the given method.

See sort for a list of allowed values for the by argument.

sort(by='key')

Sort hits in the current instance using the given method.

Parameters

by (str) – The comparison method to use to compare hits. Allowed values are: key (the default) to sort by key, or seqidx to sort by sequence index and alignment position.

to_msa(alphabet, trim=False, digitize=False, all_consensus_cols=False)

Create multiple alignment of all included domains.

Parameters

  • alphabet (Alphabet) – The alphabet of the HMM this TopHits was obtained from. It is required to convert back hits to single sequences.

  • trim (bool) – Trim off any residues that get assigned to flanking \(N\) and \(C\) states (in profile traces) or \(I_0\) and \(I_m\) (in core traces).

  • digitize (bool) – If set to True, returns a DigitalMSA instead of a TextMSA.

  • all_consensus_cols (bool) – Force a column to be created for every consensus column in the model, even if it means having all gap character in a column.

Returns

MSA – A multiple sequence alignment containing the reported hits, either a TextMSA or a DigitalMSA depending on the value of the digitize argument.

New in version 0.3.0.

included

The number of hits that are above the inclusion threshold.

Type

int

reported

The number of hits that are above the reporting threshold.

Type

int

HMM

class pyhmmer.plan7.HMM

A data structure storing the Plan7 Hidden Markov Model.

__init__(M, alphabet)

Create a new HMM from scratch.

Parameters

  • M (int) – The length of the model (i.e. the number of nodes).

  • alphabet (Alphabet) – The alphabet of the model.

copy()

Return a copy of the HMM with the exact same configuration.

New in version 0.3.0.

write(fh, binary=False)

Write the HMM to a file handle.

Parameters

  • fh (io.IOBase) – A Python file handle, opened in binary mode (this must be the case even with binary=False, since the C code will emit bytes in either case).

  • binary (bool) – Pass False to emit the file in ASCII mode using the latest supported HMMER format, or True to use the binary HMMER3 format.

zero()

Set all parameters to zero, including model composition.

M

The length of the model (i.e. the number of nodes).

Type

int

accession

The accession of the HMM, if any.

Type

bytes or None

checksum

The 32-bit checksum of the HMM, if any.

The checksum if calculated from the alignment the HMM was created from, and was introduced in more recent HMM formats. This means some HMM objects may have a non-None checksum.

New in version 0.2.1.

Changed in version 0.3.1: Returns None if the HMM flag for the checksum is not set.

Type

int or None

command_line

The command line that built the model.

For HMMs created with Builder, this defaults to sys.argv. It can however be set to any string, including multiline to show successive commands.

Example

>>> print(thioesterase.command_line)
hmmbuild Thioesterase.hmm Thioesterase.fa
hmmcalibrate Thioesterase.hmm

New in version 0.3.1.

Type

str or None

consensus

The consensus residue line of the HMM, if set.

New in version 0.3.0.

Type

str or None

consensus_accessibility

The consensus accessibility of the HMM, if any.

New in version 0.3.1.

Type

str or None

consensus_structure

The consensus structure of the HMM, if any.

New in version 0.3.1.

Type

str or None

description

The description of the HMM, if any.

Type

bytes or None

insert_emissions

The insert emissions of the model.

The returned memoryview exposes a matrix of dimensions \((M, K)\), with one row per node and one column per alphabet symbol.

Hint

Use numpy.asarray to convert the memoryview to a 2D aray:

>>> i = thioesterase.insert_emissions
>>> numpy.asarray(i).reshape((thioesterase.M, thioesterase.alphabet.K))
array([[...]], dtype=float32)

New in version 0.3.1.

Type

memoryview of float

match_emissions

The match emissions of the model.

The returned memory view exposes a matrix of dimensions \((M, K)\), with one row per node, and one column per alphabet symbol.

Hint

Use numpy.asarray to convert the memory view to a 2D array:

>>> m = thioesterase.match_emissions
>>> numpy.asarray(m).reshape((thioesterase.M, thioesterase.alphabet.K))
array([[...]], dtype=float32)

New in version 0.3.1.

Type

memoryview of float

model_mask

The model mask line from the alignment, if any.

New in version 0.3.1.

Type

str or None

name

The name of the HMM, if any.

Type

bytes or None

nseq

The number of training sequences used, if any.

If the HMM was created from a multiple sequence alignment, this corresponds to the number of sequences in the MSA.

Example

>>> thioesterase.nseq
278

New in version 0.3.1.

Type

int or None

nseq_effective

The number of effective sequences used, if any.

New in version 0.3.1.

Type

float or None

reference

The reference line from the alignment, if any.

This is relevant if the HMM was built from a multiple sequence alignment (e.g. by Builder.build_msa, or by an external hmmbuild pipeline run).

New in version 0.3.1.

Type

str or None

transition_probabilities

The transition probabilities of the model.

The returned memory view exposes a matrix of dimensions \((M+1, 7)\), with one row per node (plus one extra row for the entry probabilities), and one column per transition.

Hint

Use numpy.asarray to convert the memory view to a 2D array:

>>> t = thioesterase.transition_probabilities
>>> numpy.asarray(t).reshape((thioesterase.M+1, 7))
array([[...]], dtype=float32)

New in version 0.3.1.

Type

memoryview of float

HMM File

class pyhmmer.plan7.HMMFile

A wrapper around a file (or database), storing serialized HMMs.

__init__(file, db=True)

Create a new HMM reader from the given file.

Parameters

  • file (str or file-like object) – Either the path to a file containing the HMMs to read, or a file-like object opened in binary-mode.

  • db (bool) – Set to False to force the parser to ignore the pressed HMM database if it finds one. Defaults to False.

close()

Close the HMM file and free resources.

This method has no effect if the file is already closed. It is called automatically if the HMMFile was used in a context:

>>> with HMMFile("tests/data/hmms/bin/PKSI-AT.h3m") as hmm_file:
...     hmm = next(hmm_file)

Pipeline

class pyhmmer.plan7.Pipeline

An HMMER3 accelerated sequence/profile comparison pipeline.

__init__(alphabet, background=None, *, bias_filter=True, report_e=10.0, null2=True, seed=42, Z=None, domZ=None)

Instantiate and configure a new accelerated comparison pipeline.

Parameters

  • alphabet (Alphabet) – The biological alphabet the of the HMMs and sequences that are going to be compared. Used to build the background model.

  • background (Background, optional) – The background model to use with the pipeline, or None to create and use a default one. The pipeline needs ownership of the background model, so any background model passed there will be copied.

Keyword Arguments

  • bias_filter (bool) – Whether or not to enable composition bias filter. Defaults to True.

  • null2 (bool) – Whether or not to compute biased composition score corrections. Defaults to True.

  • report_e (float) – Report hits with e-value lower than or equal to this threshold in output. Defaults to 10.0.

  • seed (int, optional) – The seed to use with the random number generator. Pass 0 to use a one-time arbitrary seed, or None to keep the default seed from HMMER.

clear()

Reset the pipeline configuration to its default state.

scan_seq(query, hmms)

Run the pipeline using a query sequence against a profile database.

Parameters

  • query (DigitalSequence) – The sequence object to use to query the profile database.

  • hmms (iterable of DigitalSequence) – The HMM profiles to query. Pass a HMMFile instance to read from disk iteratively.

Returns

TopHits – the hits found in the profile database.

Raises

AlphabetMismatch – When the alphabet of the current pipeline does not match the alphabet of the given query or profile.

Caution

In the current version, this method is not optimized to use the pressed database, even if it exists. This will cause the MSV and SSV filters to be rebuilt at each iteration, which could be slow. Consider at least pre-fetching the HMM database if calling this method several times in a row.

New in version v0.4.0.

search_hmm(query, sequences)

Run the pipeline using a query HMM against a sequence database.

Parameters

  • query (HMM) – The HMM object to use to query the sequence database.

  • sequences (iterable of DigitalSequence) – The sequences to query with the HMM. For instance, pass a SequenceFile in digital mode to read from disk iteratively.

Returns

TopHits – the hits found in the sequence database.

Raises

AlphabetMismatch – When the alphabet of the current pipeline does not match the alphabet of the given HMM.

New in version 0.2.0.

search_msa(query, sequences, builder=None)

Run the pipeline using a query alignment against a sequence database.

Parameters

  • query (DigitalMSA) – The multiple sequence alignment to use to query the sequence database.

  • sequences (iterable of DigitalSequence) – The sequences to query. Pass a SequencesFile instance in digital mode to read from disk iteratively.

  • builder (Builder, optional) – A HMM builder to use to convert the query to a HMM. If None is given, it will use a default one.

Returns

TopHits – the hits found in the sequence database.

Raises

AlphabetMismatch – When the alphabet of the current pipeline does not match the alphabet of the given query.

New in version 0.3.0.

search_seq(query, sequences, builder=None)

Run the pipeline using a query sequence against a sequence database.

Parameters

  • query (DigitalSequence) – The sequence object to use to query the sequence database.

  • sequences (iterable of DigitalSequence) – The sequences to query. Pass a SequenceFile instance in digital mode to read from disk iteratively.

  • builder (Builder, optional) – A HMM builder to use to convert the query to a HMM. If None is given, it will use a default one.

Returns

TopHits – the hits found in the sequence database.

Raises

AlphabetMismatch – When the alphabet of the current pipeline does not match the alphabet of the given query.

New in version 0.2.0.

Z

The number of effective targets searched.

It is used to compute the independent e-value for each domain, and for an entire hit. If None, the parameter number will be set automatically after all the comparisons have been done. Otherwise, it can be set to an arbitrary number.

Type

float or None

domZ

The number of significant targets.

It is used to compute the conditional e-value for each domain. If None, the parameter number will be set automatically after all the comparisons have been done, and all hits have been thresholded. Otherwise, it can be set to an arbitrary number.

Type

float or None

seed

The seed used by the internal random number generator.

New in version 0.2.0.

Type

int

Profile

class pyhmmer.plan7.Profile

A Plan7 search profile.

__init__(M, alphabet)

Create a new profile for the given alphabet.

Parameters

  • M (int) – The length of the profile, i.e. the number of nodes.

  • alphabet (Alphabet) – The alphabet to use with this profile.

clear()

Clear internal buffers to reuse the profile without reallocation.

configure(hmm, background, L, multihit=True, local=True)

Configure a search profile using the given models.

Parameters

  • hmm (pyhmmer.plan7.HMM) – The model HMM with core probabilities.

  • bg (pyhmmer.plan7.Background) – The null background model.

  • L (int) – The expected target sequence length.

  • multihit (bool) – Whether or not to use multihit modes.

  • local (bool) – Whether or not to use non-local modes.

copy()

Return a copy of the profile with the exact same configuration.

is_local()

Return whether or not the profile is in a local alignment mode.

is_multihit()

Returns whether or not the profile is in a multihit alignment mode.

optimized()

Convert the profile to a platform-specific optimized profile.

Returns

OptimizedProfile – The platform-specific optimized profile built using the configuration of this profile.

L

The current configured target sequence length.

Type

int

M

The length of the profile (i.e. the number of nodes).

New in version 0.3.0.

Type

int

accession

The accession of the profile, if any.

New in version 0.3.0.

Type

bytes or None

description

The description of the profile, if any.

New in version 0.3.0.

Type

bytes or None

name

The name of the profile, if any.

New in version 0.3.0.

Type

bytes or None

class pyhmmer.plan7.OptimizedProfile

An optimized profile that uses platform-specific instructions.

__init__(M, alphabet)

Create a new optimized profile from scratch.

Optimized profiles use platform-specific code to accelerate the various algorithms. Although you can allocate an optimized profile yourself, the only way to obtain a fully configured profile is to create it with the Profile.optimized method, after having configured the profile for a given HMM with Profile.configure.

Parameters

  • M (int) – The length of the model (i.e. the number of nodes).

  • alphabet (Alphabet) – The alphabet of the model.

copy()

Create an exact copy of the optimized profile.

is_local()

Return whether or not the profile is in a local alignment mode.

write(fh_filter, fh_profile)

Write an optimized profile to two separate files.

HMMER implements an acceleration pipeline using several scoring algorithms. Parameters for MSV (the Multi ungapped Segment Viterbi) are saved independently to the fh_filter handle, while the rest of the profile is saved to fh_profile.