SeqAn3 3.3.0
The Modern C++ library for sequence analysis.
|
Sequence files are the most generic and common biological files. Well-known formats include FASTA and FASTQ, but some may also be interested in treating SAM or BAM files as sequence files, discarding the alignment.
The Sequence file abstraction supports reading three different fields:
The first three fields are retrieved by default (and in that order). The last field may be selected to have sequence and qualities directly stored in a more memory-efficient combined container. If you select the last field you may not select seqan3::field::seq or seqan3::field::qual.
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::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.
In most cases the template parameters are deduced completely automatically:
Reading from a std::istringstream:
Note that this is not the same as writing sequence_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, sequence_file_input<>
would have also worked, but for opening from stream it would not have. In some cases, you do need to specify the arguments, e.g. if you want to read amino acids:
You can define your own traits type to further customise the types used by and returned by this class, see seqan3::sequence_file_input_default_traits_dna for more details. As mentioned above, specifying at least one template parameter yourself means that you loose automatic deduction so if you want to read amino acids and want to read from a string stream you need to give all types yourself:
You can iterate over this file record-wise:
In the above example, record
has the type seqan3::sequence_file_input::record_type which is seqan3::sequence_record. 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:
Instead of using member accessor on the record, you can also use structured bindings to decompose the record into its elements:
In this case you immediately get the two elements of the tuple: sequence
of seqan3::sequence_file_input::sequence_type and id
of seqan3::sequence_file_input::id_type. But beware: with structured bindings you do need to get the order of elements correctly!
If you want to skip specific fields from the record you can pass a non-empty fields trait object to the sequence_file_input constructor to select the fields that should be read from the input. For example to choose a combined field for SEQ and QUAL (see above). Or to never actually read the QUAL, if you don't need it. The following snippets demonstrate the usage of such a fields trait object.
When reading a file, all fields not present in the file (but requested implicitly or via the selected_field_ids
parameter) are ignored.
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:
You can check whether a file is at end by comparing begin() and end() (if they are the same, the file is at end).
We currently support reading the following formats: