Class Gaps
Store the gapped version of a sequence.

Implements ContainerConcept
All Subcl's AnchorGaps, ArrayGaps
All Impl'd AssignableConcept, ContainerConcept, DestructibleConcept
Defined in <seqan/align.h>
Signature template <typename TSequence, typename TSpec> class Gaps;

Template Parameters

TSequence The type of the underlying sequence.
TSpec Tag for specialization.

Member Function Overview

Member Functions Inherited From AssignableConcept

Interface Function Overview

Interface Functions Inherited From AssignableConcept

Interface Functions Inherited From ContainerConcept

Interface Metafunction Overview

Interface Metafunctions Inherited From ContainerConcept

Detailed Description

Gaps wrap a Sequence and allows one to (1) insert gaps into the sequence and (2) select an infix of the gapped sequence (clipping). The gaps are not inserted into the underlying sequence (source) but stored separately. Using the clipping is optional and meant for selecting parts of the alignment as a part of the result of a local alignment algorithm.

In the figure above, the source sequence has seven characters, the gapped sequence has four gaps and thus consists of eleven characters. The gapped sequence is clipped to start at position 0 in the gapped sequence and to end at position 8 in the gapped sequence (the positions given as half-open intervals [begin, end)).

The figure shows the three coordinate systems that are used with Gaps objects. The source position is the position in the underlying sequence. The unclipped view position is the position in the gapped sequence without gaps. The view position is the position in the gapped sequence but including the clipping: All (clipped) view positions have the clipping begin position subtracted from them.

Examples

The following example shows the construction of the gaps object from the image above together with some calls to toViewPosition and toSourcePosition.

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

using namespace seqan;

int main()
{
    Dna5String seq = "CGGTATC";

    // Construct the gaps object.
    Gaps<Dna5String> gaps(seq);

    // Insert gaps (view position, unclipped as of yet).  Note that inserting
    // the gaps changes the coordinates.
    insertGap(gaps, 3);
    insertGap(gaps, 5);
    insertGaps(gaps, 7, 2);

    // Clip the gaps object.  Note that the coordinates are in unclipped view position.
    setClippedBeginPosition(gaps, 1);
    setClippedEndPosition(gaps, 8);

    // Print the resulting gaps object and some coordinate transformation.
    std::cout << "Resulting gaps: " << gaps << "\n"
              << "toSourcePosition(gaps, 0) == " << toSourcePosition(gaps, 0) << "\n"
              << "toSourcePosition(gaps, 4) == " << toSourcePosition(gaps, 4) << "\n"
              << "toViewPosition(gaps, 0) == " << toViewPosition(gaps, 0) << "\n"
              << "toViewPosition(gaps, 5) == " << toViewPosition(gaps, 6) << "\n";

    return 0;
}

The output is as follows:

Resulting gaps: GG-T-A-
toSourcePosition(gaps, 0) == 1
toSourcePosition(gaps, 4) == 4
toViewPosition(gaps, 0) == -1
toViewPosition(gaps, 5) == 9

Interface Functions Detail

void assignSource(gaps, seq);

Assign the source of a gaps object, copying data.

Parameters

gaps The Gaps object to assign the source of.
seq The sequence to assign to the underlying string.

Data Races

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

TPos beginPosition(gaps);

Return the clipping begin position as a source position.

Parameters

gaps The Gaps object to query.

Returns

TPos The clipping begin position in the source (Metafunction: Position).

Example

In the following gaps configuration, the result of beginPosition(gaps) is $1$. The clipping starts in a gap and the source position of the first non-gap character right of the clipping begin has source position 1.

clipping                   [     )
  (half-open interval)

gapped sequence:          X--XXX-XX-

source position:          0111234456
unclipped view position:  0123456789
clipped view position:     0123456

Data Races

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

void clearClipping(gaps);

Clear clipping from Gaps objects.

Parameters

gaps Object to clear clipping from.

Data Races

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

void clearGaps(gaps);

Clear gaps from Gaps objects.

Parameters

gaps Object to clear gaps from.

Data Races

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

TPos clippedBeginPosition(gaps);

Return begin position of the clipping.

Parameters

gaps The Gaps object to query.

Returns

TPos The begin position of the unclipped view (Metafunction: Position).

Example

In the following gaps configuration, the result of clippedBeginPosition(gaps) is 1.

clipping                   [     )
  (half-open interval)

gapped sequence:          X--XXX-XX-

source position:          0111234456
unclipped view position:  0123456789
clipped view position:     0123456

Data Races

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

TPos clippedEndPosition(gaps);

Return end position of the clipping.

Parameters

gaps The Gaps object to query.

Returns

TPos The end position of the unclipped view (Metafunction: Position).

Example

In the following gaps configuration, the result of clippedEndPosition(gaps) is 7.

clipping                   [     )
  (half-open interval)

gapped sequence:          X--XXX-XX-

source position:          0111234456
unclipped view position:  0123456789
clipped view position:     0123456

Data Races

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

void clipSemiGlobal(global, local);

Clip the Gaps objects to reflect a semi-global alignment.

Parameters

global The global Gaps object.
local The local Gaps object.

Leading and trailing gaps are clipped in the local Gaps object. The global Gaps object is updated accordingly.

Data Races

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

void copyClipping(dest, source);

Copy clipping information from one Gaps object to another.

Parameters

dest The destination Gaps object.
source The source Gaps object.

Data Races

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

void copyGaps(dest, source);

Copy gaps from one Gaps object to another (in the clipped view of both arguments).

Parameters

dest The destination Gaps object (appropriate clipping, no gaps).
source The source Gaps object.

The user is responsible for ensuring that the gaps are over sequences of same length and appropriate clipping.

Data Races

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

TSize countCharacters(gaps, viewPos[, dir]);

The number of characters following a position.

Parameters

gaps The Gaps object to query.
viewPos View position (including clipping and gaps) to query at.
dir A tag to specify the counting direction. One of GapDirectionTags. Defaults to RightOfViewPos.

Returns

TSize The number of non-gaps characters characters at viewPos (Metafunction: Size).

If the the direction tag is RightOfViewPos the current view position will be included in the count, and excluded when LeftOfViewPos is selected.

Data Races

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

TSize countGapExtensions(gaps);

The number of gap extensions.

Parameters

gaps The Gaps object to query.

Returns

TSize The total number of gap extensions (Metafunction: Size).

Data Races

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

TSize countGapOpens(gaps);

The number of gap openings.

Parameters

gaps The Gaps object to query.

Returns

TSize The total number of gap openings (Metafunction: Size).

Data Races

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

TSize countGaps(gaps, viewPos[, dir]);

The number of gaps following a position.

Parameters

gaps The Gaps object to query.
viewPos View position (including clipping and gaps) to query at.
dir A tag to specify the counting direction. One of GapDirectionTags. Defaults to RightOfViewPos.

Returns

TSize The number of gap characters at viewPos (Metafunction: Size).

If the the direction tag is RightOfViewPos the current view position will be included in the count, and excluded when LeftOfViewPos is selected.

Data Races

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

TSize countLeadingGaps(gaps);

The number of leading gaps.

Parameters

gaps The Gaps object to query.

Returns

TSize The number of leading gap characters (Metafunction: Size).

Data Races

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

TSize countTrailingGaps(gaps);

The number of trailing gaps.

Parameters

gaps The Gaps object to query.

Returns

TSize The number of trailing gap characters (Metafunction: Size).

Data Races

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

TPos endPosition(gaps);

Return the clipping end position as a source position.

Parameters

gaps The Gaps object to query for the end position as a source position.

Returns

TPos The end position as a source position (Metafunction: Position).

Example

In the following gaps configuration, the result of endPositioN(gaps) is 4.

clipping                   [     )
  (half-open interval)

gapped sequence:          X--XXX-XX-

source position:          0111234456
unclipped view position:  0123456789
clipped view position:     0123456

Data Races

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

void insertGap(gaps, viewPos);

Insert one gap character.

Parameters

gaps The Gaps object to insert gap into.
viewPos The view position (including clipping and gaps) to insert the gap at.

Data Races

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

void insertGaps(gaps, viewPos, count);

Insert gap characters.

Parameters

gaps The Gaps object to insert gaps into.
viewPos The view position (including clipping and gaps) to insert gaps at.
count The number of gaps to insert.

Data Races

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

bool isCharacter(gaps, viewPos);

Query positions in a Gaps object for being a character.

Parameters

gaps The Gaps object to query.
viewPos The view position (including clipping and gaps).

Returns

bool The query result.

Data Races

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

bool isGap(gaps, viewPos);

Query positions in a Gaps object for being a gap.

Parameters

gaps The Gaps object to query.
viewPos The view position (including clipping and gaps).

Returns

bool The query result.

Data Races

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

TIterator iter(gaps, viewPos[, tag]);

Return an iterator to a specific position in the current clipping.

Parameters

gaps The Gaps object to get an iterator into.
viewPos View position to get an iterator to (Metafunction: Position).
tag An optional tag for selecting the iterator type.

Returns

TIterator The resulting iterator. The type is Iterator<TGaps, TTag>::Type where TTag is the type of tag.

Data Races

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

TSize length(gaps);

Return number of gap and characters between the beginning and the end of the clipping.

Parameters

gaps The Gaps object to query for its length.

Returns

TSize The number of gaps and characters between the beginning and the end of the clipping (Metafunction: Size).

Data Races

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

TSize removeGap(gaps, viewPos);

Remove one gap from a Gaps object.

Parameters

gaps The gaps object to remove one gap character from.
viewPos The view positions to remove one gap character from.

Returns

TSize The number of gap characters removed (Metafunction: Size).

Data Races

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

TSize removeGaps(gaps, viewPos, count);

Remove gaps from a Gaps object.

Parameters

gaps The gaps object to remove gap characters from.
viewPos The view positions to remove gap characters from.
count The number of gap characters to remove.

Returns

TSize The number of gap characters removed (Metafunction: Size).

Data Races

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

void setBeginPosition(gaps, sourcePos);

Set the begin position of the clipped gapped sequence, given a source position.

Parameters

gaps The Gaps object to set the begin position in.
sourcePos Position in the underlying sequence to set clipping to.

Data Races

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

void setClippedBeginPosition(gaps, unclippedViewPos);

Set the begin position of the clipping.

Parameters

gaps The Gaps object to set the clipping begin position of.
unclippedViewPos View position (including gaps but excluding clipping) to set the clipping begin to.

Data Races

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

void setClippedEndPosition(gaps, unclippedViewPos);

Set the end position of the clipping.

Parameters

gaps The Gaps object to set the clipping end position of.
unclippedViewPos View position (including gaps but excluding clipping) to set the clipping end to.

Data Races

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

void setEndPosition(gaps, sourcePos);

Set the end position of the clipped gapped sequence, given a source position.

Parameters

gaps The Gaps object to set the end position in.
sourcePos Position in the underlying sequence to set clipping to.

Data Races

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

TSource source(gaps);

Return underlying object.

Parameters

gaps The Gaps object to return the underling sequence for.

Returns

TSource Reference to the source of the Gaps.

Data Races

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

TPos toSourcePosition(gaps, viewPos);

Conversion from view position (including gaps and clipping) to source (without gaps or clipping).

Parameters

gaps The gaps object to use for translation.
sourcePos The view position (including gaps and clipping) to translate.

Returns

TPos The resulting position in the underlying sequence (Metafunction: Position).

Data Races

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

TPos toViewPosition(gaps, sourcePos);

Conversion from source (without gaps or clipping) to view position (including gaps and clipping).

Parameters

gaps The gaps object to use for translation.
sourcePos The source position (in the underlying sequence) to translate.

Returns

TPos The resulting position in the view (Metafunction: Position).

Data Races

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

TSize unclippedLength(gaps);

Return length of the gapped sequence without clipping.

Parameters

gaps The Gaps object to query.

Returns

TSize The result (Metafunction: Size).

Data Races

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