|
template<typename stream_type , typename seq_legal_alph_type , typename ref_seqs_type , typename ref_ids_type , typename seq_type , typename id_type , typename offset_type , typename ref_seq_type , typename ref_id_type , typename ref_offset_type , typename align_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, alignment_file_input_options< seq_legal_alph_type > const &options, ref_seqs_type &ref_seqs, alignment_file_header< ref_ids_type > &header, seq_type &seq, qual_type &qual, id_type &id, offset_type &offset, ref_seq_type &ref_seq, ref_id_type &ref_id, ref_offset_type &ref_offset, align_type &align, 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. More...
|
|
template<typename stream_type , typename seq_legal_alph_type , bool seq_qual_combined, typename seq_type , typename id_type , typename qual_type > |
void | read_sequence_record (stream_type &stream, sequence_file_input_options< seq_legal_alph_type, seq_qual_combined > const &options, seq_type &sequence, id_type &id, qual_type &qualities) |
| Read from the specified stream and back-insert into the given field buffers. More...
|
|
template<typename stream_type , typename header_type , typename seq_type , typename id_type , typename ref_seq_type , typename ref_id_type , typename align_type , typename qual_type , typename mate_type , typename tag_dict_type , typename e_value_type , typename bit_score_type > |
void | write_alignment_record (stream_type &stream, alignment_file_output_options const &options, header_type &&header, seq_type &&seq, qual_type &&qual, id_type &&id, int32_t const offset, ref_seq_type &&ref_seq, ref_id_type &&ref_id, std::optional< int32_t > ref_offset, align_type &&align, std::vector< cigar > const &cigar_vector, sam_flag const flag, uint8_t const mapq, mate_type &&mate, tag_dict_type &&tag_dict, e_value_type &&e_value, bit_score_type &&bit_score) |
| Write the given fields to the specified stream. More...
|
|
template<typename stream_type , typename seq_type , typename id_type , typename qual_type > |
void | write_sequence_record (stream_type &stream, sequence_file_output_options const &options, seq_type &&sequence, id_type &&id, qual_type &&qualities) |
| Write the given fields to the specified stream. More...
|
|
The SAM format (tag).
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 Alignment Input and Output in SeqAn for a walk through of how to read alignment files.
fields_specialisation
The SAM format provides the following fields: seqan3::field::alignment, seqan3::field::seq, seqan3::field::qual, seqan3::field::id, seqan3::field::ref_seq, seqan3::field::ref_id seqan3::field::ref_ossfet, 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 but will be defaulted to '0' for numeric fields and '*' for other fields.
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 | implicilty stored in seqan3::field::alignment |
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 |
The (read sequence/query) OFFSET will be required to store the soft clipping information at the read start (end clipping will be automatically deduced by how much the read sequence length + offset is larger than the alignment length).
Note: SeqAn currently does not support hard clipping. When reading SAM, hard-clipping is discarded; but the resulting alignment/sequence combination is still valid.
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.
template<typename stream_type , typename seq_legal_alph_type , typename ref_seqs_type , typename ref_ids_type , typename seq_type , typename id_type , typename offset_type , typename ref_seq_type , typename ref_id_type , typename ref_offset_type , typename align_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_sam::read_alignment_record |
( |
stream_type & |
stream, |
|
|
alignment_file_input_options< seq_legal_alph_type > const & |
options, |
|
|
ref_seqs_type & |
ref_seqs, |
|
|
alignment_file_header< ref_ids_type > & |
header, |
|
|
seq_type & |
seq, |
|
|
qual_type & |
qual, |
|
|
id_type & |
id, |
|
|
offset_type & |
offset, |
|
|
ref_seq_type & |
ref_seq, |
|
|
ref_id_type & |
ref_id, |
|
|
ref_offset_type & |
ref_offset, |
|
|
align_type & |
align, |
|
|
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
-
- Parameters
-
[in,out] | stream | The input stream to read from. |
[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::alignment_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] | offset | The buffer for seqan3::field::offset 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] | align | The buffer for seqan3::field::alignment 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.