biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/sequence/align/statistics.py

@@ -0,0 +1,264 @@
+# 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__ = ["EValueEstimator"]
+
+import numpy as np
+from biotite.sequence.align.pairwise import align_optimal
+from biotite.sequence.seqtypes import GeneralSequence
+
+
+class EValueEstimator:
+    r"""
+    This class is used to calculate *expect values* (E-values) for local
+    pairwise sequence alignments.
+
+    The E-value is a measure to quantify the significance of a found
+    homology.
+    It is the number of alignments, that would result from aligning
+    random sequences of a given length, with a score at least as high as
+    the score from an alignment of interest.
+
+    The calculation of the E-value from score and sequence lengths
+    depend on the two parameters :math:`\lambda` and :math:`K`
+    :footcite:`Altschul1996`.
+    These parameters are estimated from sampling a large number
+    of random sequence alignments in :meth:`from_samples()`
+    :footcite:`Altschul1986`, which may be time consuming.
+    If these parameters are known, the constructor can be used instead.
+
+    Based on the sampled parameters, the decadic logarithm of the
+    E-value can be quickly calculated via :meth:`log_evalue()`.
+
+    Parameters
+    ----------
+    lam : float
+        The :math:`\lambda` parameter.
+    k : float
+        The :math:`K` parameter.
+
+    Notes
+    -----
+    The calculated E-value is a rough estimation that gets more
+    accurate the more sequences are used in the sampling process.
+    Note that the accuracy for alignment of short sequences, where the
+    average length of a sampled alignment make up a significant part of
+    the complete sampled sequence :footcite:`Altschul1996`.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    Examples
+    --------
+
+    Create an alignment, whose significance should be evaluated.
+
+    >>> query = NucleotideSequence("CGACGGCGTCTACGAGTCAACATCATTC")
+    >>> hit = NucleotideSequence("GCTTTATTACGGGTTTACGAGTTCAACATCACGAAAACAA")
+    >>> matrix = SubstitutionMatrix.std_nucleotide_matrix()
+    >>> gap_penalty = (-12, -2)
+    >>> alignment = align_optimal(query, hit, matrix, gap_penalty, local=True)[0]
+    >>> print(alignment)
+    ACGGCGTCTACGAGT-CAACATCA
+    ACGG-GTTTACGAGTTCAACATCA
+    >>> print(alignment.score)
+    77
+
+    Create an estimator based on the same scoring scheme as the
+    alignment.
+    Use background symbol frequencies from the hypothetical reference
+    database.
+
+    >>> # Ensure deterministic results
+    >>> np.random.seed(0)
+    >>> # Sequences in database have a GC content of 0.6
+    >>> background = np.array([0.2, 0.3, 0.3, 0.2])
+    >>> estimator = EValueEstimator.from_samples(
+    ...     query.alphabet, matrix, gap_penalty, background, sample_length=100
+    ... )
+
+    Approach 1: Calculate E-value based on number of sequences in the
+    hypothetical database (*100*).
+
+    >>> log_e = estimator.log_evalue(alignment.score, len(query), 100 * len(hit))
+    >>> print(f"E-value = {10**log_e:.2e}")
+    E-value = 3.36e-01
+
+    Approach 2: Calculate E-value based on total length of all sequences
+    in the hypothetical database combined (*10000*).
+
+    >>> log_e = estimator.log_evalue(alignment.score, len(query), 10000)
+    >>> print(f"E-value = {10**log_e:.2e}")
+    E-value = 8.41e-01
+    """
+
+    def __init__(self, lam, k):
+        self._lam = lam
+        self._k = k
+
+    @staticmethod
+    def from_samples(
+        alphabet, matrix, gap_penalty, frequencies, sample_length=1000, sample_size=1000
+    ):
+        r"""
+        Create an :class:`EValueEstimator` with :math:`\lambda` and
+        :math:`K` estimated via sampling alignments of random sequences
+        based on a given scoring scheme.
+
+        The parameters are estimated from the sampled alignment scores
+        using the method of moments :footcite:`Altschul1986`.
+
+        Parameters
+        ----------
+        alphabet : Alphabet, length=k
+            The alphabet for the sampled sequences.
+        matrix : SubstitutionMatrix
+            The substitution matrix.
+            It must be compatible with the given `alphabet` and the
+            expected similarity score between two random symbols must be
+            negative.
+        gap_penalty : int or tuple(int,int)
+            Either a linear (``int``) or affine (``tuple``) gap penalty.
+            Integers must be negative.
+        frequencies : ndarray, shape=k, dtype=float
+            The background frequencies for each symbol in the
+            `alphabet`.
+            The random sequences are created based on these frequencies.
+        sample_length : int
+            The length of the sampled sequences.
+            It should be much larger than the average length of a local
+            alignment of two sequences.
+            The runtime scales quadratically with this parameter.
+        sample_size : int
+            The number of sampled sequences.
+            The accuracy of the estimated parameters and E-values,
+            but also the runtime increases with the sample size.
+
+        Returns
+        -------
+        estimator : EValueEstimator
+            A :class:`EValueEstimator` with sampled :math:`\lambda` and
+            :math:`K` parameters.
+
+        Notes
+        -----
+        The sampling process generates random sequences based on
+        ``numpy.random``.
+        To ensure reproducible results you could call
+        :func:`numpy.random.seed()` before running
+        :meth:`from_samples()`.
+        """
+        if len(frequencies) != len(alphabet):
+            raise IndexError(
+                f"Background frequencies for {len(frequencies)} symbols were "
+                f"given, but the alphabet has {len(alphabet)} symbols"
+            )
+        if np.any(frequencies < 0):
+            raise ValueError("Background frequencies must be positive")
+        # Normalize background frequencies
+        frequencies = frequencies / np.sum(frequencies)
+
+        # Check matrix
+        if not matrix.is_symmetric():
+            raise ValueError("A symmetric substitution matrix is required")
+        if not matrix.get_alphabet1().extends(alphabet):
+            raise ValueError(
+                "The substitution matrix is not compatible with the given alphabet"
+            )
+        score_matrix = matrix.score_matrix()[: len(alphabet), : len(alphabet)]
+        if (
+            np.sum(
+                score_matrix * frequencies[np.newaxis, :] * frequencies[:, np.newaxis]
+            )
+            >= 0
+        ):
+            raise ValueError(
+                "Invalid substitution matrix, the expected similarity "
+                "score between two random symbols is not negative"
+            )
+
+        # Generate the sequence code for the random sequences
+        random_sequence_code = np.random.choice(
+            len(alphabet), size=(sample_size, 2, sample_length), p=frequencies
+        )
+
+        # Sample the alignments of random sequences
+        sample_scores = np.zeros(sample_size, dtype=int)
+        for i in range(sample_size):
+            seq1 = GeneralSequence(alphabet)
+            seq2 = GeneralSequence(alphabet)
+            seq1.code = random_sequence_code[i, 0]
+            seq2.code = random_sequence_code[i, 1]
+            sample_scores[i] = align_optimal(
+                seq1, seq2, matrix, local=True, gap_penalty=gap_penalty, max_number=1
+            )[0].score
+
+        # Use method of moments to estimate parameters
+        lam = np.pi / np.sqrt(6 * np.var(sample_scores))
+        u = np.mean(sample_scores) - np.euler_gamma / lam
+        k = np.exp(lam * u) / sample_length**2
+
+        return EValueEstimator(lam, k)
+
+    @property
+    def lam(self):
+        return self._lam
+
+    @property
+    def k(self):
+        return self._k
+
+    def log_evalue(self, score, seq1_length, seq2_length):
+        r"""
+        Calculate the decadic logarithm of the E-value for a given
+        score.
+
+        The E-value and the logarithm of the E-value is calculated as
+
+        .. math::
+
+            E = Kmn e^{-\lambda s}
+
+            \log_{10} E = (\log_{10} Kmn) - \frac{\lambda s}{\ln 10},
+
+        where :math:`s` is the similarity score and :math:`m` and
+        :math:`n` are the lengths of the aligned sequences.
+
+        Parameters
+        ----------
+        score : int or ndarray, dtype=int
+            The score to evaluate.
+        seq1_length : int or ndarray, dtype=int
+            The length of the first sequence.
+            In the context of a homology search in a sequence database,
+            this is usually the length of the query sequence.
+        seq2_length : int or ndarray, dtype=int
+            The length of the second sequence.
+            In the context of a homology search in a sequence database,
+            this is usually either the combined length of all sequences
+            in the database or the length of the hit sequence multiplied
+            by the number of sequences in the database.
+
+        Returns
+        -------
+        log_e : float
+            The decadic logarithm of the E-value.
+
+        Notes
+        -----
+        This method returns the logarithm of the E-value instead of
+        the E-value, as low E-values indicating a highly significant
+        homology cannot be accurately represented by a ``float``.
+        """
+        score = np.asarray(score)
+        seq1_length = np.asarray(seq1_length)
+        seq2_length = np.asarray(seq2_length)
+
+        return np.log10(
+            self._k * seq1_length * seq2_length
+        ) - self._lam * score / np.log(10)

biotite/sequence/align/tracetable.pxd

@@ -0,0 +1,64 @@
+# 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.
+
+cimport cython
+cimport numpy as np
+
+
+# A trace table saves the directions a cell came from
+# A "1" in the corresponding bit in the trace table means
+# the cell came from this direction
+
+cdef enum TraceDirectionLinear:
+    # Values for linear gap penalty (one score table)
+    MATCH    = 1    # bit 1 -> diagonal -> alignment of symbols
+    GAP_LEFT = 2    # bit 2 -> left     -> gap in first sequence
+    GAP_TOP  = 4    # bit 3 -> top      -> gap in second sequence
+
+cdef enum TraceDirectionAffine:
+    # Values for affine gap penalty (three score tables)
+    MATCH_TO_MATCH       = 1    # bit 1 -> match - match transition
+    GAP_LEFT_TO_MATCH    = 2    # bit 2 -> seq 1 gap - match transition
+    GAP_TOP_TO_MATCH     = 4    # bit 3 -> seq 2 gap - match transition
+    MATCH_TO_GAP_LEFT    = 8    # bit 4 -> match - seq 1 gap transition
+    GAP_LEFT_TO_GAP_LEFT = 16   # bit 5 -> seq 1 gap - seq 1 gap transition
+    MATCH_TO_GAP_TOP     = 32   # bit 6 -> match - seq 2 gap transition
+    GAP_TOP_TO_GAP_TOP   = 64   # bit 7 -> seq 2 gap - seq 2 gap transition
+
+
+cdef enum TraceState:
+    # The state specifies the table the traceback is currently in
+    # For linear gap penalty (only one table/state exists):
+    NO_STATE = 0
+    # For affine gap penalty (three tables/states exists): 
+    MATCH_STATE    = 1
+    GAP_LEFT_STATE = 2
+    GAP_TOP_STATE  = 3
+
+
+cdef np.uint8_t get_trace_linear(np.int32_t match_score,
+                                 np.int32_t gap_left_score,
+                                 np.int32_t gap_top_score,
+                                 np.int32_t *max_score)
+
+cdef np.uint8_t get_trace_affine(np.int32_t match_to_match_score,
+                                 np.int32_t gap_left_to_match_score,
+                                 np.int32_t gap_top_to_match_score,
+                                 np.int32_t match_to_gap_left_score,
+                                 np.int32_t gap_left_to_gap_left_score,
+                                 np.int32_t match_to_gap_top_score,
+                                 np.int32_t gap_top_to_gap_top_score,
+                                 np.int32_t *max_match_score,
+                                 np.int32_t *max_gap_left_score,
+                                 np.int32_t *max_gap_top_score)
+
+cdef int follow_trace(np.uint8_t[:,:] trace_table,
+                      bint banded,
+                      int i, int j, int pos,
+                      np.int64_t[:,:] trace,
+                      list trace_list,
+                      int state,
+                      int* curr_trace_count,
+                      int max_trace_count,
+                      int lower_diag, int upper_diag) except -1

biotite/sequence/align/tracetable.pyx

@@ -0,0 +1,370 @@
+# 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.
+
+"""
+A module for Biotite's internal use only.
+Contains C-functions for handling trace tables in a reuasable way for
+different alignment functions.
+"""
+
+__name__ = "biotite.sequence.align"
+__author__ = "Patrick Kunzmann"
+__all__ = []
+
+cimport cython
+cimport numpy as np
+
+import numpy as np
+
+
+cdef inline np.uint8_t get_trace_linear(np.int32_t match_score,
+                                        np.int32_t gap_left_score,
+                                        np.int32_t gap_top_score,
+                                        np.int32_t *max_score):
+    """
+    Find maximum score from the input scores and return corresponding
+    trace direction for linear gap penalty.
+    """
+    if match_score > gap_left_score:
+        if match_score > gap_top_score:
+            trace = TraceDirectionLinear.MATCH
+            max_score[0] = match_score
+        elif match_score == gap_top_score:
+            trace = (
+                TraceDirectionLinear.MATCH |
+                TraceDirectionLinear.GAP_TOP
+            )
+            max_score[0] = match_score
+        else:
+            trace = TraceDirectionLinear.GAP_TOP
+            max_score[0] = gap_top_score
+    elif match_score == gap_left_score:
+        if match_score > gap_top_score:
+            trace = (
+                TraceDirectionLinear.MATCH |
+                TraceDirectionLinear.GAP_LEFT
+            )
+            max_score[0] = match_score
+        elif match_score == gap_top_score:
+            trace = (
+                TraceDirectionLinear.MATCH |
+                TraceDirectionLinear.GAP_LEFT |
+                TraceDirectionLinear.GAP_TOP
+            )
+            max_score[0] = match_score
+        else:
+            trace = TraceDirectionLinear.GAP_TOP
+            max_score[0] = gap_top_score
+    else:
+        if gap_left_score > gap_top_score:
+            trace = TraceDirectionLinear.GAP_LEFT
+            max_score[0] = gap_left_score
+        elif gap_left_score == gap_top_score:
+            trace = (
+                TraceDirectionLinear.GAP_LEFT |
+                TraceDirectionLinear.GAP_TOP
+            )
+            max_score[0] = gap_left_score
+        else:
+            trace = TraceDirectionLinear.GAP_TOP
+            max_score[0] = gap_top_score
+    
+    return trace
+
+
+cdef inline np.uint8_t get_trace_affine(np.int32_t match_to_match_score,
+                                        np.int32_t gap_left_to_match_score,
+                                        np.int32_t gap_top_to_match_score,
+                                        np.int32_t match_to_gap_left_score,
+                                        np.int32_t gap_left_to_gap_left_score,
+                                        np.int32_t match_to_gap_top_score,
+                                        np.int32_t gap_top_to_gap_top_score,
+                                        np.int32_t *max_match_score,
+                                        np.int32_t *max_gap_left_score,
+                                        np.int32_t *max_gap_top_score):
+    """
+    Find maximum scores from the input scores and return corresponding
+    trace direction for affine gap penalty.
+    """
+    # Match Table
+    if match_to_match_score > gap_left_to_match_score:
+        if match_to_match_score > gap_top_to_match_score:
+            trace = TraceDirectionAffine.MATCH_TO_MATCH
+            max_match_score[0] = match_to_match_score
+        elif match_to_match_score == gap_top_to_match_score:
+            trace = (
+                TraceDirectionAffine.MATCH_TO_MATCH |
+                TraceDirectionAffine.GAP_TOP_TO_MATCH
+            )
+            max_match_score[0] = match_to_match_score
+        else:
+            trace = TraceDirectionAffine.GAP_TOP_TO_MATCH
+            max_match_score[0] = gap_top_to_match_score
+    elif match_to_match_score == gap_left_to_match_score:
+        if match_to_match_score > gap_top_to_match_score:
+            trace = (
+                TraceDirectionAffine.MATCH_TO_MATCH | 
+                TraceDirectionAffine.GAP_LEFT_TO_MATCH
+            )
+            max_match_score[0] = match_to_match_score
+        elif match_to_match_score == gap_top_to_match_score:
+            trace = (
+                TraceDirectionAffine.MATCH_TO_MATCH |
+                TraceDirectionAffine.GAP_LEFT_TO_MATCH |
+                TraceDirectionAffine.GAP_TOP_TO_MATCH
+            )
+            max_match_score[0] = match_to_match_score
+        else:
+            trace = TraceDirectionAffine.GAP_TOP_TO_MATCH
+            max_match_score[0] = gap_top_to_match_score
+    else:
+        if gap_left_to_match_score > gap_top_to_match_score:
+            trace = TraceDirectionAffine.GAP_LEFT_TO_MATCH
+            max_match_score[0] = gap_left_to_match_score
+        elif gap_left_to_match_score == gap_top_to_match_score:
+            trace = (
+                TraceDirectionAffine.GAP_LEFT_TO_MATCH |
+                TraceDirectionAffine.GAP_TOP_TO_MATCH
+            )
+            max_match_score[0] = gap_left_to_match_score
+        else:
+            trace = TraceDirectionAffine.GAP_TOP_TO_MATCH
+            max_match_score[0] = gap_top_to_match_score
+    
+    # 'Gap left' table
+    if match_to_gap_left_score > gap_left_to_gap_left_score:
+        trace |= TraceDirectionAffine.MATCH_TO_GAP_LEFT
+        max_gap_left_score[0] = match_to_gap_left_score
+    elif match_to_gap_left_score < gap_left_to_gap_left_score:
+        trace |= TraceDirectionAffine.GAP_LEFT_TO_GAP_LEFT
+        max_gap_left_score[0] = gap_left_to_gap_left_score
+    else:
+        trace |= (
+            TraceDirectionAffine.MATCH_TO_GAP_LEFT |
+            TraceDirectionAffine.GAP_LEFT_TO_GAP_LEFT
+        )
+        max_gap_left_score[0] = match_to_gap_left_score
+    
+    # 'Gap right' table
+    if match_to_gap_top_score > gap_top_to_gap_top_score:
+        trace |= TraceDirectionAffine.MATCH_TO_GAP_TOP
+        max_gap_top_score[0] = match_to_gap_top_score
+    elif match_to_gap_top_score < gap_top_to_gap_top_score:
+        trace |= TraceDirectionAffine.GAP_TOP_TO_GAP_TOP
+        max_gap_top_score[0] = gap_top_to_gap_top_score
+    else:
+        trace |= (
+            TraceDirectionAffine.MATCH_TO_GAP_TOP |
+            TraceDirectionAffine.GAP_TOP_TO_GAP_TOP
+        )
+        max_gap_top_score[0] = gap_top_to_gap_top_score
+    
+    return trace
+
+
+cdef int follow_trace(np.uint8_t[:,:] trace_table,
+                      bint banded,
+                      int i, int j, int pos,
+                      np.int64_t[:,:] trace,
+                      list trace_list,
+                      int state,
+                      int* curr_trace_count,
+                      int max_trace_count,
+                      int lower_diag, int upper_diag) except -1:
+    """
+    Follow and return traces from a trace table.
+
+    Parameters
+    ----------
+    trace_table
+        A matrix containing values indicating the direction for the
+        traceback.
+    banded
+        Whether the trace table belongs to a banded alignment
+    i, j
+        The current position in the trace table.
+        For the first branch, this is the start of the traceback.
+        For additional branches this is the start of the respective
+        branch.
+    pos
+        The current position inthe trace array to be created.
+        For the first branch, this is 0.
+        For additional branches the value of the parent branch is taken.
+    trace
+        The alignment trace array to be filled.
+    trace_list
+        When a trace is finished, it is appened to this list
+    state
+        The current score table (*match*, *gap left*, *gap top*)
+        the traceback is in, taken from parent branch.
+        Always 0 when a linear gap penalty is used.
+    curr_trace_count
+        The current number of branches. The value is a pointer, so that
+        updating this value propagates the value to all other branches
+    max_trace_count
+        The maximum number of branches created. When the number of
+        branches reaches this value, no new branches are created.
+    lower_diag, upper_diag
+        The lower and upper diagonal for a banded alignment.
+        Unused, if `banded` is false.
+    
+    Returns
+    -------
+    int
+        ``0`` if, no exception is raised, otherwisw ``-1``.
+    """
+    
+    cdef list next_indices
+    cdef list next_states
+    cdef int trace_value
+    cdef int k
+    cdef int seq_i, seq_j
+    cdef int i_match, i_gap_left, i_gap_top
+    cdef int j_match, j_gap_left, j_gap_top
+    
+    if state == TraceState.NO_STATE:
+        # Linear gap penalty
+        # Trace table has a 0 -> no trace direction -> break loop
+        # The '0'-cell itself is also not included in the traceback
+        while trace_table[i,j] != 0:
+            if banded:
+                seq_i = i - 1
+                seq_j = j + seq_i + lower_diag - 1
+                i_match, i_gap_left, i_gap_top = i-1, i,   i-1
+                j_match, j_gap_left, j_gap_top = j  , j-1, j+1
+            else:
+                # -1 is necessary due to the shift of the sequences
+                # to the bottom/right in the table
+                seq_i = i - 1
+                seq_j = j - 1
+                i_match, i_gap_left, i_gap_top = i-1, i,   i-1
+                j_match, j_gap_left, j_gap_top = j-1, j-1, j
+            trace[pos, 0] = seq_i
+            trace[pos, 1] = seq_j
+            pos += 1
+            # Traces may split
+            next_indices = []
+            trace_value = trace_table[i,j]
+            if trace_value & TraceDirectionLinear.MATCH:
+                next_indices.append((i_match, j_match))
+            if trace_value & TraceDirectionLinear.GAP_LEFT:
+                next_indices.append((i_gap_left, j_gap_left))
+            if trace_value & TraceDirectionLinear.GAP_TOP:
+                next_indices.append((i_gap_top, j_gap_top))
+            # Trace branching
+            # -> Recursive call of _follow_trace() for indices[1:]
+            for k in range(1, len(next_indices)):
+                if curr_trace_count[0] < max_trace_count:
+                    curr_trace_count[0] += 1
+                    new_i, new_j = next_indices[k]
+                    follow_trace(
+                        trace_table, banded, new_i, new_j, pos,
+                        np.copy(trace), trace_list, 0,
+                        curr_trace_count, max_trace_count,
+                        lower_diag, upper_diag
+                    )
+            # Continue in this method with indices[0]
+            i, j = next_indices[0]
+    else:
+        # Affine gap penalty
+        # -> check only for the current state whether the trace ends
+        while (
+            (
+                state == TraceState.MATCH_STATE and trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_MATCH |
+                    TraceDirectionAffine.GAP_LEFT_TO_MATCH |
+                    TraceDirectionAffine.GAP_TOP_TO_MATCH
+                ) != 0
+            ) or (
+                state == TraceState.GAP_LEFT_STATE and trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_GAP_LEFT |
+                    TraceDirectionAffine.GAP_LEFT_TO_GAP_LEFT
+                ) != 0
+            ) or (
+                state == TraceState.GAP_TOP_STATE and trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_GAP_TOP |
+                    TraceDirectionAffine.GAP_TOP_TO_GAP_TOP
+                ) != 0
+            )
+        ):
+            if banded:
+                seq_i = i - 1
+                seq_j = j + seq_i + lower_diag - 1
+                i_match, i_gap_left, i_gap_top = i-1, i,   i-1
+                j_match, j_gap_left, j_gap_top = j  , j-1, j+1
+            else:
+                # -1 is necessary due to the shift of the sequences
+                # to the bottom/right in the table
+                seq_i = i - 1
+                seq_j = j - 1
+                i_match, i_gap_left, i_gap_top = i-1, i,   i-1
+                j_match, j_gap_left, j_gap_top = j-1, j-1, j
+            trace[pos, 0] = seq_i
+            trace[pos, 1] = seq_j
+            pos += 1
+            next_indices = []
+            next_states = []
+
+            # Get value of trace corresponding to current state
+            # = table trace is currently in
+            if state == TraceState.MATCH_STATE:
+                trace_value = trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_MATCH |
+                    TraceDirectionAffine.GAP_LEFT_TO_MATCH |
+                    TraceDirectionAffine.GAP_TOP_TO_MATCH
+                )
+            elif state == TraceState.GAP_LEFT_STATE:
+                trace_value = trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_GAP_LEFT |
+                    TraceDirectionAffine.GAP_LEFT_TO_GAP_LEFT
+                )
+            else: # state == TraceState.GAP_TOP_STATE:
+                trace_value = trace_table[i,j] & (
+                    TraceDirectionAffine.MATCH_TO_GAP_TOP |
+                    TraceDirectionAffine.GAP_TOP_TO_GAP_TOP
+                )
+            
+            # Determine indices and state of next trace step
+            if trace_value & TraceDirectionAffine.MATCH_TO_MATCH:
+                next_indices.append((i_match, j_match))
+                next_states.append(TraceState.MATCH_STATE)
+            if trace_value & TraceDirectionAffine.GAP_LEFT_TO_MATCH:
+                next_indices.append((i_match, j_match))
+                next_states.append(TraceState.GAP_LEFT_STATE)
+            if trace_value & TraceDirectionAffine.GAP_TOP_TO_MATCH:
+                next_indices.append((i_match, j_match))
+                next_states.append(TraceState.GAP_TOP_STATE)
+            if trace_value & TraceDirectionAffine.MATCH_TO_GAP_LEFT:
+                next_indices.append((i_gap_left, j_gap_left))
+                next_states.append(TraceState.MATCH_STATE)
+            if trace_value & TraceDirectionAffine.GAP_LEFT_TO_GAP_LEFT:
+                next_indices.append((i_gap_left, j_gap_left))
+                next_states.append(TraceState.GAP_LEFT_STATE)
+            if trace_value & TraceDirectionAffine.MATCH_TO_GAP_TOP:
+                next_indices.append((i_gap_top, j_gap_top))
+                next_states.append(TraceState.MATCH_STATE)
+            if trace_value & TraceDirectionAffine.GAP_TOP_TO_GAP_TOP:
+                next_indices.append((i_gap_top, j_gap_top))
+                next_states.append(TraceState.GAP_TOP_STATE)
+            # Trace branching
+            # -> Recursive call of _follow_trace() for indices[1:]
+            for k in range(1, len(next_indices)):
+                if curr_trace_count[0] < max_trace_count:
+                    curr_trace_count[0] += 1
+                    new_i, new_j = next_indices[k]
+                    new_state = next_states[k]
+                    follow_trace(
+                        trace_table, banded, new_i, new_j, pos,
+                        np.copy(trace), trace_list, new_state,
+                        curr_trace_count, max_trace_count,
+                        lower_diag, upper_diag
+                    )
+            # Continue in this method with indices[0] and states[0]
+            i, j = next_indices[0]
+            state = next_states[0]
+    # Trim trace to correct size (delete all pure -1 entries)
+    # and append to trace_list
+    tr_arr = np.asarray(trace)
+    trace_list.append(tr_arr[(tr_arr[:,0] != -1) | (tr_arr[:,1] != -1)])
+    return 0