# fn() globalAlignment
Computes the best global pairwise alignment.

Defined in | <seqan/align.h>
Signature | `TScoreVal globalAlignment(align, scoringScheme, [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]); TScoreVal globalAlignment(gapsH, gapsV, scoringScheme, [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]); TScoreVal globalAlignment(frags, strings, scoringScheme, [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]); TScoreVal globalAlignment(alignGraph, scoringScheme, [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]);`

## Parameters

`align` | The Align object to use for storing the pairwise alignment.
`gapsH` | The Gaps object for the first row (horizontal in the DP matrix).
`gapsV` | The Gaps object for the second row (vertical in the DP matrix).
`frags` | String of Fragment objects to store alignment in.
`strings` | StringSet of length two with the strings to align.
`alignGraph` | Alignment Graph for the resulting alignment. Must be initialized with two strings.
`scoringScheme` | The scoring scheme to use for the alignment. Note that the user is responsible for ensuring that the scoring scheme is compatible with `algorithmTag`.
`alignConfig` | AlignConfig instance to use for the alignment configuration.
`lowerDiag` | Optional lower diagonal (`int`).
`upperDiag` | Optional upper diagonal (`int`).
`algorithmTag` | Tag to select the alignment algorithm (see AlignmentAlgorithmTags).

## Return Values

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

## Detailed Description

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

First, you can select whether begin and end gaps are free in either sequence using `alignConfig`.

Second, you can select the type of the target storing the alignment. This can be either an Align object, two Gaps objects, a AlignmentGraph, 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. Alignment Graphs provide a graph-based representation of segment-based colinear alignments. Using Fragment strings is useful for collecting many pairwise alignments, for example in the construction of Alignment Graphs for multiple-sequence alignments (MSA).

Third, 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`.

Fourth, you can select the algorithm to use with `algorithmTag`. This can be one of NeedlemanWunsch and Gotoh. The Needleman-Wunsch algorithm supports scoring schemes with linear gap costs only while Gotoh's algorithm also allows affine gap costs.

The available alignment algorithms all have some restrictions. Gotoh's algorithm can handle arbitrary substitution and affine gap scores. Needleman-Wunsch is limited to linear gap scores. The implementation of Hirschberg's algorithm is further limited that it does not support `alignConfig` objects or banding. The implementation of the Myers-Hirschberg algorithm further limits this to only support edit distance (as scores, matches are scored with 0, mismatches are scored with -1).

The examples below show some common use cases.

### Examples

Global alignment of two sequences using an Align object and the Needleman-Wunsch algorithm.

    #include <iostream>

    #include <seqan/basic.h>
    #include <seqan/align.h>
    #include <seqan/stream.h>  // for printint strings

    using namespace seqan;

    int main()
    {
        Dna5String seqH = "CGATT";
        Dna5String seqV = "CGAAATT";

        Align<Dna5String> align;
        resize(rows(align), 2);
        assignSource(row(align, 0), seqH);
        assignSource(row(align, 1), seqV);

        Score<int, Simple> scoringScheme(2, -1, -2, -1);
        AlignConfig<> alignConfig;

        int result = globalAlignment(align, scoringScheme, alignConfig);

        std::cout << "Score: " << result << "\n";
        std::cout << "The resulting alignment is\n"
                  << align << "\n";

        return 0;
    }

Demo: demos/dox/align/global_alignment_unbanded.cpp

The output is as follows:

    Score: 8
    The resulting alignment is
          0     .
            CG--ATT
            ||  |||
            CGAAATT

Global banded alignment of two sequences using two Gaps objects and the Gotoh algorithm.

    #include <iostream>

    #include <seqan/basic.h>
    #include <seqan/align.h>
    #include <seqan/sequence.h>
    #include <seqan/stream.h>  // for printint strings

    using namespace seqan;

    int main()
    {
        Dna5String seqH = "CGATT";
        Dna5String seqV = "CGAAATT";

        Align<Dna5String> align;
        resize(rows(align), 2);
        assignSource(row(align, 0), seqH);
        assignSource(row(align, 1), seqV);

        Score<int, Simple> scoringScheme(2, -1, -2);
        AlignConfig<> alignConfig;

        int lDiag = -2;
        int uDiag = 2;

        int result = globalAlignment(align, scoringScheme, alignConfig, lDiag, uDiag);

        std::cout << "Score: " << result << "\n";
        std::cout << "The resulting alignment is\n"
                  << align << "\n";

        return 0;
    }

Demo: demos/dox/align/global_alignment_banded.cpp

The output is as follows:

    Score: 6
    The resulting alignment is
          0     .
            CG--ATT
            ||  |||
            CGAAATT

http://seqan.readthedocs.io/en/develop/Tutorial/PairwiseSequenceAlignment.html

### References

- Needleman SB, Wunsch CD: A general method applicable to the search for similarities in the amino acid sequence of two proteins. J Mol Biol 1970, 48(3): 443-53.
- Gotoh O: An improved algorithm for matching biological sequences. J Mol Biol 1982, 162(3):705-8

## Data Races

Thread safety unknown!

## See Also

- AlignmentAlgorithmTags
- globalAlignmentScore
- localAlignment

#### Dox Sources

    /*!
     * @fn globalAlignment
     *
     * @headerfile <seqan/align.h>
     *
     * @brief Computes the best global pairwise alignment.
     *
     * @signature TScoreVal globalAlignment(align, scoringScheme, [alignConfig,]
     *            [lowerDiag, upperDiag,] [algorithmTag]);
     * @signature TScoreVal globalAlignment(gapsH, gapsV, scoringScheme,
     *            [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]);
     * @signature TScoreVal globalAlignment(frags, strings, scoringScheme,
     *            [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]);
     * @signature TScoreVal globalAlignment(alignGraph, scoringScheme,
     *            [alignConfig,] [lowerDiag, upperDiag,] [algorithmTag]);
     *
     * @param[in,out] align The @link Align @endlink object to use for storing the
     *                      pairwise alignment.
     * @param[in,out] gapsH The @link Gaps @endlink object for the first row
     *                      (horizontal in the DP matrix).
     * @param[in,out] gapsV The @link Gaps @endlink object for the second row
     *                      (vertical in the DP matrix).
     * @param[in,out] frags String of @link Fragment @endlink objects to store
     *                      alignment in.
     * @param[in] strings StringSet of length two with the strings to align.
     * @param[in,out] alignGraph Alignment Graph for the resulting alignment. Must
     *                           be initialized with two strings.
     * @param[in] scoringScheme The @link Score scoring scheme @endlink to use for
     *                          the alignment. Note that the user is responsible for
     *                          ensuring that the scoring scheme is compatible with
     *                          <tt>algorithmTag</tt>.
     * @param[in] alignConfig @link AlignConfig @endlink instance to use for the
     *                        alignment configuration.
     * @param[in] lowerDiag Optional lower diagonal (<tt>int</tt>).
     * @param[in] upperDiag Optional upper diagonal (<tt>int</tt>).
     * @param[in] algorithmTag Tag to select the alignment algorithm (see @link
     *                         AlignmentAlgorithmTags @endlink).
     *
     * @return TScoreVal Score value of the resulting alignment (Metafunction: @link
     *                   Score#Value @endlink of the type of
     *                   <tt>scoringScheme</tt>).
     *
     * There exist multiple overloads for this function with four configuration
     * dimensions.
     *
     * First, you can select whether begin and end gaps are free in either sequence
     * using <tt>alignConfig</tt>.
     *
     * Second, 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, a
     * @link AlignmentGraph @endlink, 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. @link AlignmentGraph Alignment Graphs @endlink provide a
     * graph-based representation of segment-based colinear alignments. 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).
     *
     * Third, 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>.
     *
     * Fourth, you can select the algorithm to use with <tt>algorithmTag</tt>. This
     * can be one of @link AlignmentAlgorithmTags#NeedlemanWunsch @endlink and @link
     * AlignmentAlgorithmTags#Gotoh @endlink. The Needleman-Wunsch algorithm
     * supports scoring schemes with linear gap costs only while Gotoh's algorithm
     * also allows affine gap costs.
     *
     * The available alignment algorithms all have some restrictions. Gotoh's
     * algorithm can handle arbitrary substitution and affine gap scores. Needleman-
     * Wunsch is limited to linear gap scores. The implementation of Hirschberg's
     * algorithm is further limited that it does not support <tt>alignConfig</tt>
     * objects or banding. The implementation of the Myers-Hirschberg algorithm
     * further limits this to only support edit distance (as scores, matches are
     * scored with 0, mismatches are scored with -1).
     *
     * The examples below show some common use cases.
     *
     * @section Examples
     *
     * Global alignment of two sequences using an @link Align @endlink object and
     * the Needleman-Wunsch algorithm.
     *
     * @include demos/dox/align/global_alignment_unbanded.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/align/global_alignment_unbanded.cpp.stdout
     *
     * Global banded alignment of two sequences using two @link Gaps @endlink
     * objects and the Gotoh algorithm.
     *
     * @include demos/dox/align/global_alignment_banded.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/align/global_alignment_banded.cpp.stdout
     *
     * http://seqan.readthedocs.io/en/develop/Tutorial/PairwiseSequenceAlignment.htm
     * l
     *
     * @section References
     *
     * <ul> <li>Needleman SB, Wunsch CD: A general method applicable to the search
     * for similarities in the amino acid sequence of two proteins. J Mol Biol 1970,
     * 48(3): 443-53.</li> <li>Gotoh O: An improved algorithm for matching
     * biological sequences. J Mol Biol 1982, 162(3):705-8</li> </ul>
     *
     * @see localAlignment
     * @see globalAlignmentScore
     * @see AlignmentAlgorithmTags
     */