SeqAn3 3.4.0-rc.1
The Modern C++ library for sequence analysis.
Loading...
Searching...
No Matches
seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ > Class Template Reference

A class for reading sequence files, e.g. FASTA, FASTQ ... More...

#include <seqan3/io/sequence_file/input.hpp>

Public Types

using field_ids = fields< field::seq, field::id, field::qual >
 The subset of seqan3::field IDs that are valid for this file; order corresponds to the types in field_types.
 
using sequence_file_input_options_type = sequence_file_input_options< typename traits_type::sequence_legal_alphabet >
 The input file options type.
 
Template arguments

Exposed as member types for public access.

using traits_type = traits_type_
 A traits type that defines aliases and template for storage of the fields.
 
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 = char
 Character type of the stream(s).
 
Field types and record type

These types are relevant for record/row-based reading; they may be manipulated via the traits_type to achieve different storage behaviour.

using sequence_type = typename traits_type::template sequence_container< typename traits_type::sequence_alphabet >
 The type of field::seq (std::vector <seqan3::dna5> by default).
 
using id_type = typename traits_type::template id_container< typename traits_type::id_alphabet >
 The type of field::id (std::string by defaul).
 
using quality_type = typename traits_type::template quality_container< typename traits_type::quality_alphabet >
 The type of field::qual (std::vector <seqan3::phred42> by default).
 
using field_types = type_list< sequence_type, id_type, quality_type >
 The previously defined types aggregated in a seqan3::type_list.
 
using record_type = sequence_record< detail::select_types_with_ids_t< field_types, field_ids, selected_field_ids >, selected_field_ids >
 The type of the record, a specialisation of seqan3::record; acts as a tuple of the selected field types.
 
Range associated types

The types necessary to facilitate the behaviour of an input range (used in record-wise reading).

using value_type = record_type
 The value_type is the record_type.
 
using reference = record_type &
 The reference type.
 
using const_reference = void
 The const_reference type is void, because files are not const-iterable.
 
using size_type = size_t
 An unsigned integer type, usually std::size_t.
 
using difference_type = std::make_signed_t< size_t >
 A signed integer type, usually std::ptrdiff_t.
 
using iterator = detail::in_file_iterator< sequence_file_input >
 The iterator type of this view (an input iterator).
 
using const_iterator = void
 The const iterator type is void, because files are not const-iterable.
 
using sentinel = std::default_sentinel_t
 The type returned by end().
 

Public Member Functions

Constructors, destructor and assignment
 sequence_file_input ()=delete
 Default constructor is explicitly deleted, you need to give a stream or file name.
 
 sequence_file_input (sequence_file_input const &)=delete
 Copy construction is explicitly deleted, because you can't have multiple access to the same file.
 
sequence_file_inputoperator= (sequence_file_input const &)=delete
 Copy assignment is explicitly deleted, because you can't have multiple access to the same file.
 
 sequence_file_input (sequence_file_input &&)=default
 Move construction is defaulted.
 
sequence_file_inputoperator= (sequence_file_input &&)=default
 Move assignment is defaulted.
 
 ~sequence_file_input ()=default
 Destructor is defaulted.
 
 sequence_file_input (std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{})
 Construct from filename.
 
template<input_stream stream_t, sequence_file_input_format file_format>
requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
 sequence_file_input (stream_t &stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
 Construct from an existing stream and with specified format.
 
template<input_stream stream_t, sequence_file_input_format file_format>
requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
 sequence_file_input (stream_t &&stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
Range interface

Provides functions for record based reading of the file.

iterator begin ()
 Returns an iterator to current position in the file.
 
sentinel end () noexcept
 Returns a sentinel for comparison with iterator.
 
reference front () noexcept
 Return the record we are currently at in the file.
 

Public Attributes

sequence_file_input_options_type options
 The options are public and its members can be set directly.
 

Related Symbols

(Note that these are not member symbols.)

Type deduction guides
template<input_stream stream_type, sequence_file_input_format file_format>
 sequence_file_input (stream_type &stream, file_format const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, typename sequence_file_input<>::selected_field_ids, type_list< file_format > >
 Deduces the sequence input file type from the stream and the format.
 
template<input_stream stream_type, sequence_file_input_format file_format>
 sequence_file_input (stream_type &&stream, file_format const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, typename sequence_file_input<>::selected_field_ids, type_list< file_format > >
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<input_stream stream_type, sequence_file_input_format file_format, detail::fields_specialisation selected_field_ids>
 sequence_file_input (stream_type &&stream, file_format const &, selected_field_ids const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, selected_field_ids, type_list< file_format > >
 Deduces the sequence input file type from the stream, the format and the field ids.
 
template<input_stream stream_type, sequence_file_input_format file_format, detail::fields_specialisation selected_field_ids>
 sequence_file_input (stream_type &stream, file_format const &, selected_field_ids const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, selected_field_ids, type_list< file_format > >
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 

Detailed Description

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
class seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >

A class for reading sequence files, e.g. FASTA, FASTQ ...

Template Parameters
traits_typeAn auxiliary type that defines certain member types and constants, must satisfy seqan3::sequence_file_input_traits. (Default: seqan3::sequence_file_input_default_traits_dna)
selected_field_idsA seqan3::fields type with the list and order of desired record entries; all fields must be in seqan3::sequence_file_input::field_ids.
valid_formatsA seqan3::type_list of the selectable formats (each must meet seqan3::sequence_file_input_format).

Reading Sequence Files

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:

  1. seqan3::field::seq
  2. seqan3::field::id
  3. seqan3::field::qual
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.

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::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:
#include <filesystem>
int main()
{
using namespace seqan3::literals;
auto fasta_file = std::filesystem::current_path() / "my.fasta";
{
// Create a ./my.fasta file.
seqan3::sequence_file_output fout{fasta_file};
fout.emplace_back("ACGT"_dna4, "TEST1");
fout.emplace_back("AGGCTGA"_dna4, "Test2");
fout.emplace_back("GGAGTATAATATATATATATATAT"_dna4, "Test3");
}
// FASTA with DNA sequences assumed, regular std::ifstream taken as stream
seqan3::sequence_file_input fin{fasta_file};
}
A class for reading sequence files, e.g. FASTA, FASTQ ...
Definition sequence_file/input.hpp:207
A class for writing sequence files, e.g. FASTA, FASTQ ...
Definition io/sequence_file/output.hpp:66
void emplace_back(arg_t &&arg, arg_types &&... args)
Write a record to the file by passing individual fields.
Definition io/sequence_file/output.hpp:336
T current_path(T... args)
Provides seqan3::dna4, container aliases and string literals.
Provides seqan3::sequence_file_output and corresponding traits classes.
The SeqAn namespace for literals.
Provides seqan3::sequence_file_input and corresponding traits classes.
Reading from a std::istringstream:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
#include <utility>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
// ^ no need to specify the template arguments
}
The FASTA format.
Definition format_fasta.hpp:77
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:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
}
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:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
// ... input had amino acid sequences
auto input = R"(>TEST1
FQTWE
>Test2
KYRTW
>Test3
EEYQTWEEFARAAEKLYLTDPMKV)";
int main()
{ // Use amino acid traits below
using sequence_file_input_type =
sequence_file_input_type fin{std::istringstream{input}, seqan3::format_fasta{}};
}
A class template that holds a choice of seqan3::field.
Definition record.hpp:125
A traits type that specifies input as amino acids.
Definition sequence_file/input.hpp:167
Type that contains multiple types.
Definition type_list.hpp:26
Provides seqan3::type_list.

Reading record-wise

You can iterate over this file record-wise:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
for (auto & record : fin)
{
seqan3::debug_stream << "ID: " << record.id() << '\n';
seqan3::debug_stream << "SEQ: " << record.sequence() << '\n';
// a quality field also exists, but is not printed, because we know it's empty for FASTA files.
}
}
Provides seqan3::debug_stream and related types.
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:37
The class template that file records are based on; behaves like a std::tuple.
Definition record.hpp:190
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:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
#include <utility>
#include <vector>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
using record_type = typename decltype(fin)::record_type;
for (auto & rec : fin)
records.push_back(std::move(rec));
}
sequence_record< detail::select_types_with_ids_t< field_types, field_ids, selected_field_ids >, selected_field_ids > record_type
The type of the record, a specialisation of seqan3::record; acts as a tuple of the selected field typ...
Definition sequence_file/input.hpp:255
T move(T... args)
SeqAn specific customisations in the standard namespace.

Reading record-wise (decomposed records)

Instead of using member accessor on the record, you can also use structured bindings to decompose the record into its elements:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
for (auto & [sequence, id, quality] : fin)
{
seqan3::debug_stream << "ID: " << id << '\n';
seqan3::debug_stream << "SEQ: " << sequence << '\n';
seqan3::debug_stream << "EMPTY QUAL." << quality << '\n'; // quality is empty for FASTA files
}
}
The generic concept for a (biological) sequence.
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!

Reading record-wise (custom fields)

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.
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
#include <vector>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
using seqan3::get;
for (auto & [id, seq, qual] : fin) // the order is now different, "id" comes first, because it was specified first
{
seqan3::debug_stream << "ID: " << id << '\n';
seqan3::debug_stream << "SEQ: " << seq << '\n';
seqan3::debug_stream << "QUAL: " << qual << '\n';
}
}
@ seq
The "sequence", usually a range of nucleotides or amino acids.
@ qual
The qualities, usually in Phred score notation.
constexpr auto const & get(configuration< configs_t... > const &config) noexcept
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition configuration.hpp:412
When reading a file, all fields not present in the file (but requested implicitly or via the selected_field_ids parameter) are ignored.

Views on files

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:
// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <sstream>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
auto minimum_length5_filter = std::views::filter(
[](auto const & rec)
{
return std::ranges::size(rec.sequence()) >= 5;
});
for (auto & rec : fin | minimum_length5_filter) // only record with sequence length >= 5 will "appear"
{
seqan3::debug_stream << "IDs of seq_length >= 5: " << rec.id() << '\n';
// ...
}
}

End of file

You can check whether a file is at end by comparing begin() and end() (if they are the same, the file is at end).

Formats

We currently support reading the following formats:

Remarks
For a complete overview, take a look at Sequence File

Constructor & Destructor Documentation

◆ sequence_file_input() [1/2]

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >::sequence_file_input ( std::filesystem::path  filename,
selected_field_ids const &  fields_tag = selected_field_ids{} 
)
inline

Construct from filename.

Parameters
[in]filenamePath to the file you wish to open.
[in]fields_tagA seqan3::fields tag. [optional]
Exceptions
seqan3::file_open_errorIf the file could not be opened, e.g. non-existant, non-readable, unknown format.

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

Decompression

This constructor transparently applies a decompression stream on top of the file stream in case the file is detected as being compressed. See the section on compression and decompression for more information.

◆ sequence_file_input() [2/2]

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
template<input_stream stream_t, sequence_file_input_format file_format>
requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >::sequence_file_input ( stream_t &  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
file_formatThe format of the file in the stream, must satisfy seqan3::sequence_file_input_format.
Parameters
[in]streamThe stream to operate on; must be derived of std::basic_istream.
[in]format_tagThe file format tag.
[in]fields_tagA seqan3::fields tag. [optional]

Decompression

This constructor transparently applies a decompression stream on top of the stream in case it is detected as being compressed. See the section on compression and decompression for more information.

Member Function Documentation

◆ begin()

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
iterator seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >::begin ( )
inline

Returns an iterator to current position in the file.

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

Equals end() if the file is at end.

Complexity

Constant.

Exceptions

Throws seqan3::format_error if the first record could not be read into the buffer.

◆ end()

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
sentinel seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >::end ( )
inlinenoexcept

Returns a sentinel for comparison with iterator.

Returns
Iterator to the first element.

This element acts as a placeholder; attempting to dereference it results in undefined behaviour.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ front()

template<sequence_file_input_traits traits_type_ = sequence_file_input_default_traits_dna, detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>, detail::type_list_of_sequence_file_input_formats valid_formats_ = type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
reference seqan3::sequence_file_input< traits_type_, selected_field_ids_, valid_formats_ >::front ( )
inlinenoexcept

Return the record we are currently at in the file.

Returns
A reference to the currently buffered record.

This function returns a reference to the currently buffered record, it is identical to dereferencing begin(), but begin also always points to the current record on single pass input ranges:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
auto it = std::ranges::begin(fin);
// the following are equivalent:
auto & rec0 = *it;
auto & rec1 = fin.front();
std::cout << std::boolalpha << (rec0.id() == rec1.id()) << '\n'; // true
// Note: rec0 and rec1 are references and become invalid after incrementing "it"!
}
T begin(T... args)
T boolalpha(T... args)

It most situations using the iterator interface or a range-based for-loop are preferable to using front(), because you can only move to the next record via the iterator.

In any case, don't forget the reference! If you want to save the data from the record elsewhere, use move:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <sstream>
#include <utility>
auto input = R"(>TEST1
ACGT
>Test2
AGGCTGA
>Test3
GGAGTATAATATATATATATATAT)";
int main()
{
auto rec0 = std::move(fin.front());
}

Complexity

Constant.

Exceptions

No-throw guarantee.


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