# fn() extendAlignment
X-Drop extension for alignment objects.

Defined in | <seqan/align_extend.h>
Signature | `TScoreValue extendAlignment(align, [origScore,] hSeq, vSeq, positions, extensionDirection, [lowerDiag, upperDiag,] [xDrop,] scoreScheme);`

## Parameters

`align` | The Align object to work on. Must be an alignment over the infix of the const type of `hSeq` and `vSeq`. Also see section "Returned Alignment".
`origScore` | Original score value of the alignment (optional; computed if not provided).
`hSeq` | Full horizontal sequence.
`vSeq` | Full vertical sequence.
`positions` | A Tuple of length 4 with the begin and end position of the infixes in align.
`extensionDirection` | The extension direction (ExtensionDirection).
`lowerDiag` | Lower alignment diagonal to use (`int`).
`upperDiag` | Upper alignment diagonal to use (`int`).
`xDrop` | The X-drop value to use (integral value). It only limits computation of new columns in the DP-Matrix and has no influence on the diagonals (but can be combined with them).
`scoringScheme` | The Score to use.

## Return Values

`TScoreValue` | The score of the new alignment. `TScoreValue` is the value type of `scoringScheme`.

## Detailed Description

### Returned Alignment

The resulting alignment has the infixes extended to the whole underlying sequence. The alignment is clipped to give the parts of the aligned sequences.

### Example

    #include <iostream>

    #include <seqan/align.h>
    #include <seqan/align_extend.h>
    #include <seqan/sequence.h>

    using namespace seqan;

    int main()
    {
        Score<int> sc(2, -1, -2);

        Align<Infix<CharString const>::Type> align;
        resize(rows(align), 2);

        // We create the following initial situation with subject/query and the
        // infixes thereof.
        //
        //                         infixes/seeds
        //                             <-->
        // subject  NNNNNNNNNNTTCCGGGACGGTACACACACGGGGGGGGGG
        // query               CTCGGGACGGTACAGGCACGGTTTTTTTT
        CharString subject = "NNNNNNNNNNTTCCGGGACGGTACACACACGGGGGGGGGG";
        CharString query   = "CTCGGGACGGTACAGGCACGGTTTTTTTT";
        assignSource(row(align, 0), infix(subject, 19, 23));
        assignSource(row(align, 1), infix(query, 8, 12));
        int score = globalAlignment(align, sc);

        std::cout << "Initial alignment of infixes (score == " << score << ")\n\n"
                  << align;

        // The alignment starts at diagonal (23 - 19) = 4.  A band of 4 in each direction has
        // the following diagonals.
        int lDiag = 0, uDiag = 8;
        // Set the x-Drop value to 5.
        int xDrop = 5;
        Tuple<unsigned, 4> positions = { {19u, 8u, 23u, 12u} };
        score = extendAlignment(align, score, subject, query, positions, EXTEND_BOTH,
                                lDiag, uDiag, xDrop, sc);

        std::cout << "Resulting alignment (score == " << score << ")\n\n"
                  << align;

        std::cout << "source(row(align, 0)) == " << source(row(align, 0)) << " (full sequence)\n"
                  << "source(row(align, 1)) == " << source(row(align, 1)) << " (full sequence)\n"
                  << "\n"
                  << "clipping positions of row 0: " << clippedBeginPosition(row(align, 0))
                  << ", " << clippedEndPosition(row(align, 0)) << "\n"
                  << "clipping positions of row 1: " << clippedBeginPosition(row(align, 1))
                  << ", " << clippedEndPosition(row(align, 1)) << "\n";

        return 0;
    }

Demo: demos/dox/align_extend/extend_alignment.cpp

The output is as follows:

    Initial alignment of infixes (score == 8)

          0
            GGTA
            ||||
            GGTA

    Resulting alignment (score == 32)

          0     .    :    .
            CGGGACGGTACACACACGG
            ||||||||||||  |||||
            CGGGACGGTACAGGCACGG

    source(row(align, 0)) == NNNNNNNNNNTTCCGGGACGGTACACACACGGGGGGGGGG (full sequence)
    source(row(align, 1)) == CTCGGGACGGTACAGGCACGGTTTTTTTT (full sequence)

    clipping positions of row 0: 13, 32
    clipping positions of row 1: 2, 21

### Remarks

It is necessary to explicitly pass hSeq, vSeq and the positions, because the original hSeq and vSeq (that Align was created on), might have been infixes, (especially if they are members of a ConcatDirect set) in which cases their actual begin and end positions cannot be inferred from the Align object's rows' source().

## Data Races

Thread safety unknown!

#### Dox Sources

    /*!
     * @fn extendAlignment
     *
     * @headerfile <seqan/align_extend.h>
     *
     * @brief X-Drop extension for alignment objects.
     *
     * @signature TScoreValue extendAlignment(align, [origScore,] hSeq, vSeq,
     *            positions, extensionDirection, [lowerDiag, upperDiag,] [xDrop,]
     *            scoreScheme);
     *
     * @param[in,out] align The @link Align @endlink object to work on. Must be an
     *                      alignment over the @link InfixSegment infix @endlink of
     *                      the <i>const</i> type of <tt>hSeq</tt> and
     *                      <tt>vSeq</tt>. Also see section "Returned Alignment".
     * @param[in] origScore Original score value of the alignment (optional;
     *                      computed if not provided).
     * @param[in] hSeq Full horizontal sequence.
     * @param[in] vSeq Full vertical sequence.
     * @param[in] positions A @link Tuple @endlink of length 4 with the begin and
     *                      end position of the infixes in align.
     * @param[in] extensionDirection  The extension direction (@link
     *                               ExtensionDirection @endlink).
     * @param[in] lowerDiag Lower alignment diagonal to use (<tt>int</tt>).
     * @param[in] upperDiag Upper alignment diagonal to use (<tt>int</tt>).
     * @param[in] xDrop The X-drop value to use (integral value). It only limits
     *                  computation of new columns in the DP-Matrix and has no
     *                  influence on the diagonals (but can be combined with them).
     * @param[in] scoringScheme  The @link Score @endlink to use.
     *
     * @return TScoreValue The score of the new alignment. <tt>TScoreValue</tt> is
     *                     the value type of <tt>scoringScheme</tt>.
     *
     * @section Returned Alignment
     *
     * The resulting alignment has the infixes extended to the whole underlying
     * sequence. The alignment is clipped to give the parts of the aligned
     * sequences.
     *
     * @section Example
     *
     * @include demos/dox/align_extend/extend_alignment.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/align_extend/extend_alignment.cpp.stdout
     *
     * @section Remarks
     *
     * It is necessary to explicitly pass hSeq, vSeq and the positions, because the
     * original hSeq and vSeq (that Align was created on), might have been infixes,
     * (especially if they are members of a ConcatDirect set) in which cases their
     * actual begin and end positions cannot be inferred from the Align object's
     * rows' source().
     */