First steps with SeqAn

Table of Contents

• Hello World!
• API documentation
• Modules in SeqAn
• Some general notes that might help to dive into SeqAn
  • SeqAn and the STL
  • Modern C++
  • Avoid using namespace seqan3
• The next tutorials

Learning Objective:

This tutorial walks you through small SeqAn programs. It is intended to give you a short overview of what to expect in the other tutorials and how to use this documentation.

Difficulty	Easy
Duration	30 min
Prerequisite tutorials	Quick Setup (using CMake)
Recommended reading

Every page in the tutorials begins with the above table. It is recommended that you do the "prerequisite tutorials" before the current one. You should also have a look at the links provided in "recommended reading" and maybe keep them open in separate tabs/windows as reference.

These tutorials try to briefly introduce C++ features not well known. However, they do not teach programming in C++! If you know how to program in another language, but are not familiar with C++ and/or the significant changes in the language in recent years, we recommend the following resources:

• Bjarne Stroustrup: "A Tour of C++", Second Edition, 2018.

Hello World!

Most good tutorials start with an easy Hello World! program. So have a look:

#include <seqan3/core/debug_stream.hpp> // for debug_stream
 
int main()
{
    seqan3::debug_stream << "Hello World!\n";
}

Note

This is a code snippet. You will see many code snippets in our documentation. Most of them are compilable as-is, but some are only valid in their context, e.g. they depend on other code snippets given before/after the current one or other statements implied by the text. You can copy'n'paste freely from these examples, this implies no copyright-obligations (however distributing SeqAn or an application using it does, see Copyright and Citing).

You may ask why we do not use std::cout or std::cerr for console output. Actually, for the given text it does not make a difference since seqan3::debug_stream prints to std::cerr as well. However, the debug stream provides convenient output for SeqAn's types as well as widely used data structures (e.g. std::vector), which is especially helpful when you debug or develop your program (that's where the name originates from).

Assignment 1: Debug stream

Write a program that creates a std::vector of type int and initialise the vector with a few values. Then print the vector with seqan3::debug_stream. Does your program also work with std::cerr?

Solution

#include <iostream> // for std::cerr
#include <vector>   // for std::vector
 
#include <seqan3/core/debug_stream.hpp> // for debug_stream
 
int main()
{
    std::vector<int> vec{-1, 0, 1};
    seqan3::debug_stream << vec << '\n'; // => [-1,0,1]
    // std::cerr << vec << '\n';            // compiler error: no operator<< for std::vector<int>
}

The above is an assignment with solution. You will find assignments in the tutorials to practise the discussed contents. We believe that programming them will help you to memorise better and that it makes the tutorials more interesting and interactive. The solutions provide the intended use; but often there are multiple ways to solve an assignment, so don't worry too much if your solution is different from ours.

API documentation

While the tutorials provide you with a walkthrough of some of our modules, the API documentation will be the go-to reference when you start developing code with SeqAn.

Some helpful tips when browsing our documentation:

• You can search for seqan3 entities with the search bar in the top-right corner. E.g., start typing debug_str and the pop-up will suggest the debug_stream for you.
• If you don't have a specific entity you are searching for, the landing pages of each module are always a good start. E.g., the Alphabet landing page first lists all submodules (Adaptation, Aminoacid, ...) and general alphabet-related seqan3 entities, followed by a detailed description of our alphabet module. Searching for keywords on this page might point you in the right direction.
• If you know you've seen some code snippet somewhere but don't remember where, have a look at our cookbook. It is not structured and huge, but works well if you do a key word search with Ctrl+F.

We recommend you to open the API documentation in separate browser tab s.t. you can easily switch back to the tutorial.

If you have troubles or the documentation is missing some information, feel free to write to the developers of SeqAn on Github and ask your questions directly.

Modules in SeqAn

Modules structure the SeqAn library into logical units. There are, for instance,

• alphabet: seqan3::dna4 etc.
• io: read/write FASTA, SAM, ...
• alignment: compute pairwise alignments etc.
• search: search via an FM-Index etc.

and some more.

Some modules consist of submodules and the module structure is represented by the file hierarchy in the include/ directory. Whenever you use functions of a module, make sure to #include the correct header file.

Each directory in the SeqAn sources contains an all.hpp file which includes all the functionality of the respective module. For small examples and quick prototyping, you can just include these all.hpp-headers. However, for larger projects, we recommend you include only the necessary headers, because this will reduce the compile time measurably.

Assignment 2: Modules and API documentation

In your program of assignment 1, initialise a vector of seqan3::dna4 instead of int. The vector shall store the DNA string ACTG. Check the API documentation for which header you need to include. Additionally, browse the documentation for seqan3::dna4 on how to initialise a seqan3::dna4 letter.

Solution

#include <iostream> // for std::cerr
#include <vector>   // for std::vector
 
#include <seqan3/alphabet/all.hpp>             // for all alphabet-related stuff
#include <seqan3/alphabet/nucleotide/dna4.hpp> // for only dna4
#include <seqan3/core/debug_stream.hpp>        // for debug_stream
 
int main()
{
    std::vector<seqan3::dna4> vec{seqan3::assign_char_to('A', seqan3::dna4{}),
                                  seqan3::assign_char_to('C', seqan3::dna4{}),
                                  seqan3::assign_char_to('G', seqan3::dna4{}),
                                  seqan3::assign_char_to('T', seqan3::dna4{})};
    // The above is a little cumbersome because we don't allow implicit conversions between our alphabets and `char`.
    // There is a more convenient way:
    using namespace seqan3::literals; // Lets you use operator ""_dna4 among others
    auto vec2 = "ACGT"_dna4;
 
    seqan3::debug_stream << vec << '\n';  // => ACGT
    seqan3::debug_stream << vec2 << '\n'; // => ACGT
}

Some general notes that might help to dive into SeqAn

SeqAn and the STL

In contrast to the former version of SeqAn (2.x.x releases), we try to be very close to the standard and all other data structures and algorithms should work on STL data structures as well.

Analogous to the STL, SeqAn3 uses snake_case everywhere.

Modern C++

We use a lot of Modern C++ in SeqAn, so some things might look alien at first, e.g. type templates are used like ordinary types in many situations (no <>). We also always use {} to initialise objects and not () which is only used for function calls. In general, the style should be much easier for newcomers.

Avoid using namespace seqan3

In concordance with the C++ Core guidelines, we encourage you to avoid declaring using namespace seqan3;. This has the benefit of easily distinguishing between seqan3 features and standard C++ (std). The only exception are string literals, where we often use using namespace seqan3::literals; for convenience.

The next tutorials

Now that you reached the end of this first tutorial, you know how SeqAn code looks like and you are able to write some first code fragments. Let's go more into detail with the module-based tutorials!