A class for writing alignment files, e.g. SAM, BAL, BLAST, ... More...

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

Public Types
using	field_ids = fields< field::HEADER_PTR, field::SEQ, field::ID, field::OFFSET, field::REF_SEQ, field::REF_ID, field::REF_OFFSET, field::ALIGNMENT, field::MAPQ, field::FLAG, field::QUAL, field::MATE, field::TAGS, field::EVALUE, field::BIT_SCORE >
	The subset of seqan3::field IDs that are valid for this file.

Template arguments
Exposed as member types for public access.
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
Most of the range associated types are `void` for output ranges.
using	value_type = void
	The value type (void).

using	reference = void
	The reference type (void).

using	const_reference = void
	The const reference type (void).

using	size_type = void
	The size type (void).

using	difference_type = std::ptrdiff_t
	A signed integer type, usually std::ptrdiff_t.

using	iterator = detail::out_file_iterator< alignment_file_output >
	The iterator type of this view (an output 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
auto &	header ()
	Access the file's header. More...

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

	alignment_file_output (alignment_file_output const &)=delete
	Copy construction is explicitly deleted, because you can't have multiple access to the same file.

alignment_file_output &	operator= (alignment_file_output const &)=delete
	Copy assignment is explicitly deleted, because you can't have multiple access to the same file.

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

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

	~alignment_file_output ()=default
	Destructor is defaulted.

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

template<OStream2 stream_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &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<OStream2 stream_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &&stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})

template<typename ref_ids_type_ , std::ranges::ForwardRange ref_lengths_type>
	alignment_file_output (std::filesystem::path const &filename, ref_ids_type_ &&ref_ids, ref_lengths_type &&ref_lengths, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from filename. More...

template<OStream2 stream_type, AlignmentFileOutputFormat file_format, typename ref_ids_type_ , std::ranges::ForwardRange ref_lengths_type>
	alignment_file_output (stream_type &&stream, ref_ids_type_ &&ref_ids, ref_lengths_type &&ref_lengths, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
	Construct from an existing stream and with specified format. More...

Public Attributes
alignment_file_output_options	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<detail::Fields selected_field_ids>
	alignment_file_output (std::filesystem::path, selected_field_ids const &) -> alignment_file_output< selected_field_ids, typename alignment_file_output<>::valid_formats, typename alignment_file_output<>::stream_char_type, ref_info_not_given >
	Deduces selected_field_ids from input and sets alignment_file_output::ref_ids_type to seqan3::detail::ref_info_not_given. Valid formats and stream_char_type are defaulted.

template<OStream2 stream_type, AlignmentFileOutputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_output (stream_type &&, file_format const &, selected_field_ids const &) -> alignment_file_output< selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, ref_info_not_given >
	Deduces selected_field_ids, the valid format and the stream_char_type from input and sets alignment_file_output::ref_ids_type to seqan3::detail::ref_info_not_given.

template<OStream2 stream_type, AlignmentFileOutputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_output (stream_type &, file_format const &, selected_field_ids const &) -> alignment_file_output< selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, ref_info_not_given >
	Deduces selected_field_ids, the valid format and the stream_char_type from input and sets alignment_file_output::ref_ids_type to seqan3::detail::ref_info_not_given.

template<OStream2 stream_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &&, file_format const &) -> alignment_file_output< typename alignment_file_output<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, ref_info_not_given >
	Deduces the valid format and the stream_char_type from input and sets alignment_file_output::ref_ids_type to seqan3::detail::ref_info_not_given.

template<OStream2 stream_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &, file_format const &) -> alignment_file_output< typename alignment_file_output<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, ref_info_not_given >
	Deduces the valid format and the stream_char_type from input and sets alignment_file_output::ref_ids_type to seqan3::detail::ref_info_not_given.

template<detail::Fields selected_field_ids, std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type>
	alignment_file_output (std::filesystem::path const &, ref_ids_type &&, ref_lengths_type &&, selected_field_ids const &) -> alignment_file_output< selected_field_ids, typename alignment_file_output<>::valid_formats, typename alignment_file_output<>::stream_char_type, std::remove_reference_t< ref_ids_type >>
	Deduces selected_field_ids and ref_ids_type from input. Valid formats and stream_char_type are defaulted.

template<std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type>
	alignment_file_output (std::filesystem::path const &, ref_ids_type &&, ref_lengths_type &&) -> alignment_file_output< typename alignment_file_output<>::selected_field_ids, typename alignment_file_output<>::valid_formats, typename alignment_file_output<>::stream_char_type, std::remove_reference_t< ref_ids_type >>
	Deduces ref_ids_type from input. Valid formats, selected_field_ids and stream_char_type are defaulted.

template<OStream2 stream_type, std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type, AlignmentFileOutputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_output (stream_type &&, ref_ids_type &&, ref_lengths_type &&, file_format const &, selected_field_ids const &) -> alignment_file_output< selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, std::remove_reference_t< ref_ids_type >>
	Deduces selected_field_ids, the valid format, stream_char_type and the ref_ids_type from input.

template<OStream2 stream_type, std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type, AlignmentFileOutputFormat file_format, detail::Fields selected_field_ids>
	alignment_file_output (stream_type &, ref_ids_type &&, ref_lengths_type &&, file_format const &, selected_field_ids const &) -> alignment_file_output< selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, std::remove_reference_t< ref_ids_type >>
	Deduces selected_field_ids, the valid format, stream_char_type and the ref_ids_type from input.

template<OStream2 stream_type, std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &&, ref_ids_type &&, ref_lengths_type &&, file_format const &) -> alignment_file_output< typename alignment_file_output<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, std::remove_reference_t< ref_ids_type >>
	Deduces the valid format, stream_char_type and the ref_ids_type from input. selected_field_ids are defaulted.

template<OStream2 stream_type, std::ranges::ForwardRange ref_ids_type, std::ranges::ForwardRange ref_lengths_type, AlignmentFileOutputFormat file_format>
	alignment_file_output (stream_type &, ref_ids_type &&, ref_lengths_type &&, file_format const &) -> alignment_file_output< typename alignment_file_output<>::selected_field_ids, type_list< file_format >, typename std::remove_reference_t< stream_type >::char_type, std::remove_reference_t< ref_ids_type >>
	Deduces the valid format, stream_char_type and the ref_ids_type from input. selected_field_ids are defaulted.

Range interface
Provides functions for record based writing 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...

template<typename record_t >
void	push_back (record_t &&r)
	Write a seqan3::record to the file. More...

template<typename tuple_t >
void	push_back (tuple_t &&t)
	Write a record in form of a std::tuple to the file. More...

template<typename arg_t , typename ... arg_types>
void	emplace_back (arg_t &&arg, arg_types &&... args)
	Write a record to the file by passing individual fields. More...

template<typename rng_t >
alignment_file_output &	operator= (rng_t &&range)
	Write a range of records (or tuples) to the file. More...

template<typename rng_t >
alignment_file_output &	operator\| (rng_t &&range, alignment_file_output &f)
	Write a range of records (or tuples) to the file. More...

template<typename rng_t >
alignment_file_output	operator\| (rng_t &&range, alignment_file_output &&f)

Detailed Description

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>
class seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >

A class for writing alignment files, e.g. SAM, BAL, BLAST, ...

Template Parameters

selected_field_ids	A seqan3::fields type with the list and order of fields IDs; only relevant if these can't be deduced.
valid_formats	A seqan3::type_list of the selectable formats (each must model seqan3::AlignmentFileOutputFormat).
stream_char_type	The type of character of the underlying stream, must model seqan3::Char.

Introduction

Alignment files provide a way to store pairwise alignment information. Well-known formats include SAM and BAM or BLAST.

The Alignment file abstraction supports writing following fields:

There is an additional field called seqan3::field::HEADER_PTR. It is used to transfer header information from seqan3::alignment_file_input to seqan3::alignment_file_output, but you needn't deal with this field manually.

The member functions take any and either of these fields.

Construction and specialisation

This class comes with two constructors, one for construction from a file name and one for construction from an existing stream and a known format. The first one automatically picks the format based on the extension of the file name. The second can be used if you have a non-file stream, like std::cout or std::ostringstream, that you want to read from and/or if you cannot use file-extension based detection, but know that your output file has a certain format.

In most cases the template parameters are deduced completely automatically:

alignment_file_output fout{tmp_dir/"my.sam"}; // SAM format detected, std::ofstream opened for file

Writing to std::cout:

// no need to specify the template arguments <...> for format specialization:

alignment_file_output fout{tmp_dir/"my.sam", fields<field::MAPQ>{}};

Note that this is not the same as writing alignment_file_output<> (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_output<> would have also worked, but for opening from stream it would not have.

Writing record-wise

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam"};
    std::string ref_id;
    std::string read_id;
    std::vector<dna5> read;
    // ... e.g. compute and alignment
    using alignment_type = std::pair<std::vector<gapped<dna5>>, std::vector<gapped<dna5>>>;
    alignment_type dummy_alignment{}; // an empty dummy alignment
    using types        = type_list<std::vector<dna5>, std::string, alignment_type>;
    using types_as_ids = fields<field::SEQ, field::ID, field::ALIGNMENT>;
    // the record type specifies the fields we want to write
    using record_type  = record<types, types_as_ids>;
    // initialize record
    record_type rec{read, ref_id, dummy_alignment};
    // Write the record
    fout.push_back(rec);
    // same as
    fout.push_back(record_type{read, ref_id, dummy_alignment});
    // as all our fields are empty so this would print an
}

The easiest way to write to an alignment file is to use the push_back() member functions. These work similarly to how they work on an std::vector. You may also use a tuple like interface or the emplace_back() function but this is not recommended since one would have to keep track of the correct order of many fields (14 in total). For the record based interface using push_back please also see the seqan3::record documentation on how to specify a record with the correct field and type lists.

You may also use the output file's iterator for writing, however, this rarely provides an advantage.

Writing record-wise (custom fields)

If you want to omit non-required parameter or change the order of the parameters, you can pass a non-empty fields trait object to the seqan3::alignment_file_output constructor to select the fields that are used for interpreting the arguments.

The following snippets demonstrates the usage of such a field_traits object.

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    // I only want to print the mapping position (field::REF_OFFSET) and flag:
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam", fields<field::REF_OFFSET, field::FLAG>{}};
    unsigned mapping_pos{1300};
    unsigned flag{0};
    // ...
    fout.emplace_back(mapping_pos, flag);  // note that the order the arguments is now different, because
    // or:                                    you specified that REF_OFFSET should be first
    fout.push_back(std::tie(mapping_pos, flag));
}

A different way of passing custom fields to the file is to pass a seqan3::record – instead of a tuple – to push_back(). The seqan3::record clearly indicates which of its elements has which seqan3::field so the file will use that information instead of the template argument. This is especially handy when reading from one file and writing to another, because you don't have to configure the output file to match the input file, it will just work:

alignment_file_input  fin{tmp_dir/"my.sam", fields<field::REF_OFFSET, field::FLAG>{}};
alignment_file_output fout{tmp_dir/"output.sam"}; // doesn't have to match the configuration
for (auto & r : fin)
{
    fout.push_back(r); // copy all the records.
}

This will copy the FLAG and REF_OFFSET value into the new output file. Note that the other SAM columns in the output file will be defaulted, so unless you specify to read all SAM columns (see seqan3::format_sam) the output file will not be equal to the input file.

Writing record-wise in batches

You can write multiple records at once, by assigning to the file:

alignment_file_output fout{tmp_dir/"my.sam"};
std::vector<std::tuple<dna5_vector, std::string>> range
{
    { "ACGT"_dna5, "First" },
    { "NATA"_dna5, "2nd" },
    { "GATA"_dna5, "Third" }
}; // a range of "records"
fout = range; // will iterate over the records and write them

File I/O pipelines

Record-wise writing in batches also works for writing from input files directly to output files, because input files are also input ranges in SeqAn3:

// copying a file in one line:
alignment_file_output{tmp_dir/"output.sam"} = alignment_file_input{tmp_dir/"input.sam"};
// with alignment_file_output as a variable:
alignment_file_output fout{tmp_dir/"output.sam"};
alignment_file_input fin{tmp_dir/"input.sam"};
fout = fin;
// or in pipe notation:
alignment_file_input{tmp_dir/"input.sam"} | alignment_file_output{tmp_dir/"output.sam"};

This can be combined with file-based views to create I/O pipelines:

alignment_file_input{tmp_dir/"input.sam"} | view::persist
                                          | std::view::take(5) // take only the first 5 records
                                          | alignment_file_output{tmp_dir/"output.sam"};

Formats

We currently support writing the following formats:

Constructor & Destructor Documentation

◆ alignment_file_output() [1/5]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::alignment_file_output	(	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]

In addition to the file name, you may specify a custom seqan3::fields type which may be easier than defining all the template parameters.

Compression

This constructor transparently applies a compression stream on top of the file stream in case the given file extension suggests the user wants this. See the section on compression and decompression for more information.

Example:

In most cases the template parameters are deduced completely automatically:

alignment_file_output fout{tmp_dir/"my.sam"}; // SAM format detected, std::ofstream opened for file

Writing with custom selected fields:

// no need to specify the template arguments <...> for format specialization:

alignment_file_output fout{tmp_dir/"my.sam", fields<field::MAPQ>{}};

◆ alignment_file_output() [2/5]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<OStream2 stream_type, AlignmentFileOutputFormat file_format>

seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::alignment_file_output	(	stream_type &	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_type	The type of stream to write to; must model seqan3::OStream2.
file_format	The format of the file in the stream, must satisfy seqan3::AlignmentFileOutputFormat.

Parameters

[out]	stream	The stream to write to, must be derived of std::basic_ostream<stream_char_t>.
[in]	format_tag	The file format tag.
[in]	fields_tag	A seqan3::fields tag. [optional]

Compression

This constructor does not apply compression transparently (because there is no way to know if the user wants this). However, you can just pass e.g. seqan3::contrib::gz_ostream to this constructor if you explicitly want compression. See the section on compression and decompression for more information.

◆ alignment_file_output() [3/5]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<OStream2 stream_type, AlignmentFileOutputFormat file_format>

seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::alignment_file_output	(	stream_type &&	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_output() [4/5]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename ref_ids_type_ , std::ranges::ForwardRange ref_lengths_type>

seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::alignment_file_output	(	std::filesystem::path const &	filename,
		ref_ids_type_ &&	ref_ids,
		ref_lengths_type &&	ref_lengths,
		selected_field_ids const &	fields_tag = `selected_field_ids{}`
	)

inline

Construct from filename.

Template Parameters

ref_ids_type_	The type of range over reference ids; must model std::ForwardRange.
ref_lengths_type	The type of range over reference lengths; must model std::ForwardRange.

Parameters

[in]	filename	Path to the file you wish to open.
[in]	ref_ids	A range over reference ids.
[in]	ref_lengths	A range over lengths of reference sequences (same order as ref_ids).
[in]	fields_tag	A seqan3::fields tag. [optional]

In addition to the file name, you may specify a custom seqan3::fields type which may be easier than defining all the template parameters.

Compression

This constructor transparently applies a compression stream on top of the file stream in case the given file extension suggests the user wants this. See the section on compression and decompression for more information.

Example:

In most cases the template parameters are deduced completely automatically:

std::vector<std::string> ref_ids{"ref1", "ref2"};
std::vector<size_t>      ref_lenghts{1234, 5678};
alignment_file_output fout{tmp_dir/"my.sam", ref_ids, ref_lenghts};

Writing with custom selected fields:

// no need to specify the template arguments <...> for format specialization:

alignment_file_output fout{tmp_dir/"my.sam", fields<field::MAPQ>{}};

◆ alignment_file_output() [5/5]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<OStream2 stream_type, AlignmentFileOutputFormat file_format, typename ref_ids_type_ , std::ranges::ForwardRange ref_lengths_type>

seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::alignment_file_output	(	stream_type &&	stream,
		ref_ids_type_ &&	ref_ids,
		ref_lengths_type &&	ref_lengths,
		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_type	The type of stream to write to; must model seqan3::OStream2.
file_format	The format of the file in the stream, must model seqan3::AlignmentFileOutputFormat.
ref_ids_type_	The type of range over reference ids; must model std::ForwardRange.
ref_lengths_type	The type of range over reference lengths; must model std::ForwardRange.

Parameters

[in]	stream	The stream to operate on (this must be std::move'd in!).
[in]	ref_ids	A range over reference ids.
[in]	ref_lengths	A range over lengths of reference sequences (same order as ref_ids).
[in]	format_tag	The file format tag.
[in]	fields_tag	A seqan3::fields tag. [optional]

Compression

This constructor does not apply compression transparently (because there is no way to know if the user wants this). However, you can just pass e.g. seqan3::contrib::gz_ostream to this constructor if you explicitly want compression. See the section on compression and decompression for more information.

Member Function Documentation

◆ begin()

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

iterator seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::begin ( )

inlinenoexcept

Returns an iterator to current position in the file.

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

You can write to the file by assigning to the iterator, but using push_back() is usually more intuitive.

Complexity

Constant.

Exceptions

No-throw guarantee.

Example

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam"};
    auto file_it = fout.begin();
    std::string id;
    dna5_vector seq;
    // ...
    // assign to file iterator
    *file_it = std::tie(seq, id);
    // is the same as:
    fout.push_back(std::tie(seq, id));
}

◆ emplace_back()

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename arg_t , typename ... arg_types>

void seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::emplace_back	(	arg_t &&	arg,
		arg_types &&...	args
	)

inline

Write a record to the file by passing individual fields.

Template Parameters

arg_t	Type of the first field.
arg_types	Types of further fields.

Parameters

[in]	arg	The first field to write.
[in]	args	Further fields.

The fields are assumed to correspond to the field IDs given in selected_field_ids, however passing less is accepted if the format does not require all of them.

Complexity

Constant.

Exceptions

Basic exception safety.

Example

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    // I only want to print the mapping position (field::REF_OFFSET) and flag:
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam", fields<field::REF_OFFSET, field::FLAG>{}};
    unsigned mapping_pos{1300};
    unsigned flag{0};
    // ...
    fout.emplace_back(mapping_pos, flag);  // note that the order the arguments is now different, because
    // or:                                    you specified that REF_OFFSET should be first
    fout.push_back(std::tie(mapping_pos, flag));
}

◆ end()

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

sentinel seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::end ( )

inlinenoexcept

Returns a sentinel for comparison with iterator.

Returns: An end that is never reached.

This element acts as a placeholder; attempting to dereference it results in undefined behaviour. It always compares false against an iterator.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ header()

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

auto& seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::header ( )

inline

Access the file's header.

Example

std::vector<std::string> ref_ids{"ref1", "ref2"};
std::vector<size_t>      ref_lenghts{1234, 5678};
// always give reference information if you want to have your header properly initialised
alignment_file_output fout{tmp_dir/"my.sam", ref_ids, ref_lenghts};
// add information to the header of the file.
fout.header().comments.push_back("This is a comment");

See also: seqan3::alignment_file_header

◆ operator=()

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename rng_t >

alignment_file_output& seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::operator= ( rng_t && range )

inline

Write a range of records (or tuples) to the file.

Template Parameters

rng_t Type of the range, must satisfy seqan3::OutputRange and have a reference type that satisfies seqan3::TupleLike.

Parameters

[in] range The range to write.

This function simply iterates over the argument and calls push_back() on each element.

Complexity

Linear in the number of records.

Exceptions

Basic exception safety.

Example

alignment_file_output fout{tmp_dir/"my.sam"};
std::vector<std::tuple<dna5_vector, std::string>> range
{
    { "ACGT"_dna5, "First" },
    { "NATA"_dna5, "2nd" },
    { "GATA"_dna5, "Third" }
}; // a range of "records"
fout = range; // will iterate over the records and write them

◆ push_back() [1/2]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename record_t >

void seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::push_back ( record_t && r )

inline

Write a seqan3::record to the file.

Template Parameters

record_t Type of the record, a specialisation of seqan3::record.

Parameters

[in] r The record to write.

Complexity

Constant.

Exceptions

Basic exception safety.

Example

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam"};
    auto it = fout.begin();
    record<type_list<uint32_t, std::string>, fields<field::MAPQ, field::ID>> r;
    // ...
    fout.push_back(r);
}

◆ push_back() [2/2]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename tuple_t >

void seqan3::alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type >::push_back ( tuple_t && t )

inline

Write a record in form of a std::tuple to the file.

Template Parameters

tuple_t Type of the record, a specialisation of std::tuple.

Parameters

[in] t The record to write.

The fields in the tuple are assumed to correspond to the field IDs given in selected_field_ids, however passing less is accepted if the format does not require all of them.

Complexity

Constant.

Exceptions

Basic exception safety.

Example

#include <seqan3/io/alignment_file/all.hpp>
using namespace seqan3;
int main()
{
    alignment_file_output fout{std::filesystem::temp_directory_path()/"my.sam"};
    auto it = fout.begin();
    std::string id;
    dna5_vector seq;
    // ...
    fout.push_back(std::tie(seq, id));
}

Friends And Related Function Documentation

◆ operator| [1/2]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename rng_t >

alignment_file_output& operator\|	(	rng_t &&	range,
		alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type > &	f
	)

friend

Write a range of records (or tuples) to the file.

Template Parameters

rng_t Type of the range, must satisfy std::ranges::InputRange and have a reference type that satisfies seqan3::TupleLike.

Parameters

[in]	range	The range to write.
[in]	f	The file being written to.

This operator enables alignment_file_output to be at the end of a piping operation. It just calls operator=() internally.

Complexity

Linear in the number of records.

Exceptions

Basic exception safety.

Example

alignment_file_output fout{tmp_dir/"my.sam"};
std::vector<std::tuple<dna5_vector, std::string>> range
{
    { "ACGT"_dna5, "First" },
    { "NATA"_dna5, "2nd" },
    { "GATA"_dna5, "Third" }
}; // a range of "records"
fout = range; // will iterate over the records and write them

This is especially useful in combination with file-based filters:

alignment_file_input{tmp_dir/"input.sam"} | view::persist
                                          | std::view::take(5) // take only the first 5 records
                                          | alignment_file_output{tmp_dir/"output.sam"};

◆ operator| [2/2]

template<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::TypeListOfAlignmentFileOutputFormats valid_formats_ = type_list<format_sam, format_bam>, Char stream_char_type_ = char, typename ref_ids_type = ref_info_not_given>

template<typename rng_t >

alignment_file_output operator\|	(	rng_t &&	range,
		alignment_file_output< selected_field_ids_, valid_formats_, stream_char_type_, ref_ids_type > &&	f
	)

friend

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

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

seqan3/io/alignment_file/output.hpp

Public Types

Public Member Functions

Public Attributes

Related Functions

Range interface

Detailed Description

Introduction

Construction and specialisation

Writing record-wise

Writing record-wise (custom fields)

Writing record-wise in batches

File I/O pipelines

Formats

Constructor & Destructor Documentation

◆ alignment_file_output() [1/5]

Compression

Example:

◆ alignment_file_output() [2/5]

Compression

◆ alignment_file_output() [3/5]

◆ alignment_file_output() [4/5]

Compression

Example:

◆ alignment_file_output() [5/5]

Compression

Member Function Documentation

◆ begin()

Complexity

Exceptions

Example

◆ emplace_back()

Complexity

Exceptions

Example

◆ end()

Complexity

Exceptions

◆ header()

Example

◆ operator=()

Complexity

Exceptions

Example

◆ push_back() [1/2]

Complexity

Exceptions

Example

◆ push_back() [2/2]

Complexity

Exceptions

Example

Friends And Related Function Documentation

◆ operator| [1/2]

Complexity

Exceptions

Example

◆ operator| [2/2]