Easel¶

High-level interface to the Easel C library.

Easel is a library developed by the Eddy/Rivas Lab to facilitate the development of biological software in C. It is used by HMMER and Infernal.

Alphabet¶

class pyhmmer.easel.Alphabet¶

A biological alphabet, including additional marker symbols.

This type is used to share an alphabet to several objects in the easel and plan7 modules. Reference counting helps sharing the same instance everywhere, instead of reallocating memory every time an alphabet is needed.

Use the factory class methods to obtain a default Alphabet for one of the three biological alphabets:

>>> dna = Alphabet.dna()
>>> rna = Alphabet.rna()
>>> aa  = Alphabet.amino()

amino()¶: Create a default amino-acid alphabet.

dna()¶: Create a default DNA alphabet.

rna()¶: Create a default RNA alphabet.

K¶

The alphabet size, counting only actual alphabet symbols.

Example

>>> Alphabet.dna().K
4
>>> Alphabet.amino().K
20

Type: int

Kp¶

The complete alphabet size, including marker symbols.

Example

>>> Alphabet.dna().Kp
18
>>> Alphabet.amino().Kp
29

Type: int

symbols¶

The symbols composing the alphabet.

Example

>>> Alphabet.dna().symbols
'ACGT-RYMKSWHBVDN*~'
>>> Alphabet.rna().symbols
'ACGU-RYMKSWHBVDN*~'

Type: str

Bitfield¶

class pyhmmer.easel.Bitfield¶

A statically sized sequence of booleans stored as a packed bitfield.

A bitfield is instantiated with a fixed length, and all booleans are set to False by default:

>>> bitfield = Bitfield(8)
>>> len(bitfield)
8
>>> bitfield[0]
False

count(value=True)¶

Count the number occurrences of value in the bitfield.

If no argument is given, counts the number of True occurences.

Example

>>> bitfield = Bitfield(8)
>>> bitfield.count(False)
8
>>> bitfield[0] = bitfield[1] = True
>>> bitfield.count()
2

toggle(index)¶

Switch the value of one single bit.

Example

>>> bitfield = Bitfield(8)
>>> bitfield[0]
False
>>> bitfield.toggle(0)
>>> bitfield[0]
True
>>> bitfield.toggle(0)
>>> bitfield[0]
False

KeyHash¶

class pyhmmer.easel.KeyHash¶

A dynamically resized container to store string keys using a hash table.

clear()¶: Remove all entries from the collection.

copy()¶: Create and return an exact copy of this mapping.

Multiple Sequence Alignment¶

class pyhmmer.easel.MSA¶

An abstract alignment of multiple sequences.

checksum()¶: Calculate a 32-bit checksum for the multiple sequence alignment.

class pyhmmer.easel.TextMSA(MSA)¶

A multiple sequence alignement stored in text mode.

copy()¶: Duplicate the text sequence alignment, and return the copy.

digitize(alphabet)¶

Convert the text alignment to a digital alignment using alphabet.

Returns: DigitalMSA – An alignment in digital mode containing the same sequences digitized with alphabet.

class pyhmmer.easel.DigitalMSA(MSA)¶

A multiple sequence alignment stored in digital mode.

alphabet¶

The biological alphabet used to encode this sequence alignment to digits.

Type: Alphabet

copy()¶: Duplicate the digital sequence alignment, and return the copy.

Sequence¶

class pyhmmer.easel.Sequence¶

An abstract biological sequence with some associated metadata.

Easel provides two different mode to store a sequence: text, or digital. In the HMMER code, changing from one mode to another mode is done in place, which allows recycling memory. However, doing so can be confusing since there is no way to know statically the representation of a sequence.

To avoid this, pyhmmer provides two subclasses of the Sequence abstract class to maintain the mode contract: TextSequence and DigitalSequence. Functions expecting sequences in digital format, like pyhmmer.hmmsearch, can then use Python type system to make sure they receive sequences in the right mode. This allows type checkers such as mypy to detect potential contract breaches at compile-time.

checksum()¶: Calculate a 32-bit checksum for the sequence.

clear()¶: Reinitialize the sequence for re-use.

accession¶

The accession of the sequence.

Type: bytes

description¶

The description of the sequence.

Type: bytes

name¶

The name of the sequence.

Type: bytes

source¶

The source of the sequence, if any.

Type: bytes

class pyhmmer.easel.TextSequence(Sequence)¶

A biological sequence stored in text mode.

Hint

Use the sequence property to access the sequence letters as a Python string.

copy()¶: Duplicate the text sequence, and return the copy.

digitize(alphabet)¶

Convert the text sequence to a digital sequence using alphabet.

Returns: DigitalSequence – A copy of the sequence in digital-model, digitized with alphabet.

sequence¶

The raw sequence letters, as a Python string.

Type: str

class pyhmmer.easel.DigitalSequence(Sequence)¶

A biological sequence stored in digital mode.

Hint

Use the sequence property to access the sequence digits as a memory view, allowing to access the individual bytes. This can be combined with numpy.asarray to get the sequence as an array with zero-copy.

alphabet¶

The biological alphabet used to encode this sequence to digits.

Type: Alphabet, readonly

copy()¶: Duplicate the digital sequence, and return the copy.

textize()¶

Convert the digital sequence to a text sequence.

Returns: TextSequence – A copy of the sequence in text-mode.

sequence¶

The raw sequence digits, as a memory view.

Type: memoryview

Sequence File¶

class pyhmmer.easel.SequenceFile¶

A wrapper around a sequence file, containing unaligned sequences.

This class supports reading sequences stored in different formats, such as FASTA, GenBank or EMBL. The format of each file can be automatically detected, but it is also possible to pass an explicit format specifier when the SequenceFile is instantiated.

close()¶: Close the file and free the resources used by the parser.

guess_alphabet()¶

Guess the alphabet of an open SequenceFile.

This method tries to guess the alphabet of a sequence file by inspecting the first sequence in the file. It returns the alphabet, or None if the file alphabet cannot be reliably guessed.

Raises

EOFError – if the file is empty.
OSError – if a parse error occurred.
ValueError – if this methods is called after the file was closed.

parse(buffer, format)¶: Parse a sequence from a binary buffer using the given format.

parseinto(seq, buffer, format)¶: Parse a sequence from a binary buffer into seq.

read(skip_info=False, skip_sequence=False)¶

Read the next sequence from the file.

Parameters

skip_info (bool) – Pass True to disable reading the sequence metadata, and only read the sequence letters. Defaults to False.
skip_sequence (bool) – Pass True to disable reading the sequence letters, and only read the sequence metadata. Defaults to False.

Returns

Sequence – The next sequence in the file, or None if all sequences were read from the file.

Raises

ValueError – When attempting to read a sequence from a closed file, or when the file could not be parsed.

Hint

This method allocates a new sequence, which is not efficient in case the sequences are being read within a tight loop. Use SequenceFile.readinto with an already initialized Sequence if you can to recycle the internal buffers.

readinto(seq, skip_info=False, skip_sequence=False)¶

Read the next sequence from the file, using seq to store data.

Parameters

seq (Sequence) – A sequence object to use to store the next entry in the file. If this sequence was used before, it must be properly reset (using the Sequence.clear method) before using it again with readinto.
skip_info (bool) – Pass True to disable reading the sequence metadata, and only read the sequence letters. Defaults to False`.
skip_sequence (bool) – Pass True to disable reading the sequence letters, and only read the sequence metadata. Defaults to False.

Returns

Sequence – A reference to seq that was passed as an input, or None if no sequences are left in the file.

Raises

ValueError – When attempting to read a sequence from a closed file, or when the file could not be parsed.

Example

Use SequenceFile.readinto to loop over the sequences in a file while recycling the same Sequence buffer:

>>> with SequenceFile("vendor/hmmer/testsuite/ecori.fa") as sf:
...     seq = TextSequence()
...     while sf.readinto(seq) is not None:
...         # ... process seq here ... #
...         seq.clear()

set_digital(alphabet)¶

Set the SequenceFile to read in digital mode with alphabet.

This method can be called even after the first sequences have been read; it only affects subsequent sequences in the file.

Sequence / Subsequence Index¶

class pyhmmer.easel.SSIReader¶

A read-only handler for sequence/subsequence index file.

class Entry(fd, record_offset, data_offset, record_length)¶

property data_offset¶: Alias for field number 2

property fd¶: Alias for field number 0

property record_length¶: Alias for field number 3

property record_offset¶: Alias for field number 1

class FileInfo(name, format)¶

property format¶: Alias for field number 1

property name¶: Alias for field number 0

close()¶: Close the SSI file reader.

file_info(fd)¶: Retrieve the FileInfo of the descriptor.

find_name(key)¶: Retrieve the Entry for the given name.

class pyhmmer.easel.SSIWriter¶

A writer for sequence/subsequence index files.

add_alias(alias, key)¶: Make alias an alias of key in the index.

add_file(filename, format=0)¶

Add a new file to the index.

Parameters

filename (str) – The name of the file to register.
format (int) – A format code to associate with the file, or 0.

Returns

int – The filehandle associated with the new indexed file.

add_key(key, fd, record_offset, data_offset=0, record_length=0)¶: Add a new entry to the index with the given key.

close()¶: Close the SSI file writer.