biotite 0.41.2__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

@@ -236,7 +236,7 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
     # 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

biotite/sequence/align/permutation.pyx

@@ -85,7 +85,7 @@ class RandomPermutation(Permutation):
     This class uses a simple full-period *linear congruential generator*
     (LCG) to provide pseudo-randomized values:
 
-    .. math:: \text{order} = (a c_\text{k-mer} + 1) \mod 2^64.
+    .. math:: \text{order} = (a \, c_\text{k-mer} + 1) \mod 2^{64}.
 
     The factor :math:`a` is taken from :footcite:`Steele2021` to ensure
     full periodicity and good random behavior.
@@ -186,6 +186,9 @@ class FrequencyPermutation(Permutation):
         The minimum and maximum value, the permutated value
         (i.e. the return value of :meth:`permute()`)
         can take.
+    kmer_alphabet : KmerAlphabet
+        The *k-mer* alphabet that defines the range of possible *k-mers*
+        that should be permuted.
 
     Notes
     -----
@@ -226,11 +229,11 @@ class FrequencyPermutation(Permutation):
     >>> permutation = FrequencyPermutation.from_table(kmer_table)
     >>> order = permutation.permute(kmer_codes)
     >>> print(order)
-    [ 0 24 20 19 16 15 14 13 12 22 21 10 11  8  7 18  6  5  4  3 23  2  1  9
+    [ 0 22 18 19  1  2  3  4  5 23 20  6  7  8  9 21 10 11 12 13 24 14 15 16
      17]
     >>> kmer_codes = kmer_codes[np.argsort(order)]
     >>> print(["..."] + ["".join(kmer_alph.decode(c)) for c in kmer_codes[-10:]])
-    ['...', 'ba', 'ar', 'rr', 'da', 'ad', 'ac', 'ca', 'br', 'ra', 'ab']
+    ['...', 'rc', 'rd', 'rr', 'ac', 'ad', 'ca', 'da', 'ab', 'br', 'ra']
     """
 
     def __init__(self, kmer_alphabet, counts):
@@ -240,7 +243,9 @@ class FrequencyPermutation(Permutation):
                 f"but {len(counts)} counts were given"
             )
         # 'order' maps a permutation to a k-mer
-        order = np.argsort(counts)
+        # Stability is important to get the same k-mer subset selection
+        # on different architectures
+        order = np.argsort(counts, kind="stable")
         # '_permutation_table' should perform the reverse mapping
         self._permutation_table = _invert_mapping(order)
         self._kmer_alph = kmer_alphabet
@@ -259,8 +264,11 @@ class FrequencyPermutation(Permutation):
         return self._kmer_alph
 
 
+    @staticmethod
     def from_table(kmer_table):
         """
+        from_table(kmer_table)
+
         Create a :class:`FrequencyPermutation` from the *k-mer* counts
         of a :class:`KmerTable`.