AlignmentGraph - SeqAn API Documentation

# Spec AlignmentGraph
Alignment graph type.

Extends | Graph
All Extended | Graph
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept
Defined in | <seqan/graph_align.h>
Signature | `template <typename TStringSet[, typename TCargo[, typename TSpec]]> class Graph<Alignment<TStringSet, TCargo, TSpec> >;`

## Template Parameters

`TStringSet` | The type of the StringSet containing the sequence information. Must be a DependentStringSet.
`TCargo` | The cargo type that can be attached to edges. Default: `unsigned`.
`TSpec` | The specializing type. Default: `Default`. Use `WithoutEdgeId` here to omit edge ids. NB: if edges do not store ids then external property maps do not work.

## Member Function Overview

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void assignStringSet(g, stringSet);`
  Assigns a new StringSet to an AlignmentGraph.
- `bool convertAlignment(g, component, order, compLength);, bool convertAlignment(g, matrix);`
  Converts an alignment graph into an alignment matrix.
- `TVertexDescriptor findVertex(ag, id, pos);`
  Finds a vertx given a sequence id and a position.
- `TPos fragmentBegin(ag, v);`
  Gets the begin position for this vertex descriptor in the sequence.
- `TSize fragmentLength(ag, v);`
  Gets the length of the fragment for this vertex descriptor in the sequence.
- `void getDistanceMtarix(graph, mat[, tag]);, void getDistanceMtarix(graph, mat[, kTup][, alphabet], KmerDistance);`
  Computes a pairwise distance matrix from an AlignmentGraph.
- `TPos getFirstCoveredPosition(ag, id);`
  Finds the first position in a sequence that is not assigned to a nil vertex.
- `TPos getLastCoveredPosition(ag, id);`
  Finds the last position in a sequence that is not assigned to a nil vertex.
- `getProjectedPosition(ag, seqId, pos, seqId2, pos2);`
  Projects a position of one sequence taking part in a pairwise match onto the other sequence.
- `THost getStringSet(g);`
  Gets the StringSet of an AlignmentGraph.
- `TInfix label(ag, v);`
  Get the label associated with this vertex descriptor or the sequence that is associated with a fragment.
- `TId sequenceId(ag, v);`
  Gets the sequence id that is associated with this vertex descriptor or with a sequence of a fragment.
- `THostRef stringSet(g);`
  Return reference to the StringSet of an AlignmentGraph.

### Interface Functions Inherited From Graph

- `addEdge`
- `addEdges`
- `addVertex`
- `assignEdgeMap`
- `assignVertexMap`
- `clear`
- `clearEdges`
- `clearVertices`
- `degree`
- `empty`
- `findEdge`
- `getAdjacencyMatrix`
- `getNil`
- `getVertexAdjacencyVector`
- `inDegree`
- `numEdges`
- `numVertices`
- `outDegree`
- `removeEdge`
- `removeInEdges`
- `removeOutEdges`
- `removeVertex`
- `resizeEdgeMap`
- `resizeVertexMap`
- `sourceVertex`
- `targetVertex`
- `transpose`
- `writeRecords`

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

### Interface Functions Inherited From ContainerConcept

- `writeValue`
- `write`
- `begin`
- `end`
- `length`
- `empty`
- `swap`
- `getObjectId`
- `moveValue`
- `append`
- `appendValue`
- `shrinkToFit`
- `directionIterator`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From Graph

- `Cargo`
- `EdgeDescriptor`
- `EdgeIdHandler`
- `EdgeType`
- `Size`
- `VertexIdHandler`

### Interface Metafunctions Inherited From ContainerConcept

- `DefaultGetIteratorSpec`
- `DefaultIteratorSpec`
- `Difference`
- `DirectionIterator`
- `GetValue`
- `Iterator`
- `Position`
- `Reference`
- `Size`
- `Value`

## Detailed Description

### Example

    #include <iostream>

    #include <seqan/basic.h>
    #include <seqan/stream.h>
    #include <seqan/align.h>
    #include <seqan/graph_align.h>

    using namespace seqan2;

    int main()
    {
        typedef StringSet<DnaString, Dependent<> > TStringSet;
        typedef Graph<Alignment<TStringSet, void> > TAlignmentGraph;

        // Define scorings scheme.
        //
        // In this case, affine gap costs with match = 0, mismatch = -1,
        // gapextend = -1 and gapopen = -2.
        Score<int> scoringScheme(0, -1, -1, -2);

        // Define the two sequence to be allocated.
        DnaString seq1 = "atcgaatgcgga";
        DnaString seq2 = "actcgttgca";

        // Create StringSet with these two sequences and construct an
        // AlignmentGraph for them.
        TStringSet stringSet;
        appendValue(stringSet, seq1);
        appendValue(stringSet, seq2);
        TAlignmentGraph alignmentGraph(stringSet);

        // Compute global alignment of seq1 and seq1 using Gotoh's algorithm and
        // print score and alignment graph.
        int score = globalAlignment(alignmentGraph, scoringScheme, Gotoh());
        std::cout << "Score = " << score << "\n"
                  << alignmentGraph << std::endl;
        return 0;
    }

Demo: demos/dox/graph_align/graph_align.cpp

    Score = -8
    Alignment matrix:
          0     .    :
            ATCGAATGCGGA
            |     |||  |
            ACTCGTTGC--A

## Interface Functions Detail

### `void assignStringSet(g, stringSet);`

Assigns a new StringSet to an AlignmentGraph.

#### Parameters

`g` | An AlignmentGraph.
`stringSet` | The StringSet to assign to.

#### Data Races

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

#### See Also

- getStringSet
- stringSet

### `bool convertAlignment(g, component, order, compLength); bool convertAlignment(g, matrix);`

Converts an alignment graph into an alignment matrix.

#### Parameters

`g` | AlignmentGraph to convert. An alignment graph.
`component` | Vertex to component mapping.
`order` | The order of the component graph when sorting topologically.
`compLength` | Component sizes.
`matrix` | A string that represents an alignment matrix.

#### Returns

`bool` | true iff the alignment graph is a valid alignment and false otherwise.

#### Remarks

The variant with `component` and `order` computes a topological sorting of connected components.

#### Data Races

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

### `TVertexDescriptor findVertex(ag, id, pos);`

Finds a vertx given a sequence id and a position.

#### Parameters

`ag` | The AlignmentGraph to search in.
`id` | The sequence id to search for.
`pos` | The position to search for.

#### Returns

`TVertexDescriptor` | The vertex covering the given position on the specified sequence, `getNil<TVertexDescriptor>()` if none could be found.

#### Data Races

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

### `TPos fragmentBegin(ag, v);`

Gets the begin position for this vertex descriptor in the sequence.

#### Parameters

`ag` | The AlignmentGraph to query.
`v` | The vertex descriptor of the vertex.

#### Returns

`TPos` | The begin position.

#### Data Races

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

### `TSize fragmentLength(ag, v);`

Gets the length of the fragment for this vertex descriptor in the sequence.

#### Parameters

`ag` | The AlignmentGraph to query.
`v` | The vertex descriptor of the vertex.

#### Returns

`TPos` | The fragment size.

#### Data Races

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

### `void getDistanceMtarix(graph, mat[, tag]); void getDistanceMtarix(graph, mat[, kTup][, alphabet], KmerDistance);`

Computes a pairwise distance matrix from an AlignmentGraph.

#### Parameters

`graph` | An AlignmentGraph containing the sequences and possible alignment edges.
`mat` | Pairwise distance matrix.
`kTup` | For KMerDistance, the length of the k-mers.
`alphabet` | For KMerDistance, the alphabet to use for k-mer counting (e.g. compressed alphabets).
`tag` | See DistanceCalculationTags. Default: `KMerDistance`.

#### Data Races

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

### `TPos getFirstCoveredPosition(ag, id);`

Finds the first position in a sequence that is not assigned to a nil vertex.

#### Parameters

`ag` | An AlignmentGraph.
`id` | A sequence id.

#### Returns

`TPos` | A sequence position.

#### Data Races

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

#### See Also

- getLastCoveredPosition

### `TPos getLastCoveredPosition(ag, id);`

Finds the last position in a sequence that is not assigned to a nil vertex.

#### Parameters

`ag` | An AlignmentGraph.
`id` | A sequence id.

#### Returns

`TPos` | A sequence position.

#### Data Races

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

#### See Also

- getFirstCoveredPosition

### `getProjectedPosition(ag, seqId, pos, seqId2, pos2);`

Projects a position of one sequence taking part in a pairwise match onto the other sequence.

#### Parameters

`ag` | The AlignmentGraph to query.
`seqId` | The sequenceId.
`pos` | The position to project from.
`seqId2` | The resulting id of the sequence that was projected onto.
`pos2` | The reuslting position of the sequence was was projected onto.

#### Data Races

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

### `THost getStringSet(g);`

Gets the StringSet of an AlignmentGraph.

#### Parameters

`g` | An AlignmentGraph.

#### Returns

`THost` | A const reference to the StringSet's host.

#### Data Races

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

#### See Also

- assignStringSet
- stringSet

### `TInfix label(ag, v);`

Get the label associated with this vertex descriptor or the sequence that is associated with a fragment.

#### Parameters

`ag` | The AlignmentGraph to query.
`v` | The vertex descriptor to query.

#### Returns

`TInfix` | An infix representing the sequence label.

#### Data Races

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

### `TId sequenceId(ag, v);`

Gets the sequence id that is associated with this vertex descriptor or with a sequence of a fragment.

#### Parameters

`ag` | The AlignmentGraph.
`v` | Vertex descriptor of the vertex to retrieve sequence id for.

#### Returns

`TId` | The sequence id.

#### Data Races

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

### `THostRef stringSet(g);`

Return reference to the StringSet of an AlignmentGraph.

#### Parameters

`g` | An AlignmentGraph.

#### Returns

`THost` | A reference to the StringSet's host.

#### Data Races

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

#### See Also

- assignStringSet
- getStringSet

#### Dox Sources

    /*!
     * @class AlignmentGraph
     *
     * @extends Graph
     *
     * @headerfile <seqan/graph_align.h>
     *
     * @brief Alignment graph type.
     *
     * @signature template <typename TStringSet[, typename TCargo[, typename
     *            TSpec]]> class Graph<Alignment<TStringSet, TCargo, TSpec> >;
     *
     * @tparam TStringSet The type of the @link StringSet @endlink containing the
     *                    sequence information. <b>Must be a @link
     *                    DependentStringSet @endlink.</b>
     * @tparam TCargo The cargo type that can be attached to edges. Default:
     *                <tt>unsigned</tt>.
     * @tparam TSpec The specializing type. Default: <tt>Default</tt>. Use
     *               <tt>WithoutEdgeId</tt> here to omit edge ids. NB: if edges do
     *               not store ids then external property maps do not work.
     *
     * <img src="alignmentGraph.png" tite="An alignment graph with 3 sequences." />
     *
     * @section Example
     *
     * @include demos/dox/graph_align/graph_align.cpp
     *
     * @code{.console}
     * Score = -8
     * Alignment matrix:
     *       0     .    :
     *         ATCGAATGCGGA
     *         |     |||  |
     *         ACTCGTTGC--A
     * @endcode
     *
     *
     * @fn AlignmentGraph#getDistanceMatrix
     *
     * @headerfile <seqan/graph_msa.h>
     *
     * @brief Computes a pairwise distance matrix from an @link AlignmentGraph
     *        @endlink.
     *
     * @signature void getDistanceMtarix(graph, mat[, tag]);
     * @signature void getDistanceMtarix(graph, mat[, kTup][, alphabet],
     *            KmerDistance);
     *
     * @param[in] graph An @link AlignmentGraph @endlink containing the sequences
     *                  and possible alignment edges.
     * @param[out] mat Pairwise distance matrix.
     * @param[in] kTup For KMerDistance, the length of the k-mers.
     * @param[in] alphabet For KMerDistance, the alphabet to use for k-mer counting
     *                     (e.g. compressed alphabets).
     * @param[in] tag See @link DistanceCalculationTags @endlink. Default:
     *                <tt>KMerDistance</tt>.
     *
     * @fn AlignmentGraph#assignStringSet
     *
     * @brief Assigns a new StringSet to an AlignmentGraph.
     *
     * @signature void assignStringSet(g, stringSet);
     *
     * @param[in,out] g An AlignmentGraph.
     * @param[in] stringSet The @link StringSet @endlink to assign to.
     *
     * @see AlignmentGraph#getStringSet
     * @see AlignmentGraph#stringSet
     *
     * @fn AlignmentGraph#getStringSet
     *
     * @brief Gets the StringSet of an AlignmentGraph.
     *
     * @signature THost getStringSet(g);
     *
     * @param[in,out] g An AlignmentGraph.
     *
     * @return THost A const reference to the StringSet's host.
     *
     * @see AlignmentGraph#assignStringSet
     * @see AlignmentGraph#stringSet
     *
     * @fn AlignmentGraph#stringSet
     *
     * @brief Return reference to the StringSet of an AlignmentGraph.
     *
     * @signature THostRef stringSet(g);
     *
     * @param[in,out] g An AlignmentGraph.
     *
     * @return THost A reference to the StringSet's host.
     *
     * @see AlignmentGraph#assignStringSet
     * @see AlignmentGraph#getStringSet
     *
     * @fn AlignmentGraph#label
     *
     * @brief Get the label associated with this vertex descriptor or the sequence
     *        that is associated with a fragment.
     *
     * @signature TInfix label(ag, v);
     *
     * @param[in] ag The AlignmentGraph to query.
     * @param[in] v The vertex descriptor to query.
     *
     * @return TInfix An infix representing the sequence label.
     *
     * @fn AlignmentGraph#sequenceId
     *
     * @brief Gets the sequence id that is associated with this vertex descriptor or
     *        with a sequence of a fragment.
     *
     * @signature TId sequenceId(ag, v);
     *
     * @param[in] ag The AlignmentGraph.
     * @param[in] v Vertex descriptor of the vertex to retrieve sequence id for.
     *
     * @return TId The sequence id.
     *
     * @fn AlignmentGraph#fragmentBegin
     *
     * @brief Gets the begin position for this vertex descriptor in the sequence.
     *
     * @signature TPos fragmentBegin(ag, v);
     *
     * @param[in] ag The AlignmentGraph to query.
     * @param[in] v The vertex descriptor of the vertex.
     *
     * @return TPos The begin position.
     *
     * @fn AlignmentGraph#fragmentLength
     *
     * @brief Gets the length of the fragment for this vertex descriptor in the
     *        sequence.
     *
     * @signature TSize fragmentLength(ag, v);
     *
     * @param[in] ag The AlignmentGraph to query.
     * @param[in] v The vertex descriptor of the vertex.
     *
     * @return TPos The fragment size.
     *
     * @fn AlignmentGraph#findVertex
     *
     * @brief Finds a vertx given a sequence id and a position.
     *
     * @signature TVertexDescriptor findVertex(ag, id, pos);
     *
     * @param[in] ag The AlignmentGraph to search in.
     * @param[in] id The sequence id to search for.
     * @param[in] pos The position to search for.
     *
     * @return TVertexDescriptor The vertex covering the given position on the
     *                           specified sequence,
     *                           <tt>getNil&lt;TVertexDescriptor&gt;()</tt> if none
     *                           could be found.
     *
     * @fn AlignmentGraph#getProjectedPosition
     *
     * @brief Projects a position of one sequence taking part in a pairwise match
     *        onto the other sequence.
     *
     * @signature getProjectedPosition(ag, seqId, pos, seqId2, pos2);
     *
     * @param[in] ag The @link AlignmentGraph @endlink to query.
     * @param[in] seqId The sequenceId.
     * @param[in] pos The position to project from.
     * @param[out] seqId2 The resulting id of the sequence that was projected onto.
     * @param[out] pos2 The reuslting position of the sequence was was projected
     *                  onto.
     *
     * @fn AlignmentGraph#getFirstCoveredPosition
     *
     * @brief Finds the first position in a sequence that is not assigned to a nil
     *        vertex.
     *
     * @signature TPos getFirstCoveredPosition(ag, id);
     *
     * @param[in] ag An @link AlignmentGraph @endlink.
     * @param[in] id A sequence id.
     *
     * @return TPos A sequence position.
     *
     * @see AlignmentGraph#getLastCoveredPosition
     *
     * @fn AlignmentGraph#getLastCoveredPosition
     *
     * @brief Finds the last position in a sequence that is not assigned to a nil
     *        vertex.
     *
     * @signature TPos getLastCoveredPosition(ag, id);
     *
     * @param[in] ag An @link AlignmentGraph @endlink.
     * @param[in] id A sequence id.
     *
     * @return TPos A sequence position.
     *
     * @see AlignmentGraph#getFirstCoveredPosition
     *
     * @fn AlignmentGraph#convertAlignment
     *
     * @brief Converts an alignment graph into an alignment matrix.
     *
     * @signature bool convertAlignment(g, component, order, compLength);
     * @signature bool convertAlignment(g, matrix);
     *
     * @param[in] g AlignmentGraph to convert. An alignment graph.
     * @param[out] component Vertex to component mapping.
     * @param[out] order The order of the component graph when sorting
     *                   topologically.
     * @param[out] compLength Component sizes.
     * @param[out] matrix A string that represents an alignment matrix.
     *
     * @return bool true iff the alignment graph is a valid alignment and false
     *              otherwise.
     *
     * @section Remarks
     *
     * The variant with <tt>component</tt> and <tt>order</tt> computes a topological
     * sorting of connected components.
     */