localAlignment - SeqAn API Documentation

# fn() localAlignment
Computes the best pairwise local alignment using the Smith-Waterman algorithm.

Defined in | <seqan/align.h>
Signature | `TScoreVal localAlignment(align, scoringScheme, [lowerDiag, upperDiag]); TScoreVal localAlignment(gapsH, gapsV, scoringScheme, [lowerDiag, upperDiag]); TScoreVal localAlignment(fragmentString, scoringScheme, [lowerDiag, upperDiag]);`

## Parameters

`gapsH` | Horizontal gapped sequence in alignment matrix. Types: Gaps
`gapsV` | Vertical gapped sequence in alignment matrix. Types: Gaps
`align` | An Align object that stores the alignment. The number of rows must be 2 and the sequences must have already been set. `align[0]` is the horizontal one in the alignment matrix alignment, `align[1]` is the vertical one.
`fragmentString` | String of Fragment objects. The sequence with id `0` is the horizontal one, the sequence with id `1` is the vertical one.
`scoringScheme` | The scoring scheme to use for the alignment.
`lowerDiag` | Optional lower diagonal (`int`).
`upperDiag` | Optional upper diagonal (`int`).

## Return Values

`TScoreVal` | Score value of the resulting alignment (Metafunction Value of the type of `scoringScheme`).

## Detailed Description

The Waterman-Eggert algorithm (local alignment with declumping) is available through the LocalAlignmentEnumerator class.

When using Gaps and Align objects, only parts (i.e. one infix) of each sequence will be aligned. This will be presented to the user by setting the clipping begin and end position of the gaps (the rows in the case of Align objects). When using Fragment strings, these parts of the sequences will not appear in any fragment.

There exist multiple overloads for this function with two configuration dimensions.

First, you can select the type of the target storing the alignment. This can be either an Align object, two Gaps objects, or a string of Fragment objects. Align objects provide an interface to tabular alignments with the restriction of all rows having the same type. Using two Gaps objects has the advantage that you an align sequences with different types, for example DnaString and Dna5String. Using Fragment strings is useful for collecting many pairwise alignments, for example in the construction of Alignment Graphs for multiple- sequence alignments (MSA).

Second, you can optionally give a band for the alignment using `lowerDiag` and `upperDiag`. The center diagonal has index `0`, the `i`th diagonal below has index `-i`, the `i`th above has index `i`.

The examples below show some common use cases.

### Examples

Local alignment of two sequences using an Align object.

    Dna5String seqH = "CGATT";
    Dna5String seqV = "CGAAATT";

    Align<Dna5String> align;
    resize(rows(align), 2);
    assignSource(row(align, 0), seqH);
    assignSource(row(align, 0), seqV);
    Score<int, Simple> scoringScheme(2, -1, -2);

    int result = localAlignment(align, scoringScheme);

Local banded alignment of two sequences using two Gaps objects.

    Dna5String seqH = "CGATT";
    Gaps<Dna5String, ArrayGaps> gapsH(seqH);
    DnaString seqV = "CGAAATT";
    Gaps<Dna5String, AnchorGaps<> > gapsV(seqV);

    Score<int, Simple> scoringScheme(5, -3, -1, -5);

    int result = localAlignment(gapsH, gapsV, scoringScheme, -2, 2);

https://seqan.readthedocs.io/en/develop/Tutorial/Algorithms/Alignment/PairwiseSequenceAlignment.html

### References

- Smith TF, Waterman, MS: Identification of Common Molecular Subsequences. J Mol Biol 1981, 147(1):195-7.

## Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## See Also

- LocalAlignmentEnumerator
- PairwiseLocalAlignmentAlgorithms
- globalAlignment

#### Dox Sources

    /*!
     * @fn localAlignment
     *
     * @headerfile <seqan/align.h>
     *
     * @brief Computes the best pairwise local alignment using the Smith-Waterman
     *        algorithm.
     *
     * @signature TScoreVal localAlignment(align, scoringScheme, [lowerDiag,
     *            upperDiag]);
     * @signature TScoreVal localAlignment(gapsH, gapsV, scoringScheme, [lowerDiag,
     *            upperDiag]);
     * @signature TScoreVal localAlignment(fragmentString, scoringScheme,
     *            [lowerDiag, upperDiag]);
     *
     * @param[in,out] gapsH Horizontal gapped sequence in alignment matrix. Types:
     *                      @link Gaps @endlink
     * @param[in,out] gapsV Vertical gapped sequence in alignment matrix. Types:
     *                      @link Gaps @endlink
     * @param[in,out] align An @link Align @endlink object that stores the
     *                      alignment. The number of rows must be 2 and the
     *                      sequences must have already been set. <tt>align[0]</tt>
     *                      is the horizontal one in the alignment matrix alignment,
     *                      <tt>align[1]</tt> is the vertical one.
     * @param[in,out] fragmentString  String of @link Fragment @endlink objects. The
     *                               sequence with id <tt>0</tt> is the horizontal
     *                               one, the sequence with id <tt>1</tt> is the
     *                               vertical one.
     * @param[in] scoringScheme  The @link Score scoring scheme @endlink to use for
     *                          the alignment.
     * @param[in] lowerDiag Optional lower diagonal (<tt>int</tt>).
     * @param[in] upperDiag Optional upper diagonal (<tt>int</tt>).
     *
     * @return TScoreVal Score value of the resulting alignment (Metafunction @link
     *                   Score#Value @endlink of the type of
     *                   <tt>scoringScheme</tt>).
     *
     * The Waterman-Eggert algorithm (local alignment with declumping) is available
     * through the @link LocalAlignmentEnumerator @endlink class.
     *
     * When using @link Gaps @endlink and @link Align @endlink objects, only parts
     * (i.e. one infix) of each sequence will be aligned. This will be presented to
     * the user by setting the clipping begin and end position of the gaps (the rows
     * in the case of @link Align @endlink objects). When using @link Fragment
     * @endlink strings, these parts of the sequences will not appear in any
     * fragment.
     *
     * There exist multiple overloads for this function with two configuration
     * dimensions.
     *
     * First, you can select the type of the target storing the alignment. This can
     * be either an @link Align @endlink object, two @link Gaps @endlink objects, or
     * a string of @link Fragment @endlink objects. @link Align @endlink objects
     * provide an interface to tabular alignments with the restriction of all rows
     * having the same type. Using two @link Gaps @endlink objects has the advantage
     * that you an align sequences with different types, for example @link DnaString
     * @endlink and @link Dna5String @endlink. Using @link Fragment @endlink strings
     * is useful for collecting many pairwise alignments, for example in the
     * construction of @link AlignmentGraph Alignment Graphs @endlink for multiple-
     * sequence alignments (MSA).
     *
     * Second, you can optionally give a band for the alignment using
     * <tt>lowerDiag</tt> and <tt>upperDiag</tt>. The center diagonal has index
     * <tt>0</tt>, the <tt>i</tt>th diagonal below has index <tt>-i</tt>, the
     * <tt>i</tt>th above has index <tt>i</tt>.
     *
     * The examples below show some common use cases.
     *
     * @section Examples
     *
     * Local alignment of two sequences using an @link Align @endlink object.
     *
     * @code{.cpp}
     * Dna5String seqH = "CGATT";
     * Dna5String seqV = "CGAAATT";
     *
     * Align<Dna5String> align;
     * resize(rows(align), 2);
     * assignSource(row(align, 0), seqH);
     * assignSource(row(align, 0), seqV);
     * Score<int, Simple> scoringScheme(2, -1, -2);
     *
     * int result = localAlignment(align, scoringScheme);
     * @endcode
     *
     *
     * Local banded alignment of two sequences using two @link Gaps @endlink
     * objects.
     *
     * @code{.cpp}
     * Dna5String seqH = "CGATT";
     * Gaps<Dna5String, ArrayGaps> gapsH(seqH);
     * DnaString seqV = "CGAAATT";
     * Gaps<Dna5String, AnchorGaps<> > gapsV(seqV);
     *
     * Score<int, Simple> scoringScheme(5, -3, -1, -5);
     *
     * int result = localAlignment(gapsH, gapsV, scoringScheme, -2, 2);
     * @endcode
     *
     *
     * https://seqan.readthedocs.io/en/develop/Tutorial/Algorithms/Alignment/Pairwis
     * eSequenceAlignment.html
     *
     * @section References
     *
     * <ul> <li>Smith TF, Waterman, MS: Identification of Common Molecular
     * Subsequences. J Mol Biol 1981, 147(1):195-7.</li> </ul>
     *
     * @see globalAlignment
     * @see LocalAlignmentEnumerator
     * @see PairwiseLocalAlignmentAlgorithms
     */