SeqAn3 3.3.0
The Modern C++ library for sequence analysis.
|
The seqan3::sam_file_output 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:
Writing to std::cout:
Note that this is not the same as writing sam_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, sam_file_output<>
would have also worked, but for opening from stream it would not have.
The easiest way to write to a SAM/BAM file is to use the push_back()
member functions. These work similarly to how they work on a 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.
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::sam_file_output constructor to select the fields that are used for interpreting the arguments.
The following snippet demonstrates the usage of such a field_traits
object.
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:
This will copy the seqan3::field::flag and seqan3::field::ref_offset value into the new output file.
You can write multiple records at once, by assigning to the file:
Record-wise writing in batches also works for writing from input files directly to output files, because input files are also input ranges in SeqAn:
This can be combined with file-based views to create I/O pipelines:
We currently support writing the following formats: