Loading...
Searching...
No Matches
seqan3::sam_tag_dictionary Class Reference
IO » SAM File

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:
[legend]

## 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 | 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)

## 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"
}
seqan3::sam_tag_dictionary
The SAM tag dictionary class that stores all optional SAM fields.
Definition sam_tag_dictionary.hpp:327
seqan3::sam_tag_dictionary::get
auto & get() &
Uses std::map::operator[] for access and default initializes new keys.
Definition sam_tag_dictionary.hpp:354
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:38
seqan3::literals
The SeqAn namespace for literals.
sam_tag_dictionary.hpp
Provides the seqan3::sam_tag_dictionary class and auxiliaries.

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
}
concept.hpp
Adaptations of concepts from the standard library.
variant
std::visit
T visit(T... args)

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

Hide me