SeqAn3  3.1.0
The Modern C++ library for sequence analysis.
input.hpp
Go to the documentation of this file.
1 // -----------------------------------------------------------------------------------------------------
2 // Copyright (c) 2006-2021, Knut Reinert & Freie Universität Berlin
3 // Copyright (c) 2016-2021, Knut Reinert & MPI für molekulare Genetik
4 // This file may be used, modified and/or redistributed under the terms of the 3-clause BSD-License
5 // shipped with this file and also available at: https://github.com/seqan/seqan3/blob/master/LICENSE.md
6 // -----------------------------------------------------------------------------------------------------
7 
13 #pragma once
14 
15 #include <cassert>
16 #include <seqan3/std/filesystem>
17 #include <fstream>
18 #include <limits>
19 #include <optional>
20 #include <string>
21 #include <type_traits>
22 #include <utility>
23 #include <variant>
24 #include <vector>
25 
33 #include <seqan3/io/exception.hpp>
36 #include <seqan3/io/detail/record.hpp>
43 
44 namespace seqan3
45 {
46 // ----------------------------------------------------------------------------
47 // structure_file_input_traits
48 // ----------------------------------------------------------------------------
49 
141 template <typename t>
142 SEQAN3_CONCEPT structure_file_input_traits = requires(t v)
143 {
144  // TODO(joergi-w) The expensive concept checks are currently omitted. Check again when compiler has improved.
145  // sequence
150 
151  // id
154 
155  // bpp
156  requires std::is_floating_point_v<typename t::bpp_prob>;
158 
159 // requires container // TODO check Associative container Concept when implemented
160 // <typename t::template bpp_queue
161 // <typename t::template bpp_item
162 // <typename t::bpp_prob, typename t::bpp_partner>>>
163 // && requires(typename t::template bpp_queue // TODO maybe implement also a version that allows emplace_back
164 // <typename t::template bpp_item
165 // <typename t::bpp_prob, typename t::bpp_partner>> value) { value.emplace(1.0, 1); };
166 // requires sequence_container
167 // <typename t::template bpp_container
168 // <typename t::template bpp_queue
169 // <typename t::template bpp_item
170 // <typename t::bpp_prob, typename t::bpp_partner>>>>;
171 
172  // structure
173  requires std::is_same_v<typename t::structure_alphabet, dssp9> // TODO(joergi-w) add aa_structure_concept
176 
177  // structured sequence: tuple composites of seq and structure
178  requires std::is_base_of_v<alphabet_tuple_base
179  <typename t::template structured_seq_alphabet
180  <typename t::seq_alphabet, typename t::structure_alphabet>,
181  typename t::seq_alphabet, typename t::structure_alphabet>,
182  typename t::template structured_seq_alphabet<typename t::seq_alphabet, typename t::structure_alphabet>>;
183 // requires sequence_container
184 // <typename t::template structured_seq_container
185 // <typename t::template structured_seq_alphabet
186 // <typename t::seq_alphabet, typename t::structure_alphabet>>>;
187 
188  // energy: std::optional of floating point number
189  requires std::is_floating_point_v<typename t::energy_type::value_type>;
190 
191  // reactivity [error]
192  requires std::is_floating_point_v<typename t::react_type>;
194 
195  // comment
198 
199  // offset
201 };
203 
204 // ----------------------------------------------------------------------------
205 // structure_file_input_default_traits
206 // ----------------------------------------------------------------------------
207 
222 {
228  // sequence
229 
232 
235 
237  template <typename _seq_alphabet>
239 
240  // id
241 
243  using id_alphabet = char;
244 
246  template <typename _id_alphabet>
248 
249  // base pair probability structure
250 
252  using bpp_prob = double;
253 
255  using bpp_partner = size_t;
256 
258  template <typename _bpp_prob, typename _bpp_partner>
260 
262  template <typename _bpp_item>
264 
266  template <typename _bpp_queue>
268 
269  // fixed structure
270 
272  using structure_alphabet = wuss51;
273 
275  template <typename _structure_alphabet>
277 
278  // combined sequence and structure
279 
281  template <typename _seq_alphabet, typename _structure_alphabet>
283 
285  template <typename _structured_seq_alphabet>
287 
288  // energy
289 
292 
293  // reactivity [error]
294 
296  using react_type = double;
297 
299  template <typename _react_type>
301 
302  // comment
303 
305  using comment_alphabet = char;
306 
308  template <typename _comment_alphabet>
310 
311  // offset
312 
314  using offset_type = size_t;
316 };
317 
321 {
334  template <typename _seq_alphabet, typename _structure_alphabet>
337 };
338 
339 // ----------------------------------------------------------------------------
340 // structure_file_input
341 // ----------------------------------------------------------------------------
342 
358  detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::structure>,
359  detail::type_list_of_structure_file_input_formats valid_formats_ = type_list<format_vienna>>
361 {
362 public:
368  using traits_type = traits_type_;
370  using selected_field_ids = selected_field_ids_;
372  using valid_formats = valid_formats_;
374  using stream_char_type = char;
376 
381  field::id,
382  field::bpp,
386  field::react,
389  field::offset>;
390 
391  static_assert([]() constexpr
392  {
393  for (field f : selected_field_ids::as_array)
394  if (!field_ids::contains(f))
395  return false;
396  return true;
397  }(),
398  "You selected a field that is not valid for structure files, please refer to the documentation "
399  "of structure_file_input::field_ids for the accepted values.");
400 
401  static_assert([]() constexpr
402  {
406  }(), "You may not select field::structured_seq and either of field::seq and field::structure "
407  "at the same time.");
408 
415  using seq_type = typename traits_type::template seq_container<typename traits_type::seq_alphabet>;
417  using id_type = typename traits_type::template id_container<typename traits_type::id_alphabet>;
419  using bpp_type = typename traits_type::template bpp_container
420  <typename traits_type::template bpp_queue
421  <typename traits_type::template bpp_item
422  <typename traits_type::bpp_prob, typename traits_type::bpp_partner>>>;
424  using structure_type = typename traits_type::template structure_container
425  <typename traits_type::structure_alphabet>;
427  using structured_seq_type = typename traits_type::template structured_seq_container
428  <typename traits_type::template structured_seq_alphabet
429  <typename traits_type::seq_alphabet, typename traits_type::structure_alphabet>>;
431  using energy_type = typename traits_type::energy_type;
433  using react_type = typename traits_type::template react_container<typename traits_type::react_type>;
435  using comment_type = typename traits_type::template comment_container
436  <typename traits_type::comment_alphabet>;
438  using offset_type = typename traits_type::offset_type;
439 
443 
448 
458  using const_reference = void;
460  using size_type = size_t;
464  using iterator = detail::in_file_iterator<structure_file_input>;
466  using const_iterator = void;
468  using sentinel = std::default_sentinel_t;
470 
486 
504  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
505  primary_stream{new std::ifstream{}, stream_deleter_default}
506  {
507  primary_stream->rdbuf()->pubsetbuf(stream_buffer.data(), stream_buffer.size());
508  static_cast<std::basic_ifstream<char> *>(primary_stream.get())->open(filename,
509  std::ios_base::in | std::ios::binary);
510 
511  if (!primary_stream->good())
512  throw file_open_error{"Could not open file " + filename.string() + " for reading."};
513 
514  // possibly add intermediate decompression stream
515  secondary_stream = detail::make_secondary_istream(*primary_stream, filename);
516 
517  // initialise format handler
518  detail::set_format(format, filename);
519  }
520 
536  template <input_stream stream_t, structure_file_input_format file_format>
538  requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, char>
540  structure_file_input(stream_t & stream,
541  file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
542  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
543  primary_stream{&stream, stream_deleter_noop},
544  format{detail::structure_file_input_format_exposer<file_format>{}}
545  {
546  static_assert(list_traits::contains<file_format, valid_formats>,
547  "You selected a format that is not in the valid_formats of this file.");
548 
549  // possibly add intermediate decompression stream
550  secondary_stream = detail::make_secondary_istream(*primary_stream);
551  }
552 
554  template <input_stream stream_t, structure_file_input_format file_format>
556  requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, char>
558  structure_file_input(stream_t && stream,
559  file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
560  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
561  primary_stream{new stream_t{std::move(stream)}, stream_deleter_default},
562  format{detail::structure_file_input_format_exposer<file_format>{}}
563  {
564  static_assert(list_traits::contains<file_format, valid_formats>,
565  "You selected a format that is not in the valid_formats of this file.");
566 
567  // possibly add intermediate compression stream
568  secondary_stream = detail::make_secondary_istream(*primary_stream);
569  }
571 
591  {
592  // buffer first record
593  if (!first_record_was_read)
594  {
595  read_next_record();
596  first_record_was_read = true;
597  }
598 
599  return {*this};
600  }
601 
615  sentinel end() noexcept
616  {
617  return {};
618  }
619 
643  reference front() noexcept
644  {
645  return *begin();
646  }
648 
650  structure_file_input_options<typename traits_type::seq_legal_alphabet,
652 
653 protected:
655 
659  record_type record_buffer;
661  std::vector<char> stream_buffer{std::vector<char>(1'000'000)};
663 
671  static void stream_deleter_noop(std::basic_istream<stream_char_type> *) {}
673  static void stream_deleter_default(std::basic_istream<stream_char_type> * ptr) { delete ptr; }
674 
676  stream_ptr_t primary_stream{nullptr, stream_deleter_noop};
678  stream_ptr_t secondary_stream{nullptr, stream_deleter_noop};
679 
681  bool first_record_was_read{false};
683  bool at_end{false};
684 
686  using format_type = typename detail::variant_from_tags<valid_formats,
687  detail::structure_file_input_format_exposer>::type;
689  format_type format;
691 
693  void read_next_record()
694  {
695  // clear the record
696  record_buffer.clear();
697 
698  // at end if we could not read further
699  if ((std::istreambuf_iterator<stream_char_type>{*secondary_stream} ==
701  {
702  at_end = true;
703  return;
704  }
705 
706  assert(!format.valueless_by_exception());
707  std::visit([&] (auto & f)
708  {
709  // read new record
711  {
713  "You may not select field::structured_seq and field::structure at the same time.");
715  "You may not select field::structured_seq and field::seq at the same time.");
716  f.read_structure_record(*secondary_stream,
717  options,
718  detail::get_or_ignore<field::structured_seq>(record_buffer), // seq
719  detail::get_or_ignore<field::id>(record_buffer),
720  detail::get_or_ignore<field::bpp>(record_buffer),
721  detail::get_or_ignore<field::structured_seq>(record_buffer), // structure
722  detail::get_or_ignore<field::energy>(record_buffer),
723  detail::get_or_ignore<field::react>(record_buffer),
724  detail::get_or_ignore<field::react_err>(record_buffer),
725  detail::get_or_ignore<field::comment>(record_buffer),
726  detail::get_or_ignore<field::offset>(record_buffer));
727  }
728  else
729  {
730  f.read_structure_record(*secondary_stream,
731  options,
732  detail::get_or_ignore<field::seq>(record_buffer),
733  detail::get_or_ignore<field::id>(record_buffer),
734  detail::get_or_ignore<field::bpp>(record_buffer),
735  detail::get_or_ignore<field::structure>(record_buffer),
736  detail::get_or_ignore<field::energy>(record_buffer),
737  detail::get_or_ignore<field::react>(record_buffer),
738  detail::get_or_ignore<field::react_err>(record_buffer),
739  detail::get_or_ignore<field::comment>(record_buffer),
740  detail::get_or_ignore<field::offset>(record_buffer));
741  }
742  }, format);
743  }
744 
746  friend iterator;
747 };
748 
755 template <input_stream stream_type,
756  structure_file_input_format file_format,
757  detail::fields_specialisation selected_field_ids>
758 structure_file_input(stream_type && stream, file_format const &, selected_field_ids const &)
762 
764 template <input_stream stream_type,
765  structure_file_input_format file_format,
766  detail::fields_specialisation selected_field_ids>
767 structure_file_input(stream_type & stream, file_format const &, selected_field_ids const &)
772 
773 } // namespace seqan3
Provides seqan3::aa27, container aliases and string literals.
Provides alphabet adaptations for standard char types.
The twenty-seven letter amino acid alphabet.
Definition: aa27.hpp:46
The protein structure alphabet of the characters "HGIEBTSCX".
Definition: dssp9.hpp:63
The 15 letter RNA alphabet, containing all IUPAC smybols minus the gap.
Definition: rna15.hpp:51
The five letter RNA alphabet of A,C,G,U and the unknown character N.
Definition: rna5.hpp:49
A class for reading structured sequence files, e.g. Stockholm, Connect, Vienna, ViennaRNA bpp matrix ...
Definition: input.hpp:361
structure_file_input_options< typename traits_type::seq_legal_alphabet, selected_field_ids::contains(field::structured_seq)> options
The options are public and its members can be set directly.
Definition: input.hpp:651
reference front() noexcept
Return the record we are currently at in the file.
Definition: input.hpp:643
structure_file_input(structure_file_input const &)=delete
Copy construction is explicitly deleted, because you cannot have multiple access to the same file.
typename traits_type::template structure_container< typename traits_type::structure_alphabet > structure_type
The type of the structure field (default std::vector of seqan3::wuss51).
Definition: input.hpp:425
detail::in_file_iterator< structure_file_input > iterator
The iterator type of this view (an input iterator).
Definition: input.hpp:464
typename traits_type::template id_container< typename traits_type::id_alphabet > id_type
The type of the ID field (default std::string).
Definition: input.hpp:417
structure_file_input(stream_type &&stream, file_format const &, selected_field_ids const &) -> structure_file_input< typename structure_file_input<>::traits_type, selected_field_ids, type_list< file_format >>
Deduction of the selected fields, the file format and the stream type.
structure_file_input & operator=(structure_file_input const &)=delete
Copy assignment is explicitly deleted, because you cannot have multiple access to the same file.
structure_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 o...
Definition: input.hpp:558
size_t size_type
An unsigned integer type, usually std::size_t.
Definition: input.hpp:460
typename traits_type::template seq_container< typename traits_type::seq_alphabet > seq_type
The type of the sequence field (default std::vector of seqan3::rna5).
Definition: input.hpp:415
std::default_sentinel_t sentinel
The type returned by end().
Definition: input.hpp:468
structure_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: input.hpp:446
typename traits_type::template comment_container< typename traits_type::comment_alphabet > comment_type
The type of the comment field (default double).
Definition: input.hpp:436
char stream_char_type
Character type of the stream(s).
Definition: input.hpp:374
void const_reference
The const_reference type is void, because files are not const-iterable.
Definition: input.hpp:458
structure_file_input()=delete
Default constructor is explicitly deleted, you need to give a stream or file name.
structure_file_input(stream_type &stream, file_format const &, selected_field_ids const &) -> structure_file_input< typename structure_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 o...
traits_type_ traits_type
A traits type that defines aliases and template for storage of the fields.
Definition: input.hpp:368
void const_iterator
The const iterator type is void, because files are not const-iterable.
Definition: input.hpp:466
selected_field_ids_ selected_field_ids
A seqan3::fields list with the fields selected for the record.
Definition: input.hpp:370
structure_file_input & operator=(structure_file_input &&)=default
Move assignment is defaulted.
structure_file_input(structure_file_input &&)=default
Move construction is defaulted.
typename traits_type::template structured_seq_container< typename traits_type::template structured_seq_alphabet< typename traits_type::seq_alphabet, typename traits_type::structure_alphabet > > structured_seq_type
The type of the sequence-structure field (default std::vector of structured_rna<rna5,...
Definition: input.hpp:429
structure_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.
Definition: input.hpp:540
sentinel end() noexcept
Returns a sentinel for comparison with iterator.
Definition: input.hpp:615
iterator begin()
Returns an iterator to current position in the file.
Definition: input.hpp:590
valid_formats_ valid_formats
A seqan3::type_list with the possible formats.
Definition: input.hpp:372
typename traits_type::template bpp_container< typename traits_type::template bpp_queue< typename traits_type::template bpp_item< typename traits_type::bpp_prob, typename traits_type::bpp_partner > >> bpp_type
The type of the base pair probabilies (default std::vector of std::set<std::pair<double,...
Definition: input.hpp:422
typename traits_type::energy_type energy_type
The type of the energy field (default double).
Definition: input.hpp:431
typename traits_type::offset_type offset_type
The type of the offset field (default size_t).
Definition: input.hpp:438
structure_file_input(std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{})
Construct from filename.
Definition: input.hpp:503
~structure_file_input()=default
Destructor is defaulted.
typename traits_type::template react_container< typename traits_type::react_type > react_type
The type of the reactivity and reactivity error fields (default double).
Definition: input.hpp:433
A seqan3::alphabet_tuple_base that joins an aminoacid alphabet with a protein structure alphabet.
Definition: structured_aa.hpp:56
A seqan3::alphabet_tuple_base that joins a nucleotide alphabet with an RNA structure alphabet.
Definition: structured_rna.hpp:57
T data(T... args)
Provides the dssp format for protein structure.
The <filesystem> header from C++17's standard library.
Provides the seqan3::format_vienna.
T get(T... args)
field
An enumerator for the fields used in file formats.
Definition: record.hpp:63
@ energy
Energy of a folded sequence, represented by one float number.
@ comment
Comment field of arbitrary content, usually a string.
@ structure
Fixed interactions, usually a string of structure alphabet characters.
@ bpp
Base pair probability matrix of interactions, usually a matrix of float numbers.
@ react
Reactivity values of the sequence characters given in a vector of float numbers.
@ react_err
Reactivity error values given in a vector corresponding to seqan3::field::react.
@ offset
Sequence (seqan3::field::seq) relative start position (0-based), unsigned value.
@ structured_seq
Sequence and fixed interactions combined in one range.
@ id
The identifier, usually a string.
@ seq
The "sequence", usually a range of nucleotides or amino acids.
constexpr bool contains
Whether a type occurs in a type list or not.
Definition: traits.hpp:231
Provides the seqan3::detail::in_file_iterator class template.
Resolves to std::ranges::explicitly_convertible_to<type1, type2>().
A concept that indicates whether an alphabet represents RNA structure.
A more refined container concept than seqan3::container.
The generic concept for structure file in formats.
The requirements a traits_type for seqan3::structure_file_input must meet.
Refines seqan3::alphabet and adds assignability.
Provides exceptions used in the I/O module.
Stream concepts.
T is_base_of_v
Provides various utility functions required only for input.
The main SeqAn3 namespace.
Definition: aligned_sequence_concept.hpp:29
Provides seqan3::rna15, container aliases and string literals.
Provides seqan3::rna5, container aliases and string literals.
T size(T... args)
A class template that holds a choice of seqan3::field.
Definition: record.hpp:128
void clear() noexcept(noexcept(std::apply(expander, std::declval< record & >())))
Clears containers that provide .clear() and (re-)initialises all other elements with = {}.
Definition: record.hpp:235
A traits type that specifies input as amino acids.
Definition: input.hpp:321
The default traits for seqan3::structure_file_input.
Definition: input.hpp:222
wuss51 structure_alphabet
The alphabet for a structure annotation is seqan3::phred42.
Definition: input.hpp:272
size_t offset_type
The type of the offset is size_t.
Definition: input.hpp:314
double bpp_prob
The type for a base pair probability is double.
Definition: input.hpp:252
char id_alphabet
The alphabet for an identifier string is char.
Definition: input.hpp:243
char comment_alphabet
The alphabet for a comment string is char.
Definition: input.hpp:305
double react_type
The type of the reactivity and reactivity error is double.
Definition: input.hpp:296
size_t bpp_partner
The type for the partner position of a base pair probability is size_t.
Definition: input.hpp:255
The options type defines various option members that influence the behaviour of all or some formats.
Definition: input_options.hpp:30
Type that contains multiple types.
Definition: type_list.hpp:29
Provides seqan3::structure_file_input_format.
Provides seqan3::structure_file_input_options.
Provides seqan3::structure_record.
Provides the composite of aminoacid with structure alphabets.
Provides traits for seqan3::type_list.
Adaptations of concepts from the standard library.
T visit(T... args)