biotite 0.41.1__cp312-cp312-macosx_10_16_x86_64.whl

biotite/sequence/align/localungapped.pyx

@@ -0,0 +1,279 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.sequence.align"
+__author__ = "Patrick Kunzmann"
+__all__ = ["align_local_ungapped"]
+
+cimport cython
+cimport numpy as np
+
+import numpy as np
+from .alignment import Alignment
+
+
+ctypedef np.int32_t int32
+ctypedef np.int64_t int64
+ctypedef np.uint8_t uint8
+ctypedef np.uint16_t uint16
+ctypedef np.uint32_t uint32
+ctypedef np.uint64_t uint64
+
+ctypedef fused CodeType1:
+    uint8
+    uint16
+    uint32
+    uint64
+ctypedef fused CodeType2:
+    uint8
+    uint16
+    uint32
+    uint64
+
+
+def align_local_ungapped(seq1, seq2, matrix, seed, int32 threshold,
+                         str direction="both", bint score_only=False,
+                         bint check_matrix=True):
+    """
+    align_local_ungapped(seq1, seq2, matrix, seed, threshold,
+                         direction="both", score_only=False, check_matrix=True)
+    
+    Perform a local alignment extending from given `seed` position
+    without inserting gaps.
+
+    The alignment extends into one or both directions (controlled by
+    `direction`) until the total alignment score falls more than
+    `threshold` below the maximum score found (*X-Drop*).
+    The returned alignment contains the range that yielded the maximum
+    score.
+    
+    Parameters
+    ----------
+    seq1, seq2 : Sequence
+        The sequences to be aligned.
+        The sequences do not need to have the same alphabets, as long as
+        the two alphabets of `matrix` extend the alphabets of the two
+        sequences.
+    matrix : SubstitutionMatrix
+        The substitution matrix used for scoring.
+    seed : tuple(int, int)
+        The indices in `seq1` and `seq2` where the local alignment
+        starts.
+        The indices must be non-negative.
+    threshold : int
+        If the current score falls this value below the maximum score
+        found, the alignment terminates.
+    direction : {'both', 'upstream', 'downstream'}, optional
+        Controls in which direction the alignment extends starting
+        from the seed.
+        If ``'upstream'``, the alignment starts before the `seed` and
+        ends at the `seed`.
+        If ``'downstream'``, the alignment starts at the `seed` and
+        ends behind the `seed`.
+        If ``'both'`` (default) the alignment starts before the `seed`
+        and ends behind the `seed`.
+        The `seed` position itself is always included in the alignment.
+    score_only : bool, optional
+        If set to ``True``, only the similarity score is returned
+        instead of the :class:`Alignment`, decreasing the runtime
+        substantially.
+    check_matrix : bool, optional
+        If set to False, the `matrix` is not checked for compatibility
+        with the alphabets of the sequences.
+        Due to the small overall runtime of the function, this can increase
+        performance substantially.
+        However, unexpected results or crashes may occur, if an
+        incompatible `matrix` is given.
+
+    
+    Returns
+    -------
+    alignment : Alignment
+        The resulting ungapped alignment.
+        Only returned, if `score_only` is ``False``.
+    score : int
+        The alignment similarity score.
+        Only returned, if `score_only` is ``True``.
+    
+    See also
+    --------
+    align_gapped
+        For gapped local alignments with the same *X-Drop* technique.
+    
+    Examples
+    --------
+
+    >>> seq1 = ProteinSequence("BIQTITE")
+    >>> seq2 = ProteinSequence("PYRRHQTITE")
+    >>> matrix = SubstitutionMatrix.std_protein_matrix()
+    >>> alignment = align_local_ungapped(seq1, seq2, matrix, seed=(4,7), threshold=10)
+    >>> print(alignment)
+    QTITE
+    QTITE
+    >>> alignment = align_local_ungapped(seq1, seq2, matrix, (4,7), 10, direction="upstream")
+    >>> print(alignment)
+    QTI
+    QTI
+    >>> alignment = align_local_ungapped(seq1, seq2, matrix, (4,7), 10, direction="downstream")
+    >>> print(alignment)
+    ITE
+    ITE
+    >>> score = align_local_ungapped(seq1, seq2, matrix, (4,7), 10, score_only=True)
+    >>> print(score)
+    24
+    """
+    if check_matrix:
+        if     not matrix.get_alphabet1().extends(seq1.get_alphabet()) \
+            or not matrix.get_alphabet2().extends(seq2.get_alphabet()):
+                raise ValueError(
+                    "The sequences' alphabets do not fit the matrix"
+                )
+    cdef const int32[:,:] score_matrix = matrix.score_matrix()
+    
+    cdef bint upstream
+    cdef bint downstream
+    if direction == "both":
+        upstream = True
+        downstream = True
+    elif direction == "upstream":
+        upstream = True
+        downstream = False
+    elif direction == "downstream":
+        upstream = False
+        downstream = True
+    else:
+        raise ValueError(f"Direction '{direction}' is invalid")
+    
+    if threshold < 0:
+        raise ValueError("The threshold value must be a non-negative integer")
+    
+    cdef int seq1_start, seq2_start
+    seq1_start, seq2_start = seed
+    if seq1_start < 0 or seq2_start < 0:
+        raise IndexError("Seed must contain positive indices")
+
+    cdef np.ndarray code1 = seq1.code
+    cdef np.ndarray code2 = seq2.code
+    # For C- function call of the '_seed_extend_uint8()' function
+    # for the common case
+    # This gives significant performance increase since the
+    # seed extend itself runs fast
+    cdef bint both_uint8 = (code1.dtype == np.uint8) \
+                         & (code2.dtype == np.uint8)
+
+    cdef int32 length
+    cdef int start_offset = 0
+    cdef int stop_offset = 1
+    cdef int32 score = 0
+    cdef int32 total_score = 0
+
+    # Separate alignment into two parts:
+    # the regions upstream and downstream from the seed position
+    # Range check to avoid negative indices
+    if upstream and seq1_start > 0 and seq2_start > 0:
+        # For the upstream region the respective part of the sequence
+        # must be reversed
+        if both_uint8:
+            length = _seed_extend_uint8(
+                code1[seq1_start-1::-1], code2[seq2_start-1::-1],
+                score_matrix, threshold, &score
+            )
+        else:
+            score, length = _seed_extend_generic(
+                code1[seq1_start-1::-1], code2[seq2_start-1::-1],
+                score_matrix, threshold
+            )
+        total_score += score
+        start_offset -= length
+    if downstream:
+        if both_uint8:
+            length = _seed_extend_uint8(
+                code1[seq1_start+1:], code2[seq2_start+1:],
+                score_matrix, threshold, &score
+            )
+        else:
+            score, length = _seed_extend_generic(
+                code1[seq1_start+1:], code2[seq2_start+1:],
+                score_matrix, threshold
+            )
+        total_score += score
+        stop_offset += length
+    total_score += score_matrix[code1[seq1_start], code2[seq2_start]]
+    
+    if score_only:
+        return total_score
+    else:
+        trace = np.stack([
+            np.arange(seq1_start + start_offset, seq1_start + stop_offset),
+            np.arange(seq2_start + start_offset, seq2_start + stop_offset)
+        ], axis=-1)
+    return Alignment([seq1, seq2], trace, total_score)
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def _seed_extend_generic(CodeType1[:] code1 not None,
+                         CodeType2[:] code2 not None,
+                         const int32[:,:] matrix not None,
+                         int32 threshold):
+    """
+    Align two sequences without insertion of gaps beginning from
+    start of the given sequences.
+    If the score drops too low, terminate the alignment.
+    Return the similarity score and the number of aligned symbols.
+    """
+    cdef int i
+    cdef int32 total_score = 0, max_score = 0
+    cdef int i_max_score = -1
+
+    # Iterate over the symbols in both sequences
+    # The alignment automatically terminates,
+    # if the the end of either sequence is reached
+    for i in range(_min(code1.shape[0], code2.shape[0])):
+        total_score += matrix[code1[i], code2[i]]
+        if total_score >= max_score:
+            max_score = total_score
+            i_max_score = i
+        elif max_score - total_score > threshold:
+            # Score drops too low -> terminate alignment
+            break
+
+    # Return the total score and the number of aligned symbols at the
+    # point with maximum total score
+    return max_score, i_max_score + 1
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef int _seed_extend_uint8(uint8[:] code1, uint8[:] code2,
+                            const int32[:,:] matrix,
+                            int32 threshold, int32* score):
+    """
+    The same functionality as :func:`_seed_extend_generic()` but as
+    C-function tailored for the common ``uint8`` sequence code *dtype*.
+    This increases the performance for this common case.
+    """
+    cdef int i
+    cdef int32 total_score = 0, max_score = 0
+    cdef int i_max_score = -1
+
+    # Iterate over the symbols in both sequences
+    # The alignment automatically terminates,
+    # if the the end of either sequence is reached
+    for i in range(_min(code1.shape[0], code2.shape[0])):
+        total_score += matrix[code1[i], code2[i]]
+        if total_score >= max_score:
+            max_score = total_score
+            i_max_score = i
+        elif max_score - total_score > threshold:
+            # Score drops too low -> terminate alignment
+            break
+
+    # Return the total score and the number of aligned symbols at the
+    # point with maximum total score
+    score[0] = max_score
+    return i_max_score + 1
+
+
+cdef inline int _min(int a, int b):
+    return a if a < b else b

biotite/sequence/align/matrix.py

@@ -0,0 +1,405 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__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
+
+__all__ = ["SubstitutionMatrix"]
+
+
+class SubstitutionMatrix(object):
+    """
+    A :class:`SubstitutionMatrix` is the foundation for scoring in
+    sequence alignments.
+    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
+        The first alphabet of the substitution matrix.
+    alphabet2 : Alphabet, length=n
+        The second alphabet of the substitution matrix.
+    score_matrix : ndarray, shape=(m,n) or dict or str
+        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,
+    ...                ("bar",1):42, ("bar",2):42, ("bar",3):42}
+    >>> matrix = SubstitutionMatrix(alph1, alph2, matrix_dict)
+    >>> print(matrix.score_matrix())
+    [[ 5 10 15]
+     [42 42 42]]
+    >>> print(matrix.get_score("foo", 2))
+    10
+    >>> print(matrix.get_score_by_code(0, 1))
+    10
+
+    Creating an identity substitution matrix via the score matrix:
+
+    >>> alph = NucleotideSequence.alphabet_unamb
+    >>> matrix = SubstitutionMatrix(alph, alph, np.identity(len(alph)))
+    >>> print(matrix)
+        A   C   G   T
+    A   1   0   0   0
+    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")
+    
+    def __init__(self, alphabet1, alphabet2, score_matrix):
+        self._alph1 = alphabet1
+        self._alph2 = alphabet2
+        if isinstance(score_matrix, dict):
+            self._fill_with_matrix_dict(score_matrix)
+        elif isinstance(score_matrix, np.ndarray):
+            alph_shape = (len(alphabet1), len(alphabet2))
+            if score_matrix.shape != alph_shape:
+                raise ValueError(
+                    f"Matrix has shape {score_matrix.shape}, "
+                    f"but {alph_shape} is required"
+                )
+            self._matrix = score_matrix.astype(np.int32)
+        elif isinstance(score_matrix, str):
+            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")
+        # 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)})"
+
+    def __eq__(self, item):
+        if not isinstance(item, SubstitutionMatrix):
+            return False
+        if self._alph1 != item.get_alphabet1():
+            return False
+        if self._alph2 != item.get_alphabet2():
+            return False
+        if not np.array_equal(self.score_matrix(), item.score_matrix()):
+            return False
+        return True
+
+    def __ne__(self, item):
+        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)
+        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])
+    
+    def get_alphabet1(self):
+        """
+        Get the first alphabet. 
+        
+        Returns
+        -------
+        alphabet : Alphabet
+            The first alphabet.
+        """
+        return self._alph1
+    
+    def get_alphabet2(self):
+        """
+        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
+            The symbol code indexed score matrix.
+            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
+            The transposed substitution matrix.
+        """
+        new_alph1 = self._alph2
+        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,
+        i.e. both alphabets are identical
+        and the score matrix is symmetric.
+
+        Returns
+        -------
+        is_symmetric : bool
+            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))
+    
+    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
+            The substitution / alignment score.
+        """
+        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 = " "
+        for symbol in self._alph2:
+            string += f" {symbol:>3}"
+        string += "\n"
+        for i, symbol in enumerate(self._alph1):
+            string += f"{symbol:>1}"
+            for j in range(len(self._alph2)):
+                string += f" {int(self._matrix[i,j]):>3d}"
+            string += "\n"
+        # 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
+            A dictionary representing the substitution matrix.
+        """
+        lines = [line.strip() for line in string.split("\n")]
+        lines = [line for line in lines if len(line) != 0 and line[0] != "#"]
+        symbols1 = [line.split()[0] for line in lines[1:]]
+        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]
+        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
+            A dictionary representing the substitution matrix.
+        """
+        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
+            List of matrix names in the internal database.
+        """
+        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
+            Default matrix.
+        """
+        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")
+