A class for reading alignment files, e.g. SAM, BAM, BLAST ... More...

#include <seqan3/io/alignment_file/input.hpp>

Public Types
Template arguments
Exposed as member types for public access.
using	traits_type = traits_type_
	A traits type that defines aliases and template for storage of the fields.

using	selected_field_ids = selected_field_ids_
	A seqan3::fields list with the fields selected for the record.

using	valid_formats = valid_formats_
	A seqan3::type_list with the possible formats.

using	stream_char_type = stream_char_type_
	Character type of the stream(s), usually `char`.

Range associated types
The types necessary to facilitate the behaviour of an input range (used in record-wise reading).
using	value_type = record_type
	The value_type is the record_type.

using	reference = record_type &
	The reference type.

using	const_reference = void
	The const_reference type is void because files are not const-iterable.

using	size_type = size_t
	An unsigned integer type, usually std::size_t.

using	difference_type = std::make_signed_t< size_t >
	A signed integer type, usually std::ptrdiff_t.

using	iterator = detail::in_file_iterator< alignment_file_input >
	The iterator type of this view (an input iterator).

using	const_iterator = void
	The const iterator type is void because files are not const-iterable.

using	sentinel = std::ranges::default_sentinel_t
	The type returned by end().

Public Member Functions
header_type &	header ()
	Access the file's header. More...

Constructors, destructor and assignment
	alignment_file_input ()=delete
	Default constructor is explicitly deleted, you need to give a stream or file name.

	alignment_file_input (alignment_file_input const &)=delete
	Copy construction is explicitly deleted because you cannot have multiple access to the same file.

alignment_file_input &	operator= (alignment_file_input const &)=delete
	Copy assignment is explicitly deleted because you cannot have multiple access to the same file.

	alignment_file_input (alignment_file_input &&)=default
	Move construction is defaulted.

alignment_file_input &	operator= (alignment_file_input &&)=default
	Move assignment is defaulted.

	~alignment_file_input ()=default
	Destructor is defaulted.

	alignment_file_input (std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from filename. More...

template<IStream2 stream_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_t &stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from an existing stream and with specified format. More...

template<IStream2 stream_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_t &&stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})

	alignment_file_input (std::filesystem::path filename, typename traits_type::ref_ids &ref_ids, typename traits_type::ref_sequences &ref_sequences, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from filename and given additional reference information. More...

template<IStream2 stream_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_t &stream, typename traits_type::ref_ids &ref_ids, typename traits_type::ref_sequences &ref_sequences, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from an existing stream and with specified format. More...

template<IStream2 stream_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_t &&stream, typename traits_type::ref_ids &ref_ids, typename traits_type::ref_sequences &ref_sequences, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})

Range interface
Provides functions for record based reading of the file.
iterator	begin () noexcept
	Returns an iterator to current position in the file. More...

sentinel	end () noexcept
	Returns a sentinel for comparison with iterator. More...

reference	front () noexcept
	Return the record we are currently at in the file. More...

Public Attributes
alignment_file_input_options< typename traits_type::sequence_legal_alphabet >	options
	The options are public and its members can be set directly.

Related Functions
(Note that these are not member functions.)
Type deduction guides
template<IStream2 stream_type, AlignmentFileInputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_input (stream_type &&stream, file_format const &, selected_field_ids const &) -> alignment_file_input< typename alignment_file_input<>::traits_type, selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce selected fields, file_format and stream char type, default the rest.

template<IStream2 stream_type, AlignmentFileInputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_input (stream_type &stream, file_format const &, selected_field_ids const &) -> alignment_file_input< typename alignment_file_input<>::traits_type, selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce selected fields, file_format and stream char type, default the rest.

template<IStream2 stream_type, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_type &&stream, file_format const &) -> alignment_file_input< typename alignment_file_input<>::traits_type, typename alignment_file_input<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce file_format and stream char type, default the rest.

template<IStream2 stream_type, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_type &stream, file_format const &) -> alignment_file_input< typename alignment_file_input<>::traits_type, typename alignment_file_input<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce file_format and stream char type, default the rest.

template<std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t, detail::Fields selected_field_ids>
	alignment_file_input (std::filesystem::path path, ref_ids_t &, ref_sequences_t &, selected_field_ids const &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, selected_field_ids, typename alignment_file_input<>::valid_formats, typename alignment_file_input<>::stream_char_type >
	Deduce selected fields, ref_sequences_t and ref_ids_t, default the rest.

template<std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t>
	alignment_file_input (std::filesystem::path path, ref_ids_t &, ref_sequences_t &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, typename alignment_file_input<>::selected_field_ids, typename alignment_file_input<>::valid_formats, typename alignment_file_input<>::stream_char_type >
	Deduce ref_sequences_t and ref_ids_t, default the rest.

template<IStream2 stream_type, std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t, AlignmentFileInputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_input (stream_type &&stream, ref_ids_t &, ref_sequences_t &, file_format const &, selected_field_ids const &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce selected fields, ref_sequences_t and ref_ids_t, file format and stream char type.

template<IStream2 stream_type, std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t, AlignmentFileInputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_input (stream_type &stream, ref_ids_t &, ref_sequences_t &, file_format const &, selected_field_ids const &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce selected fields, ref_sequences_t and ref_ids_t, file format and stream char type.

template<IStream2 stream_type, std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_type &&stream, ref_ids_t &, ref_sequences_t &, file_format const &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, typename alignment_file_input<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce ref_sequences_t and ref_ids_t, file format and stream char type.

template<IStream2 stream_type, std::ranges::ForwardRange ref_ids_t, std::ranges::ForwardRange ref_sequences_t, AlignmentFileInputFormat file_format>
	alignment_file_input (stream_type &stream, ref_ids_t &, ref_sequences_t &, file_format const &) -> alignment_file_input< alignment_file_input_default_traits< std::remove_reference_t< ref_sequences_t >, std::remove_reference_t< ref_ids_t >>, typename alignment_file_input<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type >
	Deduce selected fields, ref_sequences_t and ref_ids_t, file format and stream char type.

Field types and record type
These types are relevant for record/row-based reading; they may be manipulated via the traits_type to achieve different storage behaviour.
using	sequence_type = typename traits_type::template sequence_container< typename traits_type::sequence_alphabet >
	The type of field::SEQ (default std::vector<seqan3::dna5>).

using	id_type = typename traits_type::template id_container< typename traits_type::id_alphabet >
	The type of field::ID (default std::string by default).

using	offset_type = int32_t
	The type of field::OFFSET is fixed to int32_t.

using	ref_sequence_type = std::conditional_t< std::Same< typename traits_type::ref_sequences, ref_info_not_given >, dummy_ref_type, decltype(std::declval< detail::transformation_trait_or_t< seqan3::reference< typename traits_type::ref_sequences const >, dummy_ref_type > >()\|view::slice(0, 0))>
	The type of field::REF_SEQ (default depends on construction). More...

using	ref_id_type = std::optional< int32_t >
	The type of field::REF_ID is fixed to std::optional<int32_t>. More...

using	ref_offset_type = std::optional< int32_t >
	The type of field::REF_OFFSET is fixed to an std::optional<int32_t>. More...

using	mapq_type = uint8_t
	The type of field::MAPQ is fixed to uint8_t.

using	quality_type = typename traits_type::template quality_container< typename traits_type::quality_alphabet >
	The type of field::QUAL (default std::vector<seqan3::phred42>).

using	flag_type = uint16_t
	The type of field::FLAG is fixed to uint16_t.

using	mate_type = std::tuple< ref_id_type, ref_offset_type, int32_t >
	The type of field::MATE is fixed to std::tuple<ref_id_type, ref_offset_type, int32_t>).

using	e_value_type = double
	The type of field::EVALUE is fixed to double.

using	bitscore_type = double
	The type of field::BITSCORE is fixed to double.

using	header_type = alignment_file_header< typename traits_type::ref_ids >
	The type of field::HEADER_PTR (default: alignment_file_header<typename traits_type::ref_ids>).

using	alignment_type = std::tuple< gap_decorator< ref_sequence_type >, alignment_query_type >
	The type of field::ALIGNMENT (default: std::pair<std::vector<gapped<dna5>>, std::vector<gapped<dna5>>>).

using	field_types = type_list< sequence_type, id_type, offset_type, ref_sequence_type, ref_id_type, ref_offset_type, alignment_type, mapq_type, quality_type, flag_type, mate_type, sam_tag_dictionary, e_value_type, bitscore_type, header_type * >
	The previously defined types aggregated in a seqan3::type_list.

using	field_ids = fields< field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR >
	The subset of seqan3::field tags that are valid for this file; order corresponds to the types in field_types.

using	record_type = record< detail::select_types_with_ids_t< field_types, field_ids, selected_field_ids >, selected_field_ids >
	The type of the record, a specialisation of seqan3::record; acts as a tuple of the selected field types.

Detailed Description

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>
class seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >

A class for reading alignment files, e.g. SAM, BAM, BLAST ...

Template Parameters

traits_type	An auxiliary type that defines certain member types and constants, must model seqan3::AlignmentFileInputTraits.
selected_field_ids	A seqan3::fields type with the list and order of desired record entries; all fields must be in seqan3::alignment_file_input::field_ids.
valid_formats	A seqan3::type_list of the selectable formats (each must meet seqan3::AlignmentFileInputFormat).
stream_char_type	The type of the underlying stream device(s); must model std::Integral.

Introduction

Alignment files are primarily used to store pairwise alignments of two biological sequences and often come with many additional information. Well-known formats include the SAM/BAM format used to store read mapping data or the BLAST format that stores the results of a query search against a data base.

The Alignment file abstraction supports reading 14 different fields:

There exists one more field for alignment files, the seqan3::field::HEADER_PTR, but this field is mostly used internally. Please see the seqan3::alignment_file_output::header member function for details on how to access the seqan3::alignment_file_header of the file.)

All of these fields are retrieved by default (and in that order). Note that some of the fields are specific to the SAM format (e.g. seqan3::field::FLAG) while others are specific to BLAST format (e.g. seqan3::field::BIT_SCORE). Please see the corresponding formats for more details (seqan3::format_sam).

Construction and specialisation

This class comes with four constructors: One for construction from a file name, one for construction from an existing stream and a known format and both of the former with or without additional reference information.

Constructing from a file name automatically picks the format based on the extension of the file name. Constructing from a stream can be used if you have a non-file stream, like std::cin or std::istringstream, that you want to read from and/or if you cannot use file-extension based detection, but know that your input file has a certain format.

The reference information is specific to the SAM format. The SAM format only stores a "semi-alignment" meaning that it has the query sequence and the cigar string representing the gap information but not the reference information. If you want to retrieve valid/full alignments, you need to pass the corresponding reference information:

ref_ids: The name of the references, e.g. "chr1", "chr2", ...
ref_sequences: The reference sequence information in the same order as the ref_ids.

In most cases the template parameters are deduced automatically:

alignment_file_input fin{"/tmp/my.sam"}; // SAM format assumed, regular std::ifstream taken as stream

Reading from an std::istringstream:

std::string input
{
    "@HD\tVN:1.6\tSO:coordinate\n"
    "r001\t99\tref\t7\t30\t8M2I4M1D3M\t=\t37\t39\tTTAGATAAAGGATACTG\t*\n"
};
std::istringstream iss(input);
alignment_file_input fin{iss, format_sam{}};
//              ^ no need to specify the template arguments

Note that this is not the same as writing alignment_file_input<> (with angle brackets). In the latter case they are explicitly set to their default values, in the former case automatic deduction happens which chooses different parameters depending on the constructor arguments. For opening from file, alignment_file_input<> would have also worked, but for opening from stream it would not have.

You can define your own traits type to further customise the types used by and returned by this class, see seqan3::alignment_file_input_default_traits for more details. As mentioned above, specifying at least one template parameter yourself means that you loose automatic deduction. The following is equivalent to the automatic type deduction example with a stream from above:

alignment_file_input<alignment_file_input_default_traits<>,  // The expected format.
                     fields<field::SEQ,                      // The default types; you can adjust this list
                            field::ID,                       // if you don't want to read all this data.
                            field::OFFSET,
                            field::REF_SEQ,
                            field::REF_ID,
                            field::REF_OFFSET,
                            field::ALIGNMENT,
                            field::MAPQ,
                            field::QUAL,
                            field::FLAG,
                            field::MATE,
                            field::TAGS,
                            field::EVALUE,
                            field::BIT_SCORE,
                            field::HEADER_PTR>,
                     type_list<format_sam>, // Which formats are allowed.
                     char>                                 // Value type of the stream.
                     fin{iss, format_sam{}};

Reading record-wise

You can iterate over this file record-wise:

alignment_file_input fin{"/tmp/my.sam"};
for (auto & rec : fin)
{
    debug_stream << "id:  "              << get<field::ID>(rec)         << '\n';
    debug_stream << "read sequence: "    << get<field::SEQ>(rec)        << '\n';
    debug_stream << "mapping position: " << get<field::REF_OFFSET>(rec) << '\n';
    debug_stream << "mapping quality: "  << get<field::MAPQ>(rec)       << '\n';
    // there are more fields read on default
}

In the above example, rec has the type record_type which is a specialisation of seqan3::record and behaves like an std::tuple (that's why we can access it via get). Instead of using the seqan3::field based interface on the record, you could also use std::get<0> or even std::get<dna4_vector> to retrieve the sequence, but it is not recommended, because it is more error-prone.

Note: It is important to write auto & and not just auto, otherwise you will copy the record on every iteration. Since the buffer gets "refilled" on every iteration, you can also move the data out of the record if you want to store it somewhere without copying:

alignment_file_input fin{"/tmp/my.sam"};
using record_type = typename decltype(fin)::record_type;
std::vector<record_type> records; // store all my records in a vector
for (auto & rec : fin)
    records.push_back(std::move(rec));

Reading record-wise (custom fields)

If you want to skip specific fields from the record you can pass a non-empty fields trait object to the seqan3::alignment_file_input constructor to select the fields that should be read from the input. For example, you may only be interested in the mapping flag and mapping quality of your SAM data to get some statistics. The following snippets demonstrate the usage of such a fields trait object.

alignment_file_input fin{"/tmp/my.sam", fields<field::FLAG, field::MAPQ>{}};
for (auto & rec : fin)
{
    debug_stream << "flag:  "            << get<field::FLAG>(rec) << '\n';
    debug_stream << "mapping quality:  " << get<field::MAPQ>(rec) << '\n';
    // get<field::SEQ>(rec) would fail as it was not read
}

When reading a file, all fields not present in the file (but requested implicitly or via the selected_field_ids parameter) are ignored and the respective value in the record stays empty.

Reading record-wise (decomposed records)

Instead of using get on the record, you can also use structured bindings to decompose the record into its elements. Considering the example of reading only the flag and mapping quality like before you can also write:

alignment_file_input fin{"/tmp/my.sam", fields<field::FLAG, field::MAPQ>{}};
for (auto & [flag, mapq] : fin) // the order is the same as specified in fields!
{
    debug_stream << "flag:  "            << flag << '\n';
    debug_stream << "mapping quality:  " << mapq << '\n';
}

In this case you immediately get the two elements of the tuple: flag of flag_type and mapq of mapq_type. But beware: with structured bindings you do need to get the order of elements correctly!

Views on files

Since SeqAn files are ranges, you can also create views over files. A useful example is to filter the records based on certain criteria, e.g. minimum length of the sequence field:

alignment_file_input fin{"/tmp/my.sam"};
auto minimum_length5_filter = std::view::filter([] (auto const & rec)
{
    return size(get<field::SEQ>(rec)) >= 10;
});
for (auto & rec : fin | minimum_length5_filter) // only records with sequence length >= 10 will "appear"
{
    debug_stream << get<field::ID>(rec) << '\n';
}

End of file

You can check whether a file is at its end by comparing begin() and end() (if they are the same, the file is at its end).

Formats

We currently support reading the following formats:

Member Typedef Documentation

◆ ref_id_type

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

using seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::ref_id_type = std::optional<int32_t>

The type of field::REF_ID is fixed to std::optional<int32_t>.

To be consistent with the BAM format, the field::REF_ID will hold the index to the actual reference information stored in the header. If a read is unmapped, the optional will remain valueless.

Attention: SeqaAn3 transforms the 1-based SAM format position into a 0-based position.

◆ ref_offset_type

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

using seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::ref_offset_type = std::optional<int32_t>

The type of field::REF_OFFSET is fixed to an std::optional<int32_t>.

The SAM format is 1-based and a 0 in the ref_offset field indicated an unmapped read. Since we convert 1-based positions to 0-based positions when reading the SAM format, we model the ref_offset_type as an std::optional. If the input value is 0, the std::optional will remain valueless.

◆ ref_sequence_type

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

using seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::ref_sequence_type = std::conditional_t<std::Same<typename traits_type::ref_sequences, ref_info_not_given>, dummy_ref_type, decltype(std::declval< detail::transformation_trait_or_t< seqan3::reference<typename traits_type::ref_sequences const>, dummy_ref_type> >() | view::slice(0, 0))>

The type of field::REF_SEQ (default depends on construction).

If no reference information are given on construction, this type deduces to a sized view that throws on access (since there is nothing to access anyway). If the reference information are given, the type is deduced to a view over the given input reference sequence type such that no sequence information is copied.

Constructor & Destructor Documentation

◆ alignment_file_input() [1/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	std::filesystem::path	filename,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

Construct from filename.

Parameters

[in]	filename	Path to the file you wish to open.
[in]	fields_tag	A seqan3::fields tag. [optional]

Exceptions

seqan3::file_open_error If the file could not be opened, e.g. non-existent, non-readable, unknown format.

In addition to the file name, you may specify a custom seqan3::fields object (e.g. seqan3::fields<seqan3::field::SEQ>{}) which may be easier than defining all the template parameters.

Decompression

This constructor transparently applies a decompression stream on top of the file stream in case the file is detected as being compressed. See the section on compression and decompression for more information.

◆ alignment_file_input() [2/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

template<IStream2 stream_t, AlignmentFileInputFormat file_format>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	stream_t &	stream,
		file_format const &	format_tag,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

Construct from an existing stream and with specified format.

Template Parameters

stream_t	The stream type; must model seqan3::IStream2.
file_format	The format of the file in the stream, must model seqan3::AlignmentFileInputFormat.

Parameters

[in]	stream	The stream to operate on; must be derived of std::basic_istream.
[in]	format_tag	The file format tag.
[in]	fields_tag	A seqan3::fields tag. [optional]

In addition to the stream and the format, you may specify a custom seqan3::fields object (e.g. seqan3::fields<seqan3::field::SEQ>{}) which may be easier than defining all the template parameters.

Decompression

This constructor transparently applies a decompression stream on top of the stream in case it is detected as being compressed. See the section on compression and decompression for more information.

◆ alignment_file_input() [3/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

template<IStream2 stream_t, AlignmentFileInputFormat file_format>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	stream_t &&	stream,
		file_format const &	format_tag,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ alignment_file_input() [4/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	std::filesystem::path	filename,
		typename traits_type::ref_ids &	ref_ids,
		typename traits_type::ref_sequences &	ref_sequences,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

Construct from filename and given additional reference information.

Parameters

[in]	filename	Path to the file you wish to open.
[in]	ref_ids	A range containing the reference ids that correspond to the SAM/BAM file.
[in]	ref_sequences	A range containing the reference sequences that correspond to the SAM/BAM file.
[in]	fields_tag	A seqan3::fields tag. [optional]

Exceptions

seqan3::file_open_error If the file could not be opened, e.g. non-existent, non-readable, unknown format.

The reference information given by the ids (names) and sequences will be used to construct a proper alignment when reading in SAM or BAM files. If you are not interested in the full alignment, call the constructor without the parameters.

In addition to the file name and reference information, you may specify a custom seqan3::fields object (e.g. seqan3::fields<seqan3::field::SEQ>{}) which may be easier than defining all the template parameters.

Decompression

This constructor transparently applies a decompression stream on top of the file stream in case the file is detected as being compressed. See the section on compression and decompression for more information.

◆ alignment_file_input() [5/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

template<IStream2 stream_t, AlignmentFileInputFormat file_format>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	stream_t &	stream,
		typename traits_type::ref_ids &	ref_ids,
		typename traits_type::ref_sequences &	ref_sequences,
		file_format const &	format_tag,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

Construct from an existing stream and with specified format.

Template Parameters

stream_t	The stream type; must model seqan3::IStream2.
file_format	The format of the file in the stream; must model seqan3::AlignmentFileInputFormat.

Parameters

[in]	stream	The stream to operate on; must be derived of std::basic_istream.
[in]	ref_ids	A range containing the reference ids that correspond to the SAM/BAM file.
[in]	ref_sequences	A range containing the reference sequences that correspond to the SAM/BAM file.
[in]	format_tag	The file format tag.
[in]	fields_tag	A seqan3::fields tag. [optional]

The reference information given by the ids (names) and sequences will be used to construct a proper alignment when reading in SAM or BAM files. If you are not interested in the full alignment, you do not need to specify those information.

In addition to the stream, reference information and format, you may specify a custom seqan3::fields object (e.g. seqan3::fields<seqan3::field::SEQ>{}) which may be easier than defining all the template parameters.

Decompression

This constructor transparently applies a decompression stream on top of the stream in case it is detected as being compressed. See the section on compression and decompression for more information.

◆ alignment_file_input() [6/6]

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

template<IStream2 stream_t, AlignmentFileInputFormat file_format>

seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::alignment_file_input	(	stream_t &&	stream,
		typename traits_type::ref_ids &	ref_ids,
		typename traits_type::ref_sequences &	ref_sequences,
		file_format const &	format_tag,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Function Documentation

◆ begin()

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

iterator seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::begin ( )

inlinenoexcept

Returns an iterator to current position in the file.

Returns: An iterator pointing to the current position in the file.

Equals end() if the file is at end.

alignment_file_input fin{"/tmp/my.sam"};
auto it = fin.begin();
// the following are equivalent:
auto & rec0 = *it;
auto & rec1 = fin.front();
// Note: both become invalid after incrementing "it"!

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ end()

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

sentinel seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::end ( )

inlinenoexcept

Returns a sentinel for comparison with iterator.

Returns: Iterator to the first element.

This element acts as a placeholder; attempting to dereference it results in undefined behaviour.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ front()

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

reference seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::front ( )

inlinenoexcept

Return the record we are currently at in the file.

Returns: A reference to the currently buffered record.

This function returns a reference to the currently buffered record, it is identical to dereferencing begin(), and begin also always points to the current record on single pass input ranges:

alignment_file_input fin{"/tmp/my.sam"};
auto it = fin.begin();
// the following are equivalent:
auto & rec0 = *it;
auto & rec1 = fin.front();
// Note: both become invalid after incrementing "it"!

In most situations using the iterator interface or a range-based for-loop are preferable to using front(), because you can only move to the next record via the iterator.

In any case, don't forget the reference! If you want to save the data from the record elsewhere, use move:

alignment_file_input fin{"/tmp/my.sam"};
auto rec = std::move(fin.front()); // rec now stores the data permanently

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ header()

template<AlignmentFileInputTraits traits_type_ = alignment_file_input_default_traits<>, detail::Fields selected_field_ids_ = fields<field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::QUAL, field::FLAG, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE, field::HEADER_PTR>, detail::TypeListOfAlignmentFileInputFormats valid_formats_ = type_list<format_sam, format_bam>, std::Integral stream_char_type_ = char>

header_type& seqan3::alignment_file_input< traits_type_, selected_field_ids_, valid_formats_, stream_char_type_ >::header ( )

inline

Access the file's header.

You can access the header directly after the construction with reference information of the file object.

Example

@HD VN:1.6 SO:coordinate
@SQ SN:ref LN:45
r001   99 ref  7 30 8M2I4M1D3M = 37  39 TTAGATAAAGGATACTG *
r003    0 ref  9 30 5S6M       *  0   0 GCCTAAGCTAA       * SA:Z:ref,29,-,6H5M,17,0;
r003 2064 ref 29 17 6H5M       *  0   0 TAGGC             * SA:Z:ref,9,+,5S6M,30,1;
r001  147 ref 37 30 9M         =  7 -39 CAGCGGCAT         * NM:i:1

alignment_file_input fin{"/tmp/my.sam"};
// access the header information
debug_stream << fin.header().format_version << std::endl; // 1.6
debug_stream << fin.header().ref_dict << std::endl;       // [(ref,(45,))] (this only works with our debug_stream!)

See also: seqan3::alignment_file_header

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

seqan3/io/alignment_file/input.hpp

Public Types

Public Member Functions

Public Attributes

Related Functions

Field types and record type

Detailed Description

Introduction

Construction and specialisation

Reading record-wise

Reading record-wise (custom fields)

Reading record-wise (decomposed records)

Views on files

End of file

Formats

Member Typedef Documentation

◆ ref_id_type

◆ ref_offset_type

◆ ref_sequence_type

Constructor & Destructor Documentation

◆ alignment_file_input() [1/6]

Decompression

◆ alignment_file_input() [2/6]

Decompression

◆ alignment_file_input() [3/6]

◆ alignment_file_input() [4/6]

Decompression

◆ alignment_file_input() [5/6]

Decompression

◆ alignment_file_input() [6/6]

Member Function Documentation

◆ begin()

Complexity

Exceptions

◆ end()

Complexity

Exceptions

◆ front()

Complexity

Exceptions

◆ header()

Example