Provides the algorithmic components for the computation of pairwise alignments. More...

Collaboration diagram for Pairwise:

Classes
class	seqan3::alignment_range< alignment_executor_type >
	An input range over the alignment results generated by the underlying alignment executor. More...

class	seqan3::alignment_result< alignment_result_traits >
	Stores the alignment results and gives access to score, alignment and the front and back coordinates. More...

Functions
template<typename sequence_t , typename alignment_config_t >
constexpr auto	seqan3::align_pairwise (sequence_t &&seq, alignment_config_t const &config)
	Computes the pairwise alignment for a pair of sequences or a range over sequence pairs. More...

Detailed Description

Provides the algorithmic components for the computation of pairwise alignments.

See also: Alignment

Function Documentation

◆ align_pairwise()

template<typename sequence_t , typename alignment_config_t >

constexpr auto seqan3::align_pairwise	(	sequence_t &&	seq,
		alignment_config_t const &	config
	)

constexpr

Computes the pairwise alignment for a pair of sequences or a range over sequence pairs.

Template Parameters

sequence_t	The type of sequence pairs (see details for more information on the type constraints).
alignment_config_t	The type of the alignment configuration; must be a seqan3::configuration.

Parameters

[in]	seq	A tuple with two sequences or a range over such tuples.
[in]	config	The object storing the alignment configuration.

Returns: A seqan3::alignment_range.

This function computes the pairwise alignment for the given sequences. During the setup phase the most efficient implementation is selected depending on the configurations stored in the given seqan3::configuration object. The configuration also holds settings for parallel or vectorised execution.

Compute a single alignment

In cases where only a single alignment is to be computed, the two sequences can be passed as a pair. The pair can be any class template that models the seqan3::tuple_like concept. The tuple elements must model std::ranges::viewable_range and std::copy_constructible. Accordingly, the following example wouldn't compile:

std::pair p{"ACGTAGC", "AGTACGACG"};

auto rng = align_pairwise(p, config);

You can use std::tie instead as shown in the example below.

Compute multiple alignments

In many cases one needs to compute multiple pairwise alignments. Accordingly, the align_pairwise interface allows to pass a range over sequence pairs. The alignment algorithm will be configured only once for all submitted alignments and then computes the alignments sequentially or in parallel depending on the given configuration. Since there is always a certain amount of initial setup involving runtime checks required, it is advisable to pass many sequence-pairs to this algorithm instead of repeatedly calling it with a single pair.

Accessing the alignment results

For each sequence pair one or more seqan3::alignment_results can be computed. The seqan3::align_pairwise function returns an seqan3::alignment_range which can be used to iterate over the alignments. If the vectorise configurations are omitted the alignments are computed on-demand when iterating over the results. In case of a parallel execution all alignments are computed at once in parallel when calling begin on the associated seqan3::alignment_range.

The following snippets demonstrate the single element and the range based interface.

#include <vector>
 
#include <seqan3/alignment/configuration/all.hpp>
#include <seqan3/alignment/pairwise/align_pairwise.hpp>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::operator""_dna4;
 
    std::vector vec{std::pair{"AGTGCTACG"_dna4, "ACGTGCGACTAG"_dna4},
                    std::pair{"AGTAGACTACG"_dna4, "ACGTACGACACG"_dna4},
                    std::pair{"AGTTACGAC"_dna4, "AGTAGCGATCG"_dna4}};
 
    // Compute the alignment of a single pair.
    for (auto const & res : seqan3::align_pairwise(std::tie(vec[0].first, vec[0].second), seqan3::align_cfg::edit))
        seqan3::debug_stream << "The score: " << res.score() << "\n";
 
    // Compute the alignment over a range of pairs.
    for (auto const & res : seqan3::align_pairwise(vec, seqan3::align_cfg::edit))
        seqan3::debug_stream << "The score: " << res.score() << "\n";
}

Exception

Strong exception guarantee.

Might throw std::bad_alloc if it fails to allocate the alignment matrix or seqan3::invalid_alignment_configuration if the configuration is invalid.

Complexity

The complexity depends on the configured algorithm. For the edit distance the following worst case over two input sequences of size $ N $ can be assumed:

Computing	Runtime	Space
score
back coordinate
front coordinate
alignment

$ w $ is the size of a machine word.

For all other algorithms that compute the standard dynamic programming algorithm the following worst case holds:

Computing	Runtime	Space
score
back coordinate
front coordinate
alignment

In the banded case the worst case is modified as follows:

Computing	Runtime	Space
score
back coordinate
front coordinate
alignment

$ k $ is the size of the band.

Thread safety

This function is re-entrant, i.e. it is always safe to call in parallel with different inputs. It is thread-safe, i.e. it is safe to call in parallel with the same input under the condition that the input sequences do not change when being iterated over.

Classes

Functions