SeqAn3 3.3.0
The Modern C++ library for sequence analysis.
Loading...
Searching...
No Matches
Writing structure files

Structured 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:

  1. seqan3::field::seq (sequence)
  2. seqan3::field::id (identifier)
  3. seqan3::field::bpp (annotated sequence)
  4. seqan3::field::structure (secondary structure)
  5. seqan3::field::structured_seq (sequence and structure in one range)
  6. seqan3::field::energy (minimum free energy)
  7. seqan3::field::react (reactivity)
  8. seqan3::field::react_err (reactivity error)
  9. seqan3::field::comment (free text)
  10. seqan3::field::offset (index of first sequence character)

The member functions take any and either of these fields. If the field ID of an argument cannot be deduced, it is assumed to correspond to the field ID of the respective template parameter.

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::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:

#include <filesystem>
int main()
{
auto tmp_file = std::filesystem::temp_directory_path() / "my.dbn";
seqan3::structure_file_output fout{tmp_file}; // Vienna format detected, std::ofstream opened for file
}
A class for writing structured sequence files, e.g. Stockholm, Connect, Vienna, ViennaRNA bpp matrix ...
Definition io/structure_file/output.hpp:63
Provides seqan3::structure_file_output and corresponding traits classes.
T remove(T... args)
T temp_directory_path(T... args)

Writing to std::cout:

#include <iostream>
int main()
{
using namespace seqan3::literals;
// ^ no need to specify the template arguments
fout.emplace_back("AACGUU"_rna4, "example_id", ".(())."_wuss51); // default order for vienna: SEQ, ID, STRUCTURE
}
The Vienna format (dot bracket notation) for RNA sequences with secondary structure.
Definition format_vienna.hpp:86
The SeqAn namespace for literals.
Provides seqan3::rna4, container aliases and string literals.
Provides the WUSS format for RNA structure.

Note that this is not the same as writing structure_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. Prefer deduction over explicit defaults.

Writing record-wise

You can iterate over this file record-wise:

#include <sstream>
#include <string>
#include <tuple>
#include <vector>
int main()
{
using namespace seqan3::literals;
for (int i = 0; i < 10; i++) // ...
{
std::string id{"test_id"};
seqan3::rna5_vector seq{"ACGU"_rna5};
// ...
fout.emplace_back(seq, id, structure); // as individual variables
// or:
fout.push_back(std::tie(seq, id, structure)); // as a tuple
}
}
@ structure
Fixed interactions, usually a string of structure alphabet characters.
@ seq
The "sequence", usually a range of nucleotides or amino acids.
Provides seqan3::rna5, container aliases and string literals.
T tie(T... args)

The easiest way to write to a sequence file is to use the push_back() or emplace_back() member functions. These work similarly to how they work on a std::vector. If you pass a tuple to push_back() or give arguments to emplace_back() the seqan3::field ID of the i-th tuple-element/argument is assumed to be the i-th value of selected_field_ids, i.e. by default the first is assumed to be seqan3::field::seq, the second seqan3::field::id and the third one seqan3::field::structure. You may give less fields than are selected, if the actual format you are writing to can cope with less (e.g. for Vienna it is sufficient to write seqan3::field::seq, seqan3::field::id and seqan3::field::structure, even if selected_field_ids also contains seqan3::field::energy).

You may also use the output file's iterator for writing, however, this rarely provides an advantage.

Writing record-wise (custom fields)

If you want to pass a combined object for SEQ and STRUCTURE fields to push_back() / emplace_back(), or if you want to change the order of the parameters, you can pass a non-empty fields trait object to the structure_file_output constructor to select the fields that are used for interpreting the arguments.

The following snippets demonstrates the usage of such a fields trait object.

#include <sstream>
#include <string>
#include <tuple>
#include <vector>
int main()
{
using namespace seqan3::literals;
for (int i = 0; i < 10; i++) // ...
{
std::string id{"test_id"};
// vector of combined data structure
// ...
// note also that the order the arguments is now different, because
// you specified that `seqan3::field::id` should be first in the fields template argument
fout.emplace_back(id, structured_sequence);
// or:
fout.push_back(std::tie(id, structured_sequence));
}
}
A seqan3::alphabet_tuple_base that joins a nucleotide alphabet with an RNA structure alphabet....
Definition structured_rna.hpp:56
T emplace_back(T... args)
A class template that holds a choice of seqan3::field.
Definition record.hpp:128
Provides the composite of nucleotide with structure alphabets.

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 ID 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:

#include <sstream>
auto input = R"(> S.cerevisiae_tRNA-PHE M10740/1-73
GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUUUGGAGGUCCUGUGUUCGAUCCACAGAAUUCGCA
(((((((..((((........)))).((((.........)))).....(((((.......)))))))))))). (-17.50)
> example
UUGGAGUACACAACCUGUACACUCUUUC
..(((((..(((...)))..)))))... (-3.71))";
int main()
{
bool criteria = true;
// the output doesn't have to match the configuration of the input
for (auto & r : fin)
{
if (criteria) // r fulfills some filter criterium
fout.push_back(r);
}
}
A class for reading structured sequence files, e.g. Stockholm, Connect, Vienna, ViennaRNA bpp matrix ...
Definition structure_file/input.hpp:362
Provides seqan3::structure_file_input and corresponding traits classes.

Writing record-wise in batches

You can write multiple records at once, by assigning to the file:

#include <sstream>
#include <string>
#include <tuple>
#include <vector>
int main()
{
using namespace seqan3::literals;
{"ACGT"_rna5, "First", "...."_wuss51},
{"NATA"_rna5, "2nd", "...."_wuss51},
{"GATA"_rna5, "Third", "...."_wuss51}}; // a range of "records"
fout = range; // will iterate over the records and write them
}

File I/O pipelines

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:

#include <sstream>
auto input = R"(> S.cerevisiae_tRNA-PHE M10740/1-73
GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUUUGGAGGUCCUGUGUUCGAUCCACAGAAUUCGCA
(((((((..((((........)))).((((.........)))).....(((((.......)))))))))))). (-17.50)
> example
UUGGAGUACACAACCUGUACACUCUUUC
..(((((..(((...)))..)))))... (-3.71))";
int main()
{
}

Column-based writing

The record-based interface treats the file as a range of tuples (the records), but in certain situations you might have the data as columns, i.e. a tuple-of-ranges, instead of range-of-tuples.

You can use column-based writing in that case, it uses operator=() and seqan3::views::zip():

#include <sstream>
#include <string>
#include <vector>
using namespace seqan3::literals;
struct data_storage_t
{
};
int main()
{
data_storage_t data_storage{}; // a global or globally used variable in your program
// ... in your file writing function:
fout = seqan3::views::zip(data_storage.sequences, data_storage.ids, data_storage.structures);
}
Container that stores sequences concatenated internally.
Definition concatenated_sequences.hpp:89
Provides seqan3::concatenated_sequences.
seqan::std::views::zip zip
A view adaptor that takes several views and returns tuple-like values from every i-th element of each...
Definition zip.hpp:27
Provides seqan3::views::zip.

Formats

Currently, the only implemented format is seqan3::format_vienna. More formats will follow soon.