biotite 0.41.1__cp312-cp312-win_amd64.whl → 1.0.0__cp312-cp312-win_amd64.whl

biotite/sequence/align/matrix.py

@@ -5,11 +5,9 @@
 __name__ = "biotite.sequence.align"
 __author__ = "Patrick Kunzmann"
 
-from ..sequence import Sequence
-from ..seqtypes import NucleotideSequence, ProteinSequence
-from ..alphabet import Alphabet
-import numpy as np
 import os
+import numpy as np
+from biotite.sequence.seqtypes import NucleotideSequence, ProteinSequence
 
 __all__ = ["SubstitutionMatrix"]
 
@@ -21,54 +19,54 @@ class SubstitutionMatrix(object):
     A :class:`SubstitutionMatrix` maps each possible pairing of a symbol
     of a first alphabet with a symbol of a second alphabet to a score
     (integer).
-    
+
     The class uses a 2-D (m x n) :class:`ndarray`
     (dtype=:attr:`numpy.int32`),
     where each element stores the score for a symbol pairing, indexed
     by the symbol codes of the respective symbols in an *m*-length
     alphabet 1 and an *n*-length alphabet 2.
-    
+
     There are 3 ways to creates instances:
-    
+
     At first a 2-D :class:`ndarray` containing the scores can be
     directly provided.
-    
+
     Secondly a dictionary can be provided, where the keys are pairing
     tuples and values are the corresponding scores.
     The pairing tuples consist of a symbol of alphabet 1 as first
     element and a symbol of alphabet 2 as second element. Parings have
     to be provided for each possible combination.
-    
+
     At last a valid matrix name can be given, which is loaded from the
     internal matrix database. The following matrices are avaliable:
-        
+
         - Nucleotide substitution matrices from NCBI database
             - **NUC** - Also usable with ambiguous alphabet
-        
+
         - Protein substitution matrices from NCBI database
-        
+
             - **PAM<n>**
             - **BLOSUM<n>**
             - **MATCH** - Only differentiates between match and mismatch
             - **IDENTITY** - Strongly penalizes mismatches
             - **GONNET** - Not usable with default protein alphabet
             - **DAYHOFF**
-        
+
         - Corrected protein substitution matrices :footcite:`Hess2016`,
           **<BLOCKS>** is the BLOCKS version, the matrix is based on
-            
+
             - **BLOSUM<n>_<BLOCKS>**
             - **RBLOSUM<n>_<BLOCKS>**
             - **CorBLOSUM<n>_<BLOCKS>**
-    
+
     A list of all available matrix names is returned by
     :meth:`list_db()`.
-    
+
     Since this class can handle two different alphabets, it is possible
     to align two different types of sequences.
-    
+
     Objects of this class are immutable.
-    
+
     Parameters
     ----------
     alphabet1 : Alphabet, length=m
@@ -79,23 +77,23 @@ class SubstitutionMatrix(object):
         Either a symbol code indexed :class:`ndarray` containing the scores,
         or a dictionary mapping the symbol pairing to scores,
         or a string referencing a matrix in the internal database.
-    
+
     Raises
     ------
     KeyError
         If the matrix dictionary misses a symbol given in the alphabet.
-    
+
     References
     ----------
-    
+
     .. footbibliography::
-    
+
     Examples
     --------
-    
+
     Creating a matrix for two different (nonsense) alphabets
     via a matrix dictionary:
-    
+
     >>> alph1 = Alphabet(["foo","bar"])
     >>> alph2 = Alphabet([1,2,3])
     >>> matrix_dict = {("foo",1):5,  ("foo",2):10, ("foo",3):15,
@@ -119,17 +117,16 @@ class SubstitutionMatrix(object):
     C   0   1   0   0
     G   0   0   1   0
     T   0   0   0   1
-    
+
     Creating a matrix via database name:
-        
+
     >>> alph = ProteinSequence.alphabet
     >>> matrix = SubstitutionMatrix(alph, alph, "BLOSUM50")
     """
-    
+
     # Directory of matrix files
-    _db_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)),
-                                           "matrix_data")
-    
+    _db_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "matrix_data")
+
     def __init__(self, alphabet1, alphabet2, score_matrix):
         self._alph1 = alphabet1
         self._alph2 = alphabet2
@@ -147,16 +144,19 @@ class SubstitutionMatrix(object):
             matrix_dict = SubstitutionMatrix.dict_from_db(score_matrix)
             self._fill_with_matrix_dict(matrix_dict)
         else:
-            raise TypeError("Matrix must be either a dictionary, "
-                            "an 2-D ndarray or a string")
+            raise TypeError(
+                "Matrix must be either a dictionary, " "an 2-D ndarray or a string"
+            )
         # This class is immutable and has a getter function for the
         # score matrix -> make the score matrix read-only
         self._matrix.setflags(write=False)
 
     def __repr__(self):
         """Represent SubstitutionMatrix as a string for debugging."""
-        return f"SubstitutionMatrix({self._alph1.__repr__()}, {self._alph2.__repr__()}, " \
-               f"np.{np.array_repr(self._matrix)})"
+        return (
+            f"SubstitutionMatrix({self._alph1.__repr__()}, {self._alph2.__repr__()}, "
+            f"np.{np.array_repr(self._matrix)})"
+        )
 
     def __eq__(self, item):
         if not isinstance(item, SubstitutionMatrix):
@@ -173,40 +173,39 @@ class SubstitutionMatrix(object):
         return not self == item
 
     def _fill_with_matrix_dict(self, matrix_dict):
-        self._matrix = np.zeros(( len(self._alph1), len(self._alph2) ),
-                                dtype=np.int32)
+        self._matrix = np.zeros((len(self._alph1), len(self._alph2)), dtype=np.int32)
         for i in range(len(self._alph1)):
             for j in range(len(self._alph2)):
                 sym1 = self._alph1.decode(i)
                 sym2 = self._alph2.decode(j)
-                self._matrix[i,j] = int(matrix_dict[sym1, sym2])
-    
+                self._matrix[i, j] = int(matrix_dict[sym1, sym2])
+
     def get_alphabet1(self):
         """
-        Get the first alphabet. 
-        
+        Get the first alphabet.
+
         Returns
         -------
         alphabet : Alphabet
             The first alphabet.
         """
         return self._alph1
-    
+
     def get_alphabet2(self):
         """
-        Get the second alphabet. 
-        
+        Get the second alphabet.
+
         Returns
         -------
         alphabet : Alphabet
             The second alphabet.
         """
         return self._alph2
-    
+
     def score_matrix(self):
         """
         Get the 2-D :class:`ndarray` containing the score values.
-        
+
         Returns
         -------
         matrix : ndarray, shape=(m,n), dtype=np.int32
@@ -214,12 +213,12 @@ class SubstitutionMatrix(object):
             The array is read-only.
         """
         return self._matrix
-    
+
     def transpose(self):
         """
         Get a copy of this instance, where the alphabets are
         interchanged.
-        
+
         Returns
         -------
         transposed : SubstitutionMatrix
@@ -229,7 +228,7 @@ class SubstitutionMatrix(object):
         new_alph2 = self._alph1
         new_matrix = np.transpose(self._matrix)
         return SubstitutionMatrix(new_alph1, new_alph2, new_matrix)
-    
+
     def is_symmetric(self):
         """
         Check whether the substitution matrix is symmetric,
@@ -242,35 +241,36 @@ class SubstitutionMatrix(object):
             True, if both alphabets are identical and the score matrix
             is symmetric, false otherwise.
         """
-        return     self._alph1 == self._alph2 \
-               and np.array_equal(self._matrix, np.transpose(self._matrix))
-    
+        return self._alph1 == self._alph2 and np.array_equal(
+            self._matrix, np.transpose(self._matrix)
+        )
+
     def get_score_by_code(self, code1, code2):
         """
         Get the substitution score of two symbols,
         represented by their code.
-        
+
         Parameters
         ----------
         code1, code2 : int
             Symbol codes of the two symbols to be aligned.
-        
+
         Returns
         -------
         score : int
             The substitution / alignment score.
         """
         return self._matrix[code1, code2]
-    
+
     def get_score(self, symbol1, symbol2):
         """
         Get the substitution score of two symbols.
-        
+
         Parameters
         ----------
         symbol1, symbol2 : object
             Symbols to be aligned.
-        
+
         Returns
         -------
         score : int
@@ -279,19 +279,19 @@ class SubstitutionMatrix(object):
         code1 = self._alph1.encode(symbol1)
         code2 = self._alph2.encode(symbol2)
         return self._matrix[code1, code2]
-    
+
     def shape(self):
         """
         Get the shape (i.e. the length of both alphabets)
         of the subsitution matrix.
-        
+
         Returns
         -------
         shape : tuple
             Matrix shape.
         """
         return (len(self._alph1), len(self._alph2))
-    
+
     def __str__(self):
         # Create matrix in NCBI format
         string = " "
@@ -306,18 +306,18 @@ class SubstitutionMatrix(object):
         # Remove terminal line break
         string = string[:-1]
         return string
-    
+
     @staticmethod
     def dict_from_str(string):
         """
         Create a matrix dictionary from a string in NCBI matrix format.
-        
+
         Symbols of the first alphabet are taken from the left column,
         symbols of the second alphabet are taken from the top row.
-        
+
         The keys of the dictionary consist of tuples containing the
         aligned symbols and the values are the corresponding scores.
-        
+
         Returns
         -------
         matrix_dict : dict
@@ -329,22 +329,22 @@ class SubstitutionMatrix(object):
         symbols2 = [e for e in lines[0].split()]
         scores = np.array([line.split()[1:] for line in lines[1:]]).astype(int)
         scores = np.transpose(scores)
-        
+
         matrix_dict = {}
         for i in range(len(symbols1)):
             for j in range(len(symbols2)):
-                matrix_dict[(symbols1[i], symbols2[j])] = scores[i,j]
+                matrix_dict[(symbols1[i], symbols2[j])] = scores[i, j]
         return matrix_dict
-    
+
     @staticmethod
     def dict_from_db(matrix_name):
         """
         Create a matrix dictionary from a valid matrix name in the
         internal matrix database.
-        
+
         The keys of the dictionary consist of tuples containing the
         aligned symbols and the values are the corresponding scores.
-        
+
         Returns
         -------
         matrix_dict : dict
@@ -353,12 +353,12 @@ class SubstitutionMatrix(object):
         filename = SubstitutionMatrix._db_dir + os.sep + matrix_name + ".mat"
         with open(filename, "r") as f:
             return SubstitutionMatrix.dict_from_str(f.read())
-    
+
     @staticmethod
     def list_db():
         """
         List all matrix names in the internal database.
-        
+
         Returns
         -------
         db_list : list
@@ -367,27 +367,26 @@ class SubstitutionMatrix(object):
         files = os.listdir(SubstitutionMatrix._db_dir)
         # Remove '.mat' from files
         return [file[:-4] for file in sorted(files)]
-        
-    
+
     @staticmethod
     def std_protein_matrix():
         """
         Get the default :class:`SubstitutionMatrix` for protein sequence
         alignments, which is BLOSUM62.
-        
+
         Returns
         -------
         matrix : SubstitutionMatrix
             Default matrix.
         """
         return _matrix_blosum62
-    
+
     @staticmethod
     def std_nucleotide_matrix():
         """
         Get the default :class:`SubstitutionMatrix` for DNA sequence
         alignments.
-        
+
         Returns
         -------
         matrix : SubstitutionMatrix
@@ -395,11 +394,11 @@ class SubstitutionMatrix(object):
         """
         return _matrix_nuc
 
-# Preformatted BLOSUM62 and NUC substitution matrix from NCBI
-_matrix_blosum62 = SubstitutionMatrix(ProteinSequence.alphabet,
-                                      ProteinSequence.alphabet,
-                                      "BLOSUM62")
-_matrix_nuc = SubstitutionMatrix(NucleotideSequence.alphabet_amb,
-                                 NucleotideSequence.alphabet_amb,
-                                 "NUC")
 
+# Preformatted BLOSUM62 and NUC substitution matrix from NCBI
+_matrix_blosum62 = SubstitutionMatrix(
+    ProteinSequence.alphabet, ProteinSequence.alphabet, "BLOSUM62"
+)
+_matrix_nuc = SubstitutionMatrix(
+    NucleotideSequence.alphabet_amb, NucleotideSequence.alphabet_amb, "NUC"
+)

biotite/sequence/align/multiple.pyx

@@ -39,9 +39,9 @@ cdef float32 MAX_FLOAT = np.finfo(np.float32).max
 
 
 class GapSymbol:
-    
+
     _instance = None
-    
+
     def __init__(self):
         if GapSymbol._instance is not None:
             raise ValueError(
@@ -49,16 +49,16 @@ class GapSymbol:
             )
         else:
             GapSymbol._instance = self
-    
+
     @staticmethod
     def instance():
         if GapSymbol._instance is None:
             GapSymbol._instance = GapSymbol()
         return GapSymbol._instance
-    
+
     def __str__(self):
         return "-"
-    
+
     def __hash__(self):
         return 0
 
@@ -69,13 +69,13 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
     align_multiple(sequences, matrix, gap_penalty=-10,
                    terminal_penalty=True, distances=None,
                    guide_tree=None)
-    
+
     Perform a multiple sequence alignment using a progressive
     alignment algorithm. :footcite:`Feng1987`
 
     Based on pairwise sequence distances a guide tree is constructed.
     The sequences are progessively aligned according to the tree,
-    following the rule 'Once a gap, always a gap'. 
+    following the rule 'Once a gap, always a gap'.
 
     Parameters
     ----------
@@ -124,7 +124,7 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
     distance_matrix : ndarray, shape=(n,n), dtype=float32
         The pairwise distance matrix used to construct the guide tree.
         Equal to `distances` if provided.
-    
+
     Notes
     -----
     The similarity to distance conversion is performed according to the
@@ -137,14 +137,14 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
               \right)
 
     .. math:: S_{a,b}^{max} = \frac{ S_{a,a} + S_{b,b} }{ 2 }
-    
+
     .. math:: S_{a,b}^{rand} = \frac{1}{L_{a,b}}
               \left(
                  \sum_{x \in \Omega} \sum_{y \in \Omega}
                  s_{x,y} \cdot N_a(x) \cdot N_b(y)
               \right)
               + N_{a,b}^{open} \cdot p^{open} + N_{a,b}^{ext} \cdot p^{ext}
-    
+
     :math:`D_{a,b}` - The distance between the sequences *a* and *b*.
 
     :math:`S_{a,b}` - The similarity score between the sequences *a* and *b*.
@@ -164,17 +164,17 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
 
     In rare cases of extremely unrelated sequences, :math:`S_{a,b}`
     can be lower than :math:`S_{a,b}^{rand}`.
-    In this case the logaritmus cannot be calculated and a
+    In this case the logarithm cannot be calculated and a
     :class:`ValueError` is raised.
 
     References
     ----------
-    
+
     .. footbibliography::
 
     Examples
     --------
-    
+
     >>> seq1 = ProteinSequence("BIQTITE")
     >>> seq2 = ProteinSequence("TITANITE")
     >>> seq3 = ProteinSequence("BISMITE")
@@ -232,11 +232,11 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
     else:
         # Assure that every node in the guide tree is binary
         guide_tree = as_binary(guide_tree)
-    
+
     # Create new matrix with neutral gap symbol
     gap_symbol = GapSymbol.instance()
     new_alphabet = Alphabet(
-        matrix.get_alphabet1().get_symbols() + [gap_symbol]
+        matrix.get_alphabet1().get_symbols() + (gap_symbol,)
     )
     new_score_matrix = np.zeros(
         (len(new_alphabet), len(new_alphabet)), dtype=np.int32
@@ -275,7 +275,7 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
     ]
     for i in range(len(aligned_seqs)):
         aligned_seqs[i].code = aligned_seq_codes[i]
-    
+
     # Reorder alignmets into original alignemnt
     new_order = np.argsort(order)
     aligned_seqs = [aligned_seqs[pos] for pos in new_order]
@@ -290,7 +290,7 @@ def _get_distance_matrix(CodeType[:] _T, sequences, matrix,
     Create all pairwise alignments for the given sequences and use the
     method proposed by Feng & Doolittle to calculate the pairwise
     distance matrix
-    
+
     Parameters
     ----------
     _T : ndarray, dtype=VARAIBLE
@@ -306,7 +306,7 @@ def _get_distance_matrix(CodeType[:] _T, sequences, matrix,
     terminal_penalty : bool
         Whether to or not count terminal gap penalties for the
         alignments.
-    
+
     Returns
     -------
     distances : ndarray, shape=(n,n), dtype=float32
@@ -332,7 +332,7 @@ def _get_distance_matrix(CodeType[:] _T, sequences, matrix,
             )[0]
             scores[i,j] = alignment.score
             alignments[i,j] = alignment
-    
+
     ### Distance calculation from similarity scores ###
     # Calculate the occurences of each symbol code in each sequence
     # This is used later for the random score
@@ -364,7 +364,7 @@ def _get_distance_matrix(CodeType[:] _T, sequences, matrix,
     cdef CodeType[:] seq_code1, seq_code2
     cdef CodeType code1, code2
     cdef float32 score_rand, score_max
-    
+
     # Calculate distance
     # i and j are indicating the alignment between the sequences i and j
     for i in range(scores_v.shape[0]):
@@ -405,14 +405,14 @@ def _count_gaps(int64[:,:] trace_v, bint terminal_penalty):
     """
     Count the number of gap openings and gap extensions in an alignment
     trace.
-    
+
     Parameters
     ----------
     trace_v : ndarary, shape=(n,2), dtype=int
         The alignemnt trace.
     terminal_penalty : bool
         Whether to or not count terminal gap penalties.
-    
+
     Returns
     -------
     gap_open_count, gap_ext_count: int
@@ -440,7 +440,7 @@ def _count_gaps(int64[:,:] trace_v, bint terminal_penalty):
         if start_index == -1 or stop_index == -1:
             return 0, 0
         trace_v = trace_v[start_index : stop_index]
-    
+
     if trace_v[0,0] == -1:
         gap_open_count += 1
     if trace_v[0,1] == -1:
@@ -471,7 +471,7 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
     The gaps inserted in this pairwise alignment are also inserted
     into all other sequences in the respective sub-MSA at the same
     position.
-    
+
     Parameters
     ----------
     _T : ndarray, dtype=VARAIBLE
@@ -490,13 +490,13 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
     matrix : SubstitutionMatrix
         The substitution matrix used for the alignments.
     gap_symbol_code : int
-        The symbol code for the gap symbol. 
+        The symbol code for the gap symbol.
     gap_penalty : int or tuple(int, int)
         A linear or affine gap penalty for the alignments.
     terminal_penalty : bool
         Whether to or not count terminal gap penalties for the
         alignments.
-    
+
     Returns
     -------
     order : ndarray, shape=(m,), dtype=int
@@ -515,7 +515,7 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
     cdef int32[:] indices1_v, indices2_v
     cdef np.ndarray incides1, incides2
     cdef list aligned_seqs1, aligned_seqs2
-    
+
     if tree_node.is_leaf():
         # Child node -> Cannot do an alignment
         # -> Just return the sequence corresponding to the leaf node
@@ -523,7 +523,7 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
         # when neutral gap character is inserted
         return np.array([tree_node.index], dtype=np.int32), \
                [sequences[tree_node.index].copy()]
-    
+
     else:
         # Multiple alignment of sequences corresponding to both child nodes
         child1, child2 = tree_node.children
@@ -537,7 +537,7 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
             gap_symbol_code, gap_penalty, terminal_penalty
         )
         indices2_v = incides2
-        
+
         # Find sequence pair with lowest distance
         dist_min = MAX_FLOAT
         for i in range(indices1_v.shape[0]):
@@ -554,7 +554,7 @@ def _progressive_align(CodeType[:] _T, sequences, tree_node,
             gap_penalty, terminal_penalty, max_number=1
         )[0]
         # Place neutral gap symbol for position of new gaps
-        # in both sequence groups 
+        # in both sequence groups
         for i in range(len(aligned_seqs1)):
             seq = aligned_seqs1[i]
             seq.code = _replace_gaps(
@@ -580,7 +580,7 @@ def _replace_gaps(CodeType[:] _T,
 
     The replacement is required by the progressive alignment algorithm
     to be able to align gapped sequences with each other.
-    
+
     Parameters
     ----------
     _T : ndarray, dtype=VARAIBLE
@@ -592,8 +592,8 @@ def _replace_gaps(CodeType[:] _T,
     seq_code : ndarary, shape=(n,)
         The sequence code representing the given sequence.
     gap_symbol_code : int
-        The symbol code for the gap symbol. 
-    
+        The symbol code for the gap symbol.
+
     Returns
     -------
     new_seq_code : ndarary, shape=(m,)
@@ -609,12 +609,12 @@ def _replace_gaps(CodeType[:] _T,
         partial_trace_v.shape[0], dtype=seq_code.dtype
     )
     cdef CodeType[:] new_seq_code_v = new_seq_code
-    
+
     for i in range(partial_trace_v.shape[0]):
         index = partial_trace_v[i]
         if index == -1:
             new_seq_code_v[i] = gap_symbol_code
         else:
             new_seq_code_v[i] = seq_code[index]
-    
+
     return new_seq_code