seqan3::sam_tag_dictionary Class Reference

The SAM tag dictionary class that stores all optional SAM fields. More...

#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>

Inheritance diagram for seqan3::sam_tag_dictionary:

Public Types
using	variant_type = detail::sam_tag_variant
	The variant type defining all valid SAM tag field types.

Public Member Functions
Getter function for the seqan3::sam_tag_dictionary.
Gets the value of known SAM tags by its correct type instead of the std::variant. Template Parameters tag The unique tag id of a SAM tag. Returns The value corresponding to the key tag of type seqan3::sam_tag_type<tag>::type. See the seqan3::sam_tag_dictionary detailed documentation below for an example. Attention This function is only available for tags that have an seqan3::sam_tag_type<tag>::type overload. See the type trait documentation for further details.
template<uint16_t tag>
auto &	get () &
	Uses std::map::operator[] for access and default initializes new keys.
template<uint16_t tag>
auto &&	get () &&
	Uses std::map::operator[] for access and default initializes new keys.
template<uint16_t tag>
auto const &	get () const &
	Uses std::map::at() for access and throws when the key is unknown. More...
template<uint16_t tag>
auto const &&	get () const &&
	Uses std::map::at() for access and throws when the key is unknown. More...

Related Functions
(Note that these are not member functions.)
Other literals
template<typename char_t , char_t ... s>
constexpr uint16_t	operator""_tag ()
	The SAM tag literal, such that tags can be used in constant expressions. More...

Detailed Description

The SAM tag dictionary class that stores all optional SAM fields.

SAM tags

A SAM tag consists of two letters, initialized via the string literal ""_tag, which delegates to its unique id (type uint16_t). Example:

#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>
 
using namespace seqan3::literals;
 
// ...
 
uint16_t tag_id = "NM"_tag; // tag_id = 10061

The purpose of those tags is to fill or query the seqan3::sam_tag_dictionary for a specific key (tag_id) and retrieve the corresponding value.

SAM tag types

Note that a SAM tag is always associated with a specific type. In the SAM format, the type is indicated in the second argument of the TAG:TYPE:VALUE field. For example "NM:i:3" specifies the NM tag of an integer type with value 3. In seqan3, the types for known SAM tags are pre-defined by a type trait called seqan3::sam_tag_type. You can access the type via:

#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>
 
using namespace seqan3::literals;
 
// ...
 
using nm_tag_type = seqan3::sam_tag_type_t<"NM"_tag>;

which is the short cut for:

#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>
 
using namespace seqan3::literals;
 
// ...
 
using nm_tag_type2 = seqan3::sam_tag_type<"NM"_tag>::type;

The following types are allowed by the SAM specifications:

Type	Regexp matching VALUE	Description	SeqAn Type
A	[!-~]	Printable character	char
i	[-+]?[0-9]+	Signed integer	int32_t
f	[-+]?[0-9]*.?[0-9]+([eE][-+]?[0-9]+)?	Single-precision floating number	float
Z	[ !-~]*	Printable string, including space	std::string
H	([0-9A-F][0-9A-F])*	Byte array in the Hex format	std::vector<uint8_t>
B	[cCsSiIf](,[-+]?[0-9]*.?[0-9]+([eE][-+]?[0-9]+)?)+	Integer or numeric array	std::vector<T>

For an integer or numeric array (type ‘B’), the second letter can be one of ‘cCsSiIf’, corresponding to type T = int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t and float, respectively.

Using the sam_tag_dictionary

The dictionary can be accessed via the functions seqan3::sam_tag_dictionary::get() and seqan3::sam_tag_dictionary::set(). Every time the SAM tag you wish to query for must be given as a template argument to the functions.

Example:

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>
 
int main()
{
    using namespace seqan3::literals;
 
    seqan3::sam_tag_dictionary dict{};         // initialise empty dictionary
 
    dict.get<"NM"_tag>() = 3;          // set SAM tag 'NM' to 3 (integer type)
    dict.get<"CO"_tag>() = "comment";  // set SAM tag 'CO' to "comment" (string type)
 
    auto nm = dict.get<"NM"_tag>();    // get SAM tag 'NM' (note: type is int32_t)
    auto co = dict.get<"CO"_tag>();    // get SAM tag 'CO' (note: type is std::string)
 
    seqan3::debug_stream << nm << '\n';      // will print '3'
    seqan3::debug_stream << co << '\n';      // will print "comment"
}

Attention

You can get any SAM_tag out of the dictionary, even if the tag is user defined, but note that for unknown tags the return type is an std::variant. If you want specify the return type of your custom tag, you need to overload the seqan3::sam_tag_type type trait.

Unknown Tag Example:

#include <variant> // for std::visit
 
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/sam_file/sam_tag_dictionary.hpp>
#include <seqan3/utility/container/concept.hpp> // for the seqan3::container
 
// a lambda helper function that prints every type in the std::variant<...allowed SAM tag types...>
auto print_fn = [] (auto && arg)
{
    using T = std::remove_cvref_t<decltype(arg)>; // the type T of arg.
 
    if constexpr (!seqan3::container<T>)     // If T is not a container,
    {
        seqan3::debug_stream << arg << '\n';       // just print arg directly.
    }
    else                                     // If T is a container,
    {
        for (auto const & arg_v : arg)       // print every value in arg.
            seqan3::debug_stream << arg_v << ",";
        seqan3::debug_stream << '\n';
    }
};
 
int main()
{
    using namespace seqan3::literals;
 
    seqan3::sam_tag_dictionary dict{};          // initialise empty dictionary
 
    // ! there is no get function for unknown tags !
    // dict.get<"XZ"_tag>() = 3;
    // but you can use the operator[]
    dict["XZ"_tag] = 3; // set unknown SAM tag 'XZ' to 3 (type int32_t)
 
    // ! there is no get function for unknown tags !
    // auto nm = dict.get<"XZ"_tag>();
    // but you can use the operator[] again
    auto xz = dict["XZ"_tag]; // get SAM tag 'XZ' (type std::variant<...allowed SAM tag types...>)
 
    // ! you cannot print a std::variant directly !
    // seqan3::debug_stream << nm << '\n';
    // but you can use visit:
    std::visit(print_fn, xz); // prints 3
}

As mentioned before you can either overload the type trait seqan3::sam_tag_type for the tag "XZ" or learn more about a std::variant at https://en.cppreference.com/w/cpp/utility/variant.

Remarks

For a complete overview, take a look at SAM File

See also

seqan3::sam_tag_type

https://en.cppreference.com/w/cpp/utility/variant

https://samtools.github.io/hts-specs/SAMv1.pdf

https://samtools.github.io/hts-specs/SAMtags.pdf

Member Function Documentation

get() [1/2]

template<uint16_t tag>

auto const & seqan3::sam_tag_dictionary::get ( ) const &

inline

Uses std::map::at() for access and throws when the key is unknown.

Exceptions

std::out_of_range

if map has no key tag.

get() [2/2]

template<uint16_t tag>

auto const && seqan3::sam_tag_dictionary::get ( ) const &&

inline

Uses std::map::at() for access and throws when the key is unknown.

Exceptions

std::out_of_range

if map has no key tag.

---

The documentation for this class was generated from the following file:

• seqan3/io/sam_file/sam_tag_dictionary.hpp