A class for writing structured sequence files, e.g. Stockholm, Connect, Vienna, ViennaRNA bpp matrix ... More...
#include <seqan3/io/structure_file/output.hpp>
Public Types | |
using | field_ids = fields< field::seq, field::id, field::bpp, field::structure, field::structured_seq, field::energy, field::react, field::react_err, field::comment, field::offset > |
The subset of seqan3::field IDs that are valid for this file. | |
Template arguments | |
Exposed as member types for public access. | |
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). | |
Range associated types | |
Most of the range associated types are | |
using | value_type = void |
The value type (void). | |
using | reference = void |
The reference type (void). | |
using | const_reference = void |
The const reference type (void). | |
using | size_type = void |
The size type (void). | |
using | difference_type = std::ptrdiff_t |
A signed integer type, usually std::ptrdiff_t. | |
using | iterator = detail::out_file_iterator< structure_file_output > |
The iterator type of this view (an output 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 | |
structure_file_output ()=delete | |
Default constructor is explicitly deleted, you need to give a stream or file name. | |
structure_file_output (structure_file_output const &)=delete | |
Copy construction is explicitly deleted, because you can't have multiple access to the same file. | |
structure_file_output & | operator= (structure_file_output const &)=delete |
Copy assignment is explicitly deleted, because you can't have multiple access to the same file. | |
structure_file_output (structure_file_output &&)=default | |
Move construction is defaulted. | |
structure_file_output & | operator= (structure_file_output &&)=default |
Move assignment is defaulted. | |
~structure_file_output ()=default | |
Destructor is defaulted. | |
structure_file_output (std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{}) | |
Construct from filename. More... | |
template<output_stream stream_t, structure_file_output_format file_format> | |
structure_file_output (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. More... | |
template<output_stream stream_t, structure_file_output_format file_format> | |
structure_file_output (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. | |
Public Attributes | |
structure_file_output_options | options |
The options are public and its members can be set directly. | |
Related Functions | |
(Note that these are not member functions.) | |
Type deduction guides | |
template<output_stream stream_t, structure_file_output_format file_format, detail::fields_specialisation selected_field_ids> | |
structure_file_output (stream_t &&, file_format const &, selected_field_ids const &) -> structure_file_output< selected_field_ids, type_list< file_format >> | |
Deduction of the selected fields, the file format and the stream type. | |
template<output_stream stream_t, structure_file_output_format file_format, detail::fields_specialisation selected_field_ids> | |
structure_file_output (stream_t &, file_format const &, selected_field_ids const &) -> structure_file_output< 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. | |
Range interface | |
iterator | begin () noexcept |
Returns an iterator to current position in the file. More... | |
sentinel | end () noexcept |
Returns a sentinel for comparison with iterator. More... | |
template<typename record_t > | |
void | push_back (record_t &&r) |
Write a seqan3::record to the file. More... | |
template<typename tuple_t > | |
void | push_back (tuple_t &&t) |
Write a record in form of a std::tuple to the file. More... | |
template<typename arg_t , typename ... arg_types> | |
void | emplace_back (arg_t &&arg, arg_types &&... args) |
Write a record to the file by passing individual fields. More... | |
template<std::ranges::input_range rng_t> | |
structure_file_output & | operator= (rng_t &&range) |
Write a range of records (or tuples) to the file. More... | |
template<std::ranges::input_range rng_t> | |
structure_file_output & | operator| (rng_t &&range, structure_file_output &f) |
Write a range of records (or tuples) to the file. More... | |
template<std::ranges::input_range rng_t> | |
structure_file_output | operator| (rng_t &&range, structure_file_output &&f) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
A class for writing structured sequence files, e.g. Stockholm, Connect, Vienna, ViennaRNA bpp matrix ...
selected_field_ids | A seqan3::fields type with the list and order of fields IDs; only relevant if these can't be deduced. |
valid_formats | A seqan3::type_list of the selectable formats (each must meet seqan3::structure_file_output_format). |
### Writing structure filesStructured sequence files contain intra-molecular interactions of RNA or protein. Usually, but not necessarily, they contain the nucleotide or amino acid sequences and descriptions as well. Interactions can be represented either as fixed _secondary structure_, where every character is assigned at most one interaction partner (structure of minimum free energy), or an _annotated sequence_, where every character is assigned a set of interaction partners with specific base pair probabilities.
The structured sequence file abstraction supports writing ten different fields:
|
inline |
Construct from filename.
[in] | filename | Path to the file you wish to open. |
[in] | fields_tag | A seqan3::fields tag. [optional] |
In addition to the file name, you may specify a custom seqan3::fields type which may be easier than defining all the template parameters.
This constructor transparently applies a compression stream on top of the file stream in case the given file extension suggests the user wants this. See the section on compression and decompression for more information.
|
inline |
Construct from an existing stream and with specified format.
file_format | The format of the file in the stream, must satisfy seqan3::structure_file_output_format. |
[in,out] | stream | The stream to write to, must be derived of std::basic_ostream. |
[in] | format_tag | The file format tag. |
[in] | fields_tag | A seqan3::fields tag. [optional] |
This constructor does not apply compression transparently (because there is no way to know if the user wants this). However, you can just pass e.g. seqan3::contrib::gz_ostream to this constructor if you explicitly want compression. See the section on compression and decompression for more information.
|
inlinenoexcept |
Returns an iterator to current position in the file.
You can write to the file by assigning to the iterator, but using push_back() is usually more intuitive.
Constant.
No-throw guarantee.
|
inline |
Write a record to the file by passing individual fields.
arg_t | Type of the first field. |
arg_types | Types of further fields. |
[in] | arg | The first field to write. |
[in] | args | Further fields. |
The fields are assumed to correspond to the field IDs given in selected_field_ids, however passing less is accepted if the format does not require all of them.
Constant. TODO linear in the size of the written sequences?
Basic exception safety.
|
inlinenoexcept |
Returns a sentinel for comparison with iterator.
This element acts as a placeholder; attempting to dereference it results in undefined behaviour. It always compares false against an iterator.
Constant.
No-throw guarantee.
|
inline |
Write a range of records (or tuples) to the file.
rng_t | Type of the range, must satisfy std::ranges::output_range and have a reference type that satisfies seqan3::tuple_like. |
[in] | range | The range to write. |
This function simply iterates over the argument and calls push_back() on each element.
Linear in the number of records.
Basic exception safety.
|
inline |
Write a seqan3::record to the file.
record_t | Type of the record, a specialisation of seqan3::record. |
[in] | r | The record to write. |
Constant. TODO linear in the size of the written sequences?
Basic exception safety.
|
inline |
Write a record in form of a std::tuple to the file.
tuple_t | Type of the record, a specialisation of std::tuple. |
[in] | t | The record to write. |
The fields in the tuple are assumed to correspond to the field IDs given in selected_field_ids, however passing less is accepted if the format does not require all of them.
Constant. TODO linear in the size of the written sequences?
Basic exception safety.
|
friend |
Write a range of records (or tuples) to the file.
rng_t | Type of the range, must satisfy std::ranges::input_range and have a reference type that satisfies seqan3::tuple_like. |
[in] | range | The range to write. |
[in] | f | The file being written to. |
This operator enables structure_file_output to be at the end of a piping operation. It just calls operator=() internally.
Linear in the number of records.
Basic exception safety.
This is especially useful in combination with file-based filters: