SeqAn3  3.0.1
The Modern C++ library for sequence analysis.
format_fasta.hpp
Go to the documentation of this file.
1 // -----------------------------------------------------------------------------------------------------
2 // Copyright (c) 2006-2020, Knut Reinert & Freie Universität Berlin
3 // Copyright (c) 2016-2020, 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 <iterator>
16 #include <string>
17 #include <string_view>
18 #include <vector>
19 
20 #include <seqan3/alphabet/adaptation/char.hpp>
21 #include <seqan3/alphabet/nucleotide/dna5.hpp>
22 #include <seqan3/alphabet/quality/aliases.hpp>
23 #include <seqan3/core/char_operations/predicate.hpp>
24 #include <seqan3/core/type_traits/range.hpp>
25 #include <seqan3/io/detail/ignore_output_iterator.hpp>
26 #include <seqan3/io/detail/misc.hpp>
27 #include <seqan3/io/sequence_file/input_format_concept.hpp>
28 #include <seqan3/io/sequence_file/input_options.hpp>
29 #include <seqan3/io/sequence_file/output_format_concept.hpp>
30 #include <seqan3/io/sequence_file/output_options.hpp>
31 #include <seqan3/io/stream/iterator.hpp>
32 #include <seqan3/range/shortcuts.hpp>
33 #include <seqan3/range/detail/misc.hpp>
34 #include <seqan3/range/views/char_to.hpp>
35 #include <seqan3/range/views/istreambuf.hpp>
36 #include <seqan3/range/views/join.hpp>
37 #include <seqan3/range/views/to_char.hpp>
38 #include <seqan3/range/views/take.hpp>
39 #include <seqan3/range/views/take_exactly.hpp>
40 #include <seqan3/range/views/take_line.hpp>
41 #include <seqan3/range/views/take_until.hpp>
42 #include <seqan3/std/algorithm>
43 #include <seqan3/std/ranges>
44 
45 namespace seqan3
46 {
47 
80 class format_fasta
81 {
82 public:
86  format_fasta() noexcept = default;
87  format_fasta(format_fasta const &) noexcept = default;
88  format_fasta & operator=(format_fasta const &) noexcept = default;
89  format_fasta(format_fasta &&) noexcept = default;
90  format_fasta & operator=(format_fasta &&) noexcept = default;
91  ~format_fasta() noexcept = default;
92 
95  static inline std::vector<std::string> file_extensions
96  {
97  { "fasta" },
98  { "fa" },
99  { "fna" },
100  { "ffn" },
101  { "faa" },
102  { "frn" },
103  };
104 
105 protected:
107  template <typename stream_type, // constraints checked by file
108  typename legal_alph_type, bool seq_qual_combined,
109  typename seq_type, // other constraints checked inside function
110  typename id_type,
111  typename qual_type>
112  void read_sequence_record(stream_type & stream,
113  sequence_file_input_options<legal_alph_type, seq_qual_combined> const & options,
114  seq_type & sequence,
115  id_type & id,
116  qual_type & SEQAN3_DOXYGEN_ONLY(qualities))
117  {
118  auto stream_view = views::istreambuf(stream);
119 
120  // ID
121  read_id(stream_view, options, id);
122 
123  // Sequence
124  read_seq(stream_view, options, sequence);
125  }
126 
128  template <typename stream_type, // constraints checked by file
129  typename seq_type, // other constraints checked inside function
130  typename id_type,
131  typename qual_type>
132  void write_sequence_record(stream_type & stream,
133  sequence_file_output_options const & options,
134  seq_type && sequence,
135  id_type && id,
136  qual_type && SEQAN3_DOXYGEN_ONLY(qualities))
137  {
138  seqan3::ostreambuf_iterator stream_it{stream};
139 
140  // ID
141  if constexpr (detail::decays_to_ignore_v<id_type>)
142  {
143  throw std::logic_error{"The ID field may not be set to ignore when writing FASTA files."};
144  }
145  else
146  {
147  if (empty(id)) //[[unlikely]]
148  throw std::runtime_error{"The ID field may not be empty when writing FASTA files."};
149 
150  write_id(stream_it, options, id);
151  }
152 
153  // Sequence
154  if constexpr (detail::decays_to_ignore_v<seq_type>) // sequence
155  {
156  throw std::logic_error{"The SEQ and SEQ_QUAL fields may not both be set to ignore when writing FASTA files."};
157  }
158  else
159  {
160  if (empty(sequence)) //[[unlikely]]
161  throw std::runtime_error{"The SEQ field may not be empty when writing FASTA files."};
162 
163  write_seq(stream_it, options, sequence);
164  }
165  }
166 
167 private:
170  template <typename stream_view_t,
171  typename seq_legal_alph_type, bool seq_qual_combined,
172  typename id_type>
173  void read_id(stream_view_t & stream_view,
174  sequence_file_input_options<seq_legal_alph_type, seq_qual_combined> const & options,
175  id_type & id)
176  {
177  auto const is_id = is_char<'>'> || is_char<';'>;
178 
179  if (!is_id(*begin(stream_view)))
180  throw parse_error{std::string{"Expected to be on beginning of ID, but "} + is_id.msg +
181  " evaluated to false on " + detail::make_printable(*begin(stream_view))};
182 
183  // read id
184  if constexpr (!detail::decays_to_ignore_v<id_type>)
185  {
186  if (options.truncate_ids)
187  {
188  #if SEQAN3_WORKAROUND_VIEW_PERFORMANCE
189  auto it = stream_view.begin();
190  auto e = stream_view.end();
191  for (; (it != e) && (is_id || is_blank)(*it); ++it)
192  {}
193 
194  bool at_delimiter = false;
195  for (; it != e; ++it)
196  {
197  if ((is_cntrl || is_blank)(*it))
198  {
199  at_delimiter = true;
200  break;
201  }
202  id.push_back(assign_char_to(*it, value_type_t<id_type>{}));
203  }
204 
205  if (!at_delimiter)
206  throw unexpected_end_of_input{"FastA ID line did not end in newline."};
207 
208  for (; (it != e) && ((!is_char<'\n'>)(*it)); ++it)
209  {}
210 
211  #else // ↑↑↑ WORKAROUND | ORIGINAL ↓↓↓
212 
213  std::ranges::copy(stream_view | std::views::drop_while(is_id || is_blank) // skip leading >
214  | views::take_until_or_throw(is_cntrl || is_blank) // read ID until delimiter…
215  | views::char_to<value_type_t<id_type>>,
216  std::ranges::back_inserter(id)); // … ^A is old delimiter
217 
218  // consume rest of line
219  detail::consume(stream_view | views::take_line_or_throw);
220  #endif // SEQAN3_WORKAROUND_VIEW_PERFORMANCE
221 
222  }
223  else
224  {
225  #if SEQAN3_WORKAROUND_VIEW_PERFORMANCE
226  auto it = stream_view.begin();
227  auto e = stream_view.end();
228  for (; (it != e) && (is_id || is_blank)(*it); ++it)
229  {}
230 
231  bool at_delimiter = false;
232  for (; it != e; ++it)
233  {
234  if ((is_char<'\n'>)(*it))
235  {
236  at_delimiter = true;
237  break;
238  }
239  id.push_back(assign_char_to(*it, value_type_t<id_type>{}));
240  }
241 
242  if (!at_delimiter)
243  throw unexpected_end_of_input{"FastA ID line did not end in newline."};
244 
245  #else // ↑↑↑ WORKAROUND | ORIGINAL ↓↓↓
246 
247  std::ranges::copy(stream_view | views::take_line_or_throw // read line
248  | std::views::drop_while(is_id || is_blank) // skip leading >
249  | views::char_to<value_type_t<id_type>>,
250  std::ranges::back_inserter(id));
251  #endif // SEQAN3_WORKAROUND_VIEW_PERFORMANCE
252  }
253  }
254  else
255  {
256  detail::consume(stream_view | views::take_line_or_throw);
257  }
258  }
259 
261  template <typename stream_view_t,
262  typename seq_legal_alph_type, bool seq_qual_combined,
263  typename seq_type>
264  void read_seq(stream_view_t & stream_view,
265  sequence_file_input_options<seq_legal_alph_type, seq_qual_combined> const &,
266  seq_type & seq)
267  {
268  auto constexpr is_id = is_char<'>'> || is_char<';'>;
269 
270  if constexpr (!detail::decays_to_ignore_v<seq_type>)
271  {
272  auto constexpr not_in_alph = !is_in_alphabet<seq_legal_alph_type>;
273 
274  #if SEQAN3_WORKAROUND_VIEW_PERFORMANCE
275  auto it = stream_view.begin();
276  auto e = stream_view.end();
277  for (; (it != e) && ((!is_id)(*it)); ++it)
278  {
279  if ((is_space || is_digit)(*it))
280  continue;
281  else if (not_in_alph(*it))
282  {
283  throw parse_error{std::string{"Encountered an unexpected letter: "} +
284  not_in_alph.msg +
285  " evaluated to true on " +
286  detail::make_printable(*it)};
287  }
288 
289  seq.push_back(assign_char_to(*it, value_type_t<seq_type>{}));
290  }
291 
292  #else // ↑↑↑ WORKAROUND | ORIGINAL ↓↓↓
293 
294  std::ranges::copy(stream_view | views::take_until(is_id) // until next header (or end)
295  | std::views::filter(!(is_space || is_digit))// ignore whitespace and numbers
296  | std::views::transform([not_in_alph] (char const c)
297  {
298  if (not_in_alph(c))
299  {
300  throw parse_error{std::string{"Encountered an unexpected letter: "} +
301  not_in_alph.msg +
302  " evaluated to false on " +
303  detail::make_printable(c)};
304  }
305  return c;
306  }) // enforce legal alphabet
307  | views::char_to<value_type_t<seq_type>>, // convert to actual target alphabet
308  std::ranges::back_inserter(seq));
309  #endif // SEQAN3_WORKAROUND_VIEW_PERFORMANCE
310  }
311  else
312  {
313  detail::consume(stream_view | views::take_until(is_id));
314  }
315  }
316 
318  template <typename stream_it_t,
319  typename id_type>
320  void write_id(stream_it_t & stream_it,
321  sequence_file_output_options const & options,
322  id_type && id)
323  {
324  if (options.fasta_legacy_id_marker)
325  stream_it = ';';
326  else
327  stream_it = '>';
328 
329  if (options.fasta_blank_before_id)
330  stream_it = ' ';
331 
332  std::ranges::copy(id, stream_it);
333 
334  detail::write_eol(stream_it, options.add_carriage_return);
335  }
336 
338  template <typename stream_it_t,
339  typename seq_type>
340  void write_seq(stream_it_t & stream_it,
341  sequence_file_output_options const & options,
342  seq_type && seq)
343  {
344  if (options.fasta_letters_per_line > 0)
345  {
346  #if SEQAN3_WORKAROUND_VIEW_PERFORMANCE
347  size_t count = 0;
348  for (auto c : seq)
349  {
350  stream_it = to_char(c);
351  if (++count % options.fasta_letters_per_line == 0)
352  detail::write_eol(stream_it, options.add_carriage_return);
353  }
354  if (count % options.fasta_letters_per_line != 0)
355  detail::write_eol(stream_it, options.add_carriage_return);
356 
357  #else // ↑↑↑ WORKAROUND | ORIGINAL ↓↓↓
358 
359  //TODO: combining chunk and join is substantially faster than views::interleave (2.5x), why?
360  std::ranges::copy(seq | views::to_char
361  | ranges::view::chunk(options.fasta_letters_per_line)
362  | views::join(options.add_carriage_return
363  ? std::string_view{"\r\n"}
364  : std::string_view{"\n"}),
365  stream_it);
366  detail::write_eol(stream_it, options.add_carriage_return);
367  #endif // SEQAN3_WORKAROUND_VIEW_PERFORMANCE
368  }
369  else
370  {
371  // No performance workaround here, because transform views alone are fast
372  std::ranges::copy(seq | views::to_char, stream_it);
373  detail::write_eol(stream_it, options.add_carriage_return);
374  }
375  }
376 };
377 
378 } // namespace seqan
shortcuts.hpp
Provides various shortcuts for common std::ranges functions.
take_until.hpp
Provides seqan3::views::take_until and seqan3::views::take_until_or_throw.
input_format_concept.hpp
Provides seqan3::sequence_file_input_format and auxiliary classes.
seqan3::format_fasta::file_extensions
static std::vector< std::string > file_extensions
The valid file extensions for this format; note that you can modify this value.
Definition: format_fasta.hpp:96
vector
seqan3::format_fasta
The FastA format.
Definition: format_fasta.hpp:80
algorithm
Adaptations of algorithms from the Ranges TS.
seqan3::format_fasta::~format_fasta
~format_fasta() noexcept=default
seqan3::sequence_file_input_options
The options type defines various option members that influence the behaviour of all or some formats.
Definition: input_options.hpp:25
seqan3::format_fasta::format_fasta
format_fasta() noexcept=default
Defaulted.
range.hpp
Provides various transformation traits used by the range module.
dna5.hpp
Provides seqan3::dna5, container aliases and string literals.
seqan3::ostreambuf_iterator
::ranges::ostreambuf_iterator ostreambuf_iterator
Alias for ranges::ostreambuf_iterator. Writes successive characters onto the output stream from which...
Definition: iterator.hpp:204
seqan3
The main SeqAn3 namespace.
Definition: aligned_sequence_concept.hpp:36
std::runtime_error
seqan3::sequence_file_output_options
The options type defines various option members that influence the behaviour of all or some formats.
Definition: output_options.hpp:21
std::logic_error
output_options.hpp
Provides seqan3::sequence_file_output_options.
join.hpp
Provides seqan3::views::join.
output_format_concept.hpp
Provides seqan3::SequenceFileFormatOut and auxiliary classes.
char.hpp
Provides alphabet adaptations for standard char types.
to_char.hpp
Provides seqan3::views::to_char.
seqan3::format_fasta::write_sequence_record
void write_sequence_record(stream_type &stream, sequence_file_output_options const &options, seq_type &&sequence, id_type &&id, qual_type &&qualities)
Write the given fields to the specified stream.
Definition: format_fasta.hpp:132
take.hpp
Provides seqan3::views::take.
ranges
Adaptations of concepts from the Ranges TS.
take_exactly.hpp
Provides seqan3::views::take_exactly and seqan3::views::take_exactly_or_throw.
seqan3::format_fasta::operator=
format_fasta & operator=(format_fasta const &) noexcept=default
Defaulted.
predicate.hpp
Provides character predicates for tokenisation.
input_options.hpp
Provides seqan3::sequence_file_input_options.
ignore_output_iterator.hpp
Provides seqan3::detail::ignore_output_iterator for writing to null stream.
aliases.hpp
Provides aliases for qualified.
istreambuf.hpp
Provides seqan3::views::istreambuf.
take_line.hpp
Provides seqan3::views::take_line and seqan3::views::take_line_or_throw.
iterator.hpp
Provides seqan3::ostream and seqan3::ostreambuf iterator.
seqan3::format_fasta::read_sequence_record
void read_sequence_record(stream_type &stream, sequence_file_input_options< legal_alph_type, seq_qual_combined > const &options, seq_type &sequence, id_type &id, qual_type &qualities)
Read from the specified stream and back-insert into the given field buffers.
Definition: format_fasta.hpp:112
misc.hpp
Provides various utility functions.
misc.hpp
Provides various utility functions.
string_view
char_to.hpp
Provides seqan3::views::char_to.
seqan3::views::istreambuf
constexpr auto istreambuf
A view factory that returns a view over the stream buffer of an input stream.
Definition: istreambuf.hpp:113
string