SeqAn3 3.4.0-rc.1
The Modern C++ library for sequence analysis.
Loading...
Searching...
No Matches
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
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>
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 >
at (T... args)
 
begin (T... args)
 
cbegin (T... args)
 
cend (T... args)
 
clear (T... args)
 
contains (T... args)
 
count (T... args)
 
crbegin (T... args)
 
crend (T... args)
 
emplace (T... args)
 
emplace_hint (T... args)
 
empty (T... args)
 
end (T... args)
 
equal_range (T... args)
 
erase (T... args)
 
extract (T... args)
 
find (T... args)
 
get_allocator (T... args)
 
insert (T... args)
 
insert_or_assign (T... args)
 
key_comp (T... args)
 
lower_bound (T... args)
 
map (T... args)
 
max_size (T... args)
 
merge (T... args)
 
operator= (T... args)
 
operator[] (T... args)
 
rbegin (T... args)
 
rend (T... args)
 
size (T... args)
 
swap (T... args)
 
try_emplace (T... args)
 
upper_bound (T... args)
 
value_comp (T... args)
 
~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:

using namespace seqan3::literals;
// ...
uint16_t tag_id = "NM"_tag; // tag_id = 10061
The SeqAn namespace for literals.
Provides the seqan3::sam_tag_dictionary class and auxiliaries.

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 namespace seqan3::literals;
// ...
using nm_tag_type = seqan3::sam_tag_type_t<"NM"_tag>;

which is the short cut for:

using namespace seqan3::literals;
// ...
using nm_tag_type2 = seqan3::sam_tag_type<"NM"_tag>::type;
The generic base class.
Definition sam_tag_dictionary.hpp:165

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-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
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"
}
The SAM tag dictionary class that stores all optional SAM fields.
Definition sam_tag_dictionary.hpp:327
auto & get() &
Uses std::map::operator[] for access and default initializes new keys.
Definition sam_tag_dictionary.hpp:354
Provides seqan3::debug_stream and related types.
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:37
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-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <variant> // for std::visit
#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 << ",";
}
};
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
}
The (most general) container concept as defined by the standard library.
The main SeqAn3 namespace.
Definition aligned_sequence_concept.hpp:26
Adaptations of concepts from the standard library.
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_rangeif 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_rangeif map has no key tag.

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