Skip to content

Commit

Permalink
Merge pull request #2024 from rrahn/align_config/output_configuration
Browse files Browse the repository at this point in the history 
Align config/output configuration
  • Loading branch information
@rrahn
rrahn authored Aug 19, 2020
2 parents 907314c + 08fcc66 commit fc20e33
Show file tree
Hide file tree
Showing 38 changed files with 892 additions and 262 deletions.
13 changes: 10 additions & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,16 @@ Note that 3.1.0 will be the first API stable release and interfaces in this rele
([\#1873](https://github.com/seqan/seqan3/pull/1873)).
* The seqan3::align_cfg::mode configuration has been adapted. The algorithm can now be configured using one of the
pipeable configuration elements seqan3::align_cfg::method_global or seqan3::align_cfg::method_local
([\#1918](https://github.com/seqan/seqan3/pull/1918).
* The `seqan3::align_cfg::vectorise` configuration has been renamed to `seqan3::align_cfg::vectorised`.
* The `seqan3::align_cfg::scoring` configuration has been renamed to `seqan3::align_cfg::scoring_scheme`.
([\#1918](https://github.com/seqan/seqan3/pull/1918)).
* The `seqan3::align_cfg::vectorise` configuration has been renamed to `seqan3::align_cfg::vectorised`
([\#2026](https://github.com/seqan/seqan3/pull/2026)).
* The `seqan3::align_cfg::scoring` configuration has been renamed to `seqan3::align_cfg::scoring_scheme`
([\#2027](https://github.com/seqan/seqan3/pull/2027)).
* The `seqan3::align_cfg::result` configuration has been replaced by
[`seqan3::align_cfg::output_*` options](http://docs.seqan.de/seqan/3.0.2/group__alignment.html).
The default behaviour when not specifying any output configuration has changed from computing only the score to
computing everything. Please read the linked documentation above carefully to understand all implied changes
([\#2024](https://github.com/seqan/seqan3/pull/2024)).

### Core

Expand Down
12 changes: 6 additions & 6 deletions doc/tutorial/pairwise_alignment/configurations.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@
#include <seqan3/alignment/scoring/gap_scheme.hpp>
//! [include_gap_scheme]

//! [include_result]
#include <seqan3/alignment/configuration/align_config_result.hpp>
//! [include_result]
//! [include_output]
#include <seqan3/alignment/configuration/align_config_output.hpp>
//! [include_output]

//! [include_band]
#include <seqan3/alignment/configuration/align_config_band.hpp>
Expand Down Expand Up @@ -79,11 +79,11 @@ auto gap_open = g.get_gap_open_score(); // gap_open == -10
}

{
//! [result]
//! [output]

// Configure the alignment to only compute the score.
auto cfg = seqan3::align_cfg::result{seqan3::with_score};
//! [result]
auto cfg = seqan3::align_cfg::output_score;
//! [output]
(void) cfg;
}

Expand Down
33 changes: 20 additions & 13 deletions doc/tutorial/pairwise_alignment/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ seqan3::align_cfg::method_global.
It would be wrong for us to assume what the intended default behaviour should be.

The global alignment can be further refined by setting the seqan3::align_cfg::aligned_ends option.
The seqan3::align_cfg::aligned_ends class specifies wether or not gaps at the end of the sequences are penalised.
The seqan3::align_cfg::aligned_ends class specifies whether or not gaps at the end of the sequences are penalised.
In SeqAn you can configure this behaviour for every end (front and back of the first sequence and second sequence)
separately using the seqan3::end_gaps class.
This class is constructed with up to 4 end gap specifiers (one for every end):
Expand Down Expand Up @@ -226,27 +226,34 @@ the assignment. Et voilà, we have computed a pairwise alignment over aminoacid

## Alignment result

So far we have only computed the score, but obviously in many situations the final alignment is required, e.g. when
So far we have only used the score, but obviously in many situations the final alignment is required, e.g. when
mapping reads and the user wishes to write the alignment to the final SAM/BAM file.
In SeqAn you can simply configure what is going to be computed by the alignment algorithm using the
seqan3::align_cfg::result configuration.
different \ref seqan3_align_cfg_output_configurations "output configurations".

\snippet doc/tutorial/pairwise_alignment/configurations.cpp include_result
\snippet doc/tutorial/pairwise_alignment/configurations.cpp result
\snippet doc/tutorial/pairwise_alignment/configurations.cpp include_output
\snippet doc/tutorial/pairwise_alignment/configurations.cpp output

Accordingly, the alignment algorithm is configured to use the best implementation to obtain the desired result.
The following table shows the different outcomes that can be configured:

| Entity | Available result |
| -------------------------------------------------------------------------------------|------------------------------------------------------ |
| \ref seqan3::align_cfg::result::with_score "seqan3::with_score" | alignment score |
| \ref seqan3::align_cfg::result::with_end_positions "seqan3::with_end_positions" | alignment score; back coordinate |
| \ref seqan3::align_cfg::result::with_begin_positions "seqan3::with_begin_positions" | alignment score; back and front coordinate |
| \ref seqan3::align_cfg::result::with_alignment "seqan3::with_alignment" | alignment score; back and front coordinate; alignment |
| **Output option** | **Available result** |
| -----------------------------------------------------------------------------------------|------------------------------------------|
| \ref seqan3::align_cfg::output_score "seqan3::align_cfg::output_score" | alignment score |
| \ref seqan3::align_cfg::output_end_position "seqan3::align_cfg::output_end_position" | end positions of the aligned sequences |
| \ref seqan3::align_cfg::output_begin_position "seqan3::align_cfg::output_begin_position" | begin positions of the aligned sequences |
| \ref seqan3::align_cfg::output_alignment "seqan3::align_cfg::output_alignment" | alignment of the two sequences |
| \ref seqan3::align_cfg::output_sequence1_id "seqan3::align_cfg::output_sequence1_id" | id of the first sequence |
| \ref seqan3::align_cfg::output_sequence2_id "seqan3::align_cfg::output_sequence2_id" | id of the second sequence |

The final result is returned as a seqan3::alignment_result object. This object offers special member functions to access
the stored values. If you try to access a value, e.g. the alignment, although you didn't specify `with_alignment` in
the result configuration, a static assertion will be triggered during compilation.
the stored values. If you try to access a value, e.g. the alignment, although you didn't specify
seqan3::align_cfg::output_alignment in the result configuration, a static assertion will be triggered during
compilation.

\note If you don't specify any of the above mentioned output configurations then by default all options are enabled and
will be computed. In order to potentially increase the performance of the alignment algorithm only enable those
options that are needed for your use case.

\assignment{Assignment 4}
Compute the overlap alignment of the following two sequences. Use a linear gap scheme with a gap score of `-4` and
Expand Down
10 changes: 8 additions & 2 deletions doc/tutorial/pairwise_alignment/pairwise_alignment_solution_4.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,19 @@ int main()
auto seq1 = "TTACGTACGGACTAGCTACAACATTACGGACTAC"_dna4;
auto seq2 = "GGACGACATGACGTACGACTTTACGTACGACTAGC"_dna4;

// Configure the alignment kernel.
// Configure the output:
auto output_config = seqan3::align_cfg::output_score |
seqan3::align_cfg::output_begin_position |
seqan3::align_cfg::output_end_position |
seqan3::align_cfg::output_alignment;

// Configure the alignment kernel with the output.
auto config = seqan3::align_cfg::method_global{} |
seqan3::align_cfg::scoring_scheme{seqan3::nucleotide_scoring_scheme{
seqan3::match_score{4}, seqan3::mismatch_score{-2}}} |
seqan3::align_cfg::gap{seqan3::gap_scheme{seqan3::gap_score{-4}}} |
seqan3::align_cfg::aligned_ends{seqan3::free_ends_all} |
seqan3::align_cfg::result{seqan3::with_alignment};
output_config;

for (auto const & res : seqan3::align_pairwise(std::tie(seq1, seq2), config))
{
Expand Down
8 changes: 7 additions & 1 deletion doc/tutorial/pairwise_alignment/pairwise_alignment_solution_5.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,19 @@ int main()
auto seq1 = "TTACGTACGGACTAGCTACAACATTACGGACTAC"_dna4;
auto seq2 = "GGACGACATGACGTACGACTTTACGTACGACTAGC"_dna4;

// Configure the output:
auto output_config = seqan3::align_cfg::output_score |
seqan3::align_cfg::output_begin_position |
seqan3::align_cfg::output_end_position |
seqan3::align_cfg::output_alignment;

// Configure the alignment kernel.
auto config = seqan3::align_cfg::method_global{} |
seqan3::align_cfg::scoring_scheme{seqan3::nucleotide_scoring_scheme{
seqan3::match_score{4}, seqan3::mismatch_score{-2}}} |
seqan3::align_cfg::gap{seqan3::gap_scheme{seqan3::gap_score{-4}}} |
seqan3::align_cfg::aligned_ends{seqan3::free_ends_all} |
seqan3::align_cfg::result{seqan3::with_alignment} |
output_config |
seqan3::align_cfg::band_fixed_size{seqan3::align_cfg::lower_diagonal{-3},
seqan3::align_cfg::upper_diagonal{8}};

Expand Down
2 changes: 1 addition & 1 deletion doc/tutorial/pairwise_alignment/pairwise_alignment_solution_6.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ int main()
auto config = seqan3::align_cfg::method_global{} |
seqan3::align_cfg::edit_scheme |
seqan3::align_cfg::max_error{7u} |
seqan3::align_cfg::result{seqan3::with_score};
seqan3::align_cfg::output_score;

auto filter_v = std::views::filter([](auto && res) { return res.score() >= -6;});

Expand Down
Loading

0 comments on commit fc20e33

Please sign in to comment.