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> requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)
auto &	get () &
	Uses std::map::operator[] for access and default initializes new keys.
template<uint16_t tag> requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)
auto &&	get () &&
	Uses std::map::operator[] for access and default initializes new keys.
template<uint16_t tag> requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)
auto const &	get () const &
	Uses std::map::at() for access and throws when the key is unknown.
template<uint16_t tag> requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)
auto const &&	get () const &&
	Uses std::map::at() for access and throws when the key is unknown.
Public Member Functions inherited from std::map< uint16_t, detail::sam_tag_variant >
T	at (T... args)
T	begin (T... args)
T	cbegin (T... args)
T	cend (T... args)
T	clear (T... args)
T	contains (T... args)
T	count (T... args)
T	crbegin (T... args)
T	crend (T... args)
T	emplace (T... args)
T	emplace_hint (T... args)
T	empty (T... args)
T	end (T... args)
T	equal_range (T... args)
T	erase (T... args)
T	extract (T... args)
T	find (T... args)
T	get_allocator (T... args)
T	insert (T... args)
T	insert_or_assign (T... args)
T	key_comp (T... args)
T	lower_bound (T... args)
T	map (T... args)
T	max_size (T... args)
T	merge (T... args)
T	operator= (T... args)
T	operator[] (T... args)
T	rbegin (T... args)
T	rend (T... args)
T	size (T... args)
T	swap (T... args)
T	try_emplace (T... args)
T	upper_bound (T... args)
T	value_comp (T... args)
T	~map (T... args)

Private Types
using	base_type = std::map< uint16_t, detail::sam_tag_variant >
	The base type.

Related Symbols
(Note that these are not member symbols.)
Other literals
template<small_string< 2 > str>
constexpr uint16_t	operator""_tag ()
	The SAM tag literal, such that tags can be used in constant expressions.

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:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#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:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#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>
requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)

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>
requires (!std::same_as<sam_tag_type_t<tag>, variant_type>)

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:

• sam_tag_dictionary.hpp