Multiple Sequence Alignment#

class pytrimal.Alignment#

A multiple sequence alignment.

__init__(names, sequences)#

Create a new alignment with the given names and sequences.

Parameters:

  • names (Sequence of bytes) – The names of the sequences in the alignment.

  • sequences (Sequence of bytes or str) – The actual sequences in the alignment.

  • sequence_type (str or None) – The type of sequences stored in the alignment, one of protein, dna or rna. If None given, use the trimAl strategy to auto-detect the type. This is used in some trimmer statistics to correctly identify indetermintation symbols (X for protein sequences, N for DNA and RNA sequences).

Examples

Create a new alignment with a list of sequences and a list of names:

>>> alignment = Alignment(
...     names=[b"Sp8", b"Sp10", b"Sp26"],
...     sequences=[
...         "-----GLGKVIV-YGIVLGTKSDQFSNWVVWLFPWNGLQIHMMGII",
...         "-------DPAVL-FVIMLGTIT-KFS--SEWFFAWLGLEINMMVII",
...         "AAAAAAAAALLTYLGLFLGTDYENFA--AAAANAWLGLEINMMAQI",
...     ]
... )

There should be as many sequences as there are names, otherwise a ValueError will be raised:

>>> Alignment(
...     names=[b"Sp8", b"Sp10", b"Sp26"],
...     sequences=["GLQIHMMGII", "GLEINMMVII"]
... )
Traceback (most recent call last):
...
ValueError: `Alignment` given 3 names but 2 sequences

Sequence characters will be checked, and an error will be raised if they are not one of the characters from a biological alphabet:

>>> Alignment(
...     names=[b"Sp8", b"Sp10"],
...     sequences=["GLQIHMMGII", "GLEINMM123"]
... )
Traceback (most recent call last):
...
ValueError: The sequence "Sp10" has an unknown (49) character

Added in version 0.9.0: The sequence_type argument.

copy()#

Create a copy of this alignment.

dump()#

Dump the alignment to a file or a file-like object.

Parameters:

  • file (str, bytes, os.PathLike or file-like object) – The file to which to write the alignment. If a file-like object is given, it must be open in binary mode. Otherwise, file is treated as a path.

  • format (str) – The name of the alignment format to write. See below for a list of supported formats.

Raises:

  • ValueError – When format is not a recognized file format.

  • OSError – When the path given as file could not be opened.

Hint

The alignment can be written in one of the following formats:

clustal

The alignment format produced by the Clustal and Clustal Omega alignment softwares.

fasta

The aligned FASTA format, which outputs all sequences in the alignment as FASTA records with gap characters (see FASTA format).

html

An HTML report showing alignment in pseudo-Clustal format with colored residues.

mega

The alignment format produced by the MEGA software for evolutionary analysis of alignments.

nexus

The NEXUS alignment format (see Nexus file).

phylip (or phylip40):

The PHYLIP 4.0 alignment format.

phylip32

The PHYLIP 3.2 alignment format.

phylippaml

A variant of PHYLIP 4.0 compatible with the PAML tool for phylogenetic analysis.

nbrf or pir

The format of Protein Information Resource database files, provided by the National Biomedical Research Foundation.

Additionally, the fasta, nexus, phylippaml, phylip32, and phylip40 formats support an _m10 variant, which limits the sequence names to 10 characters.

Added in version 0.2.2.

dumps()#

Dump the alignment to a string in the provided format.

Parameters:

  • format (str) – The format of the alignment. See the dump method for a list of supported formats.

  • encoding (str) – The encoding to use to decode sequence names.

Raises:

ValueError – When format is not a recognized file format.

Added in version 0.2.2.

from_biopython()#

Create a new Alignment from an iterable of Biopython records.

Parameters:

alignment (iterable of SeqRecord) – An iterable of Biopython records objects to build the alignment from. Passing a Bio.Align.MultipleSeqAlignment object is also supported.

Returns:

Alignment – A new alignment object ready for trimming.

Added in version 0.5.0.

from_pyhmmer()#

Create a new Alignment from a pyhmmer.easel.TextMSA.

Parameters:

alignment (TextMSA) – A PyHMMER object storing a multiple sequence alignment in text format.

Returns:

Alignment – A new alignment object ready for trimming.

Added in version 0.5.0.

load()#

Load a multiple sequence alignment from a file.

Parameters:

  • path (str, bytes, os.PathLike or file-like object) – The file from which to read the alignment. If a file-like object is given, it must be open in binary mode and support random access with the seek method. Otherwise, file is treated as a path.

  • format (str, optional) – The file-format the alignment is stored in. Must be given when loading from a file-like object, will be autodetected when reading from a file.

Returns:

Alignment – The deserialized alignment.

Example

>>> msa = Alignment.load("example.001.AA.clw")
>>> msa.names
[b'Sp8', b'Sp10', b'Sp26', b'Sp6', b'Sp17', b'Sp33']

Changed in version 0.3.0: Add support for reading code from a file-like object.

to_biopython()#

Create a new MultipleSeqAlignment from this Alignment.

Returns:

MultipleSeqAlignment – A multiple sequence alignment object as implemented in Biopython.

Raises:

ImportError – When the Bio module cannot be imported.

Added in version 0.5.0.

to_pyhmmer()#

Create a new TextMSA from this Alignment.

Returns:

TextMSA – A PyHMMER multiple sequence alignment in text mode.

Raises:

ImportError – When the pyhmmer module cannot be imported.

Added in version 0.5.0.

names#

The names of the sequences in the alignment.

Type:

sequence of bytes

residues#

The residues in the alignment.

Type:

AlignmentResidues

sequence_type#

The type of sequences in the alignment.

Usually one of protein, dna or rna; in the case where the trimAl auto-detection failed, this will be None. This field is used in some trimmer statistics to correctly identify indetermintation symbols (X for protein sequences, N for DNA and RNA sequences).

Example

>>> alignment = Alignment(
...     names=[b"Sp8", b"Sp10", b"Sp26"],
...     sequences=[
...         "-----GLGKVIV-YGIVLGTKSDQFSNWVVWLFPWNGLQIHMMGII",
...         "-------DPAVL-FVIMLGTIT-KFS--SEWFFAWLGLEINMMVII",
...         "AAAAAAAAALLTYLGLFLGTDYENFA--AAAANAWLGLEINMMAQI",
...     ]
... )
>>> alignment.sequence_type
'protein'

Added in version 0.9.0.

Type:

str or None

sequences#

The sequences in the alignment.

Type:

AlignmentSequences

class pytrimal.TrimmedAlignment(Alignment)#

A multiple sequence alignment that has been trimmed.

Internally, the trimming process produces a mask of sequences and a mask of residues. This class only exposes the filtered sequences and residues.

Example

Create a trimmed alignment using two lists to filter out some residues and sequences:

>>> trimmed = TrimmedAlignment(
...    names=[b"Sp8", b"Sp10", b"Sp26"],
...    sequences=["QFSNWV", "KFS--S", "NFA--A"],
...    sequences_mask=[True, True, False],
...    residues_mask=[True, True, True, False, False, True],
... )

The names and sequences properties will only contain the retained sequences and residues:

>>> list(trimmed.names)
[b'Sp8', b'Sp10']
>>> list(trimmed.sequences)
['QFSV', 'KFSS']

Use the original_alignment method to build the original unfiltered alignment containing all sequences and residues:

>>> ali = trimmed.original_alignment()
>>> list(ali.names)
[b'Sp8', b'Sp10', b'Sp26']
>>> list(ali.sequences)
['QFSNWV', 'KFS--S', 'NFA--A']
__init__(names, sequences, sequences_mask=None, residues_mask=None)#

Create a new alignment with the given names, sequences and masks.

Parameters:

  • names (Sequence of bytes) – The names of the sequences in the alignment.

  • sequences (Sequence of str) – The actual sequences in the alignment.

  • sequences_mask (Sequence of bool) – A mask for which sequences to keep in the trimmed alignment. If given, must be as long as the sequences and names list.

  • residues_mask (Sequence of bool) – A mask for which residues to keep in the trimmed alignment. If given, must be as long as every element in the sequences argument.

copy()#

Create a copy of this trimmed alignment.

load()#

Load a multiple sequence alignment from a file.

Parameters:

  • path (str, bytes, os.PathLike or file-like object) – The file from which to read the alignment. If a file-like object is given, it must be open in binary mode and support random access with the seek method. Otherwise, file is treated as a path.

  • format (str, optional) – The file-format the alignment is stored in. Must be given when loading from a file-like object, will be autodetected when reading from a file.

Returns:

Alignment – The deserialized alignment.

Example

>>> msa = Alignment.load("example.001.AA.clw")
>>> msa.names
[b'Sp8', b'Sp10', b'Sp26', b'Sp6', b'Sp17', b'Sp33']

Changed in version 0.3.0: Add support for reading code from a file-like object.

original_alignment()#

Rebuild the original alignment from which this object was obtained.

Returns:

Alignment – The untrimmed alignment that produced this trimmed alignment.

terminal_only()#

Get a trimmed alignment where only the terminal residues are removed.

Returns:

TrimmedAlignment – The alignment where only terminal residues have been trimmed.

residues_mask#

Which residues are kept in the alignment.

Type:

sequence of bool

sequences_mask#

Which sequences are kept in the alignment.

Type:

sequence of bool

class pytrimal.AlignmentSequences#

A read-only view over the sequences of an alignment.

Objects from this class are created in the sequences property of Alignment objects. Use it to access the string data of individual rows from the alignment:

>>> msa = Alignment.load("example.001.AA.clw")
>>> len(msa.sequences)
6
>>> msa.sequences[0]
'-----GLGKVIV-YGIVLGTKSDQFSNWVVWLFPWNGLQIHMMGII'
>>> sum(seq.count('-') for seq in msa.sequences)
43

A slice over a subset of the sequences can be obtained as well without having to copy the internal data, allowing to create a new Alignment with only some sequences from the original one:

>>> msa2 = Alignment(msa.names[:4:2], msa.sequences[:4:2])
>>> len(msa2.sequences)
2
>>> msa2.sequences[1] == msa.sequences[2]
True

Added in version 0.4.0: Support for zero-copy slicing.

__getitem__(key, /)#

Return self[key].

__len__()#

Return len(self).

class pytrimal.AlignmentResidues#

A read-only view over the residues of an alignment.

Objects from this class are created in the residues property of Alignment objects. Use it to access the string data of individual columns from the alignment:

>>> msa = Alignment.load("example.001.AA.clw")
>>> len(msa.residues)
46
>>> msa.residues[0]
'--A---'
>>> msa.residues[-1]
'IIIIFL'

Added in version 0.4.0: Support for zero-copy slicing.

__getitem__(key, /)#

Return self[key].

__len__()#

Return len(self).