SeqAn3  3.0.2
The Modern C++ library for sequence analysis.
seqan3::sam_tag_dictionary Class Reference

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

#include <seqan3/io/alignment_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
tagThe 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>
const auto & get () const &
 Uses std::map::at() for access and throws when the key is unknown. More...
 
template<uint16_t tag>
const auto && get () const &&
 Uses std::map::at() for access and throws when the key is unknown. 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:

using seqan3::operator""_tag;
// ...
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:

using seqan3::operator""_tag;
// ...
using nm_tag_type = seqan3::sam_tag_type_t<"NM"_tag>;

which is the short cut for:

using seqan3::operator""_tag;
// ...
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:

int main()
{
using seqan3::operator""_tag;
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/range/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 = seqan3::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 << ",";
}
};
int main()
{
using seqan3::operator""_tag;
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 an std::variant at https://en.cppreference.com/w/cpp/utility/variant.

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>
const auto& seqan3::sam_tag_dictionary::get ( ) const &
inline

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

Exceptions
std::out_of_rangeif map has no key tag.

◆ get() [2/2]

template<uint16_t tag>
const auto&& seqan3::sam_tag_dictionary::get ( ) const &&
inline

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

Exceptions
std::out_of_rangeif map has no key tag.

The documentation for this class was generated from the following file:
debug_stream.hpp
Provides seqan3::debug_stream and related types.
sam_tag_dictionary.hpp
Provides the seqan3::sam_tag_dictionary class and auxiliaries.
concept.hpp
Adaptations of concepts from the standard library.
seqan3::sam_tag_type_t
typename sam_tag_type< tag_value >::type sam_tag_type_t
Short cut helper for seqan3::sam_tag_type::type.
Definition: sam_tag_dictionary.hpp:175
seqan3::sam_tag_type
The generic base class.
Definition: sam_tag_dictionary.hpp:166
seqan3::sam_tag_dictionary::get
auto & get() &
Uses std::map::operator[] for access and default initializes new keys.
Definition: sam_tag_dictionary.hpp:354
seqan3::sam_tag_dictionary
The SAM tag dictionary class that stores all optional SAM fields.
Definition: sam_tag_dictionary.hpp:324
container
The (most general) container concept as defined by the standard library.
std::visit
T visit(T... args)
std::remove_cv_t
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition: debug_stream.hpp:42
variant