The BAM format. More...

#include <seqan3/io/sam_file/format_bam.hpp>

Inheritance diagram for seqan3::format_bam:

Public Member Functions
Constructors, destructor and assignment
	format_bam ()=default
	Defaulted.

	format_bam (format_bam const &)=default
	Defaulted.

format_bam &	operator= (format_bam const &)=default
	Defaulted.

	format_bam (format_bam &&)=default
	Defaulted.

format_bam &	operator= (format_bam &&)=default
	Defaulted.

	~format_bam ()=default
	Defaulted.

Static Public Attributes
static std::vector< std::string >	file_extensions {{"bam"}}
	The valid file extensions for this format; note that you can modify this value.

Protected Member Functions
template<typename stream_type , typename seq_legal_alph_type , typename ref_seqs_type , typename ref_ids_type , typename stream_pos_type , typename seq_type , typename id_type , typename ref_seq_type , typename ref_id_type , typename ref_offset_type , typename cigar_type , typename flag_type , typename mapq_type , typename qual_type , typename mate_type , typename tag_dict_type , typename e_value_type , typename bit_score_type >
void	read_alignment_record (stream_type &stream, sam_file_input_options< seq_legal_alph_type > const &options, ref_seqs_type &ref_seqs, sam_file_header< ref_ids_type > &header, stream_pos_type &position_buffer, seq_type &seq, qual_type &qual, id_type &id, ref_seq_type &ref_seq, ref_id_type &ref_id, ref_offset_type &ref_offset, cigar_type &cigar_vector, flag_type &flag, mapq_type &mapq, mate_type &mate, tag_dict_type &tag_dict, e_value_type &e_value, bit_score_type &bit_score)
	Read from the specified stream and back-insert into the given field buffers.

template<typename stream_type , typename header_type , typename seq_type , typename id_type , typename ref_seq_type , typename ref_id_type , typename cigar_type , typename qual_type , typename mate_type , typename tag_dict_type >
void	write_alignment_record (stream_type &stream, sam_file_output_options const &options, header_type &&header, seq_type &&seq, qual_type &&qual, id_type &&id, ref_seq_type &&ref_seq, ref_id_type &&ref_id, std::optional< int32_t > ref_offset, cigar_type &&cigar_vector, sam_flag const flag, uint8_t const mapq, mate_type &&mate, tag_dict_type &&tag_dict, double e_value, double bit_score)
	Write the given fields to the specified stream.

Detailed Description

The BAM format.

The BAM format is the binary version of the SAM format:

Introduction

SAM is often used for storing alignments of several read sequences against one or more reference sequences. See the article on wikipedia for an introduction of the format or look into the official SAM format specifications. SeqAn implements version 1.6 of the SAM specification.

Take a look at our tutorial SAM Input and Output in SeqAn for a walk through of how to read SAM/BAM files.

fields_specialisation

The SAM format provides the following fields: seqan3::field::seq, seqan3::field::qual, seqan3::field::id, seqan3::field::ref_seq, seqan3::field::ref_id seqan3::field::ref_offset, seqan3::field::offset, seqan3::field::flag, seqan3::field::mapq and seqan3::field::mate. In addition there is the seqan3::field::header_ptr, which is usually only used internally to provide the range-based functionality of the file.

None of the fields are required when writing. If they are not given, a default value of '0' for numeric fields and '*' for other fields is used.

SAM format columns -> fields

Since many users will be accustomed to the columns of the SAM format, here is a mapping of the common SAM format columns to the SeqAn record fields:

#	SAM Column ID	FIELD name
1	QNAME	seqan3::field::id
2	FLAG	seqan3::field::flag
3	RNAME	seqan3::field::ref_id
4	POS	seqan3::field::ref_offset
5	MAPQ	seqan3::field::mapq
6	CIGAR	seqan3::field::cigar
7	RNEXT	seqan3::field::mate (tuple pos 0)
8	PNEXT	seqan3::field::mate (tuple pos 1)
9	TLEN	seqan3::field::mate (tuple pos 2)
10	SEQ	seqan3::field::seq
11	QUAL	seqan3::field::qual

Format Check

The format checks are implemented according to the official SAM format specifications in order to ensure correct SAM file output.

If a non-recoverable format violation is encountered on reading, or you specify invalid values/combinations when writing, seqan3::format_error is thrown.

Header implementation

The SAM header (if present) is read/written once in the beginning before the first record is read/written.

Remarks: For a complete overview, take a look at SAM File; For a complete overview, take a look at SAM File

Member Function Documentation

◆ read_alignment_record()

template<typename stream_type , typename seq_legal_alph_type , typename ref_seqs_type , typename ref_ids_type , typename stream_pos_type , typename seq_type , typename id_type , typename ref_seq_type , typename ref_id_type , typename ref_offset_type , typename cigar_type , typename flag_type , typename mapq_type , typename qual_type , typename mate_type , typename tag_dict_type , typename e_value_type , typename bit_score_type >

void seqan3::format_bam::read_alignment_record	(	stream_type &	stream,
		sam_file_input_options< seq_legal_alph_type > const &	options,
		ref_seqs_type &	ref_seqs,
		sam_file_header< ref_ids_type > &	header,
		stream_pos_type &	position_buffer,
		seq_type &	seq,
		qual_type &	qual,
		id_type &	id,
		ref_seq_type &	ref_seq,
		ref_id_type &	ref_id,
		ref_offset_type &	ref_offset,
		cigar_type &	cigar_vector,
		flag_type &	flag,
		mapq_type &	mapq,
		mate_type &	mate,
		tag_dict_type &	tag_dict,
		e_value_type &	e_value,
		bit_score_type &	bit_score
	)

inlineprotected

Read from the specified stream and back-insert into the given field buffers.

Template Parameters

stream_type	The input stream type; Must be derived from std::ostream.
stream_pos_type	Type of the position buffer, aka, the std::streampos of the current record.
ref_seqs_type	e.g. std::deque<ref_sequence_type> or decltype(std::ignore).
seq_type	Type of the seqan3::field::seq input (see seqan3::sam_file_input_traits).
qual_type	Type of the seqan3::field::qual input (see seqan3::sam_file_input_traits).
id_type	Type of the seqan3::field::id input (see seqan3::sam_file_input_traits).
ref_seq_type	Type of the seqan3::field::ref_seq input (see seqan3::sam_file_input_traits).
ref_id_type	Type of the seqan3::field::ref_id input (see seqan3::sam_file_input_traits).
ref_offset_type	Type of the seqan3::field::ref_offset input (see seqan3::sam_file_input_traits).
cigar_type	Type of the seqan3::field::cigar input (a std::vector<cigar> or std::ignore).
flag_type	Type of the seqan3::field::flag input (see seqan3::sam_file_input_traits).
mapq_type	Type of the seqan3::field::mapq input (see seqan3::sam_file_input_traits).
mate_type	std::tuple<ref_id_type, ref_offset_type, int32_t> or decltype(std::ignore).
tag_dict_type	seqan3::sam_tag_dictionary or decltype(std::ignore).
e_value_type	Type of the seqan3::field::evalue input (see seqan3::sam_file_input_traits).
bit_score_type	Type of the seqan3::field::bit_score input (see seqan3::sam_file_input_traits).

Parameters

[in,out]	stream	The input stream to read from.
[in,out]	position_buffer	The buffer to store the current record's position.
[in]	options	File specific options passed to the format.
[out]	ref_seqs	The reference sequences to the corresponding alignments.
[out]	header	A pointer to the seqan3::sam_file_header object.
[out]	seq	The buffer for seqan3::field::seq input.
[out]	qual	The buffer for seqan3::field::qual input.
[out]	id	The buffer for seqan3::field::id input.
[out]	ref_seq	The buffer for seqan3::field::ref_seq input.
[out]	ref_id	The buffer for seqan3::field::ref_id input.
[out]	ref_offset	The buffer for seqan3::field::ref_offset input.
[out]	cigar_vector	The buffer for seqan3::field::cigar input.
[out]	flag	The buffer for seqan3::field::flag input.
[out]	mapq	The buffer for seqan3::field::mapq input.
[out]	mate	The buffer for seqan3::field::mate input.
[out]	tag_dict	The buffer for seqan3::field::tags input.
[out]	e_value	The buffer for seqan3::field::evalue input.
[out]	bit_score	The buffer for seqan3::field::bit_score input.

Additional requirements

The function must also accept std::ignore as parameter for any of the fields, except stream, options and header. [This is enforced by the concept checker!]
In this case the data read for that field shall be discarded by the format.

◆ write_alignment_record()

template<typename stream_type , typename header_type , typename seq_type , typename id_type , typename ref_seq_type , typename ref_id_type , typename cigar_type , typename qual_type , typename mate_type , typename tag_dict_type >

void seqan3::format_bam::write_alignment_record	(	stream_type &	stream,
		sam_file_output_options const &	options,
		header_type &&	header,
		seq_type &&	seq,
		qual_type &&	qual,
		id_type &&	id,
		ref_seq_type &&	ref_seq,
		ref_id_type &&	ref_id,
		std::optional< int32_t >	ref_offset,
		cigar_type &&	cigar_vector,
		sam_flag const	flag,
		uint8_t const	mapq,
		mate_type &&	mate,
		tag_dict_type &&	tag_dict,
		double	e_value,
		double	bit_score
	)