SeqAn3  3.2.0
The Modern C++ library for sequence analysis.
format_fastq.hpp
Go to the documentation of this file.
1 // -----------------------------------------------------------------------------------------------------
2 // Copyright (c) 2006-2022, Knut Reinert & Freie Universität Berlin
3 // Copyright (c) 2016-2022, 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 <algorithm>
16 #include <iterator>
17 #include <ranges>
18 #include <string>
19 #include <string_view>
20 #include <vector>
21 
43 
44 namespace seqan3
45 {
46 
79 {
80 public:
84  format_fastq() noexcept = default;
85  format_fastq(format_fastq const &) noexcept = default;
86  format_fastq & operator=(format_fastq const &) noexcept = default;
87  format_fastq(format_fastq &&) noexcept = default;
88  format_fastq & operator=(format_fastq &&) noexcept = default;
89  ~format_fastq() noexcept = default;
90 
92 
94  static inline std::vector<std::string> file_extensions{{"fastq"}, {"fq"}};
95 
96 protected:
98  template <typename stream_type, // constraints checked by file
99  typename seq_legal_alph_type,
100  typename stream_pos_type,
101  typename seq_type, // other constraints checked inside function
102  typename id_type,
103  typename qual_type>
104  void read_sequence_record(stream_type & stream,
106  stream_pos_type & position_buffer,
107  seq_type & sequence,
108  id_type & id,
109  qual_type & qualities)
110  {
111  auto stream_view = detail::istreambuf(stream);
112  auto stream_it = begin(stream_view);
113 
114  // cache the begin position so we write quals to the same position as seq in seq_qual case
115  size_t sequence_size_before = 0;
116  size_t sequence_size_after = 0;
117  if constexpr (!detail::decays_to_ignore_v<seq_type>)
118  sequence_size_before = size(sequence);
119  position_buffer = stream.tellg();
120 
121  /* ID */
122  if (*stream_it != '@') // [[unlikely]]
123  {
124  throw parse_error{std::string{"Expected '@' on beginning of ID line, got: "}
125  + detail::make_printable(*stream_it)};
126  }
127  ++stream_it; // skip '@'
128 
129  if constexpr (!detail::decays_to_ignore_v<id_type>)
130  {
131  if (options.truncate_ids)
132  {
133  std::ranges::copy(stream_view | detail::take_until_or_throw(is_cntrl || is_blank)
134  | views::char_to<std::ranges::range_value_t<id_type>>,
135  std::back_inserter(id));
136  detail::consume(stream_view | detail::take_line_or_throw);
137  }
138  else
139  {
140  std::ranges::copy(stream_view | detail::take_line_or_throw
141  | views::char_to<std::ranges::range_value_t<id_type>>,
142  std::back_inserter(id));
143  }
144  }
145  else
146  {
147  detail::consume(stream_view | detail::take_line_or_throw);
148  }
149 
150  /* Sequence */
151  auto seq_view = stream_view | detail::take_until_or_throw(is_char<'+'>) // until 2nd ID line
152  | std::views::filter(!is_space); // ignore whitespace
153  if constexpr (!detail::decays_to_ignore_v<seq_type>)
154  {
155  constexpr auto is_legal_alph = char_is_valid_for<seq_legal_alph_type>;
156  std::ranges::copy(
157  seq_view
159  [is_legal_alph](char const c) // enforce legal alphabet
160  {
161  if (!is_legal_alph(c))
162  {
163  throw parse_error{std::string{"Encountered an unexpected letter: "}
164  + "char_is_valid_for<"
165  + detail::type_name_as_string<seq_legal_alph_type>
166  + "> evaluated to false on " + detail::make_printable(c)};
167  }
168  return c;
169  })
170  | views::char_to<std::ranges::range_value_t<seq_type>>, // convert to actual target alphabet
172  sequence_size_after = size(sequence);
173  }
174  else // consume, but count
175  {
176  auto it = begin(seq_view);
177  auto it_end = end(seq_view);
178  while (it != it_end)
179  {
180  ++it;
181  ++sequence_size_after;
182  }
183  }
184 
185  detail::consume(stream_view | detail::take_line_or_throw);
186 
187  /* Qualities */
188  auto qview = stream_view | std::views::filter(!is_space) // this consumes trailing newline
189  | detail::take_exactly_or_throw(sequence_size_after - sequence_size_before);
190  if constexpr (!detail::decays_to_ignore_v<qual_type>)
191  {
192  std::ranges::copy(qview | views::char_to<std::ranges::range_value_t<qual_type>>,
193  std::back_inserter(qualities));
194  }
195  else
196  {
197  detail::consume(qview);
198  }
199  }
200 
202  template <typename stream_type, // constraints checked by file
203  typename seq_type, // other constraints checked inside function
204  typename id_type,
205  typename qual_type>
206  void write_sequence_record(stream_type & stream,
207  sequence_file_output_options const & options,
208  seq_type && sequence,
209  id_type && id,
210  qual_type && qualities)
211  {
212  seqan3::detail::fast_ostreambuf_iterator stream_it{*stream.rdbuf()};
213 
214  // ID
215  if constexpr (detail::decays_to_ignore_v<id_type>)
216  {
217  throw std::logic_error{"The ID field may not be set to ignore when writing FASTQ files."};
218  }
219  else
220  {
221  if (std::ranges::empty(id)) //[[unlikely]]
222  throw std::runtime_error{"The ID field may not be empty when writing FASTQ files."};
223 
224  stream_it = '@';
225  stream_it.write_range(id);
226  stream_it.write_end_of_line(options.add_carriage_return);
227  }
228 
229  // Sequence
230  if constexpr (detail::decays_to_ignore_v<seq_type>)
231  {
232  throw std::logic_error{
233  "The SEQ and SEQ_QUAL fields may not both be set to ignore when writing FASTQ files."};
234  }
235  else
236  {
237  if (std::ranges::empty(sequence)) //[[unlikely]]
238  throw std::runtime_error{"The SEQ field may not be empty when writing FASTQ files."};
239 
240  stream_it.write_range(sequence | views::to_char);
241  stream_it.write_end_of_line(options.add_carriage_return);
242  }
243 
244  // 2nd ID-line
245  if constexpr (!detail::decays_to_ignore_v<id_type>)
246  {
247  stream_it = '+';
248 
249  if (options.fastq_double_id)
250  stream_it.write_range(id);
251 
252  stream_it.write_end_of_line(options.add_carriage_return);
253  }
254 
255  // Quality line
256  if constexpr (detail::decays_to_ignore_v<qual_type>)
257  {
258  throw std::logic_error{
259  "The QUAL and SEQ_QUAL fields may not both be set to ignore when writing FASTQ files."};
260  }
261  else
262  {
263  if (std::ranges::empty(qualities)) //[[unlikely]]
264  throw std::runtime_error{"The SEQ field may not be empty when writing FASTQ files."};
265 
266  if constexpr (std::ranges::sized_range<seq_type> && std::ranges::sized_range<qual_type>)
267  {
268  assert(std::ranges::size(sequence) == std::ranges::size(qualities));
269  }
270 
271  stream_it.write_range(qualities | views::to_char);
272  stream_it.write_end_of_line(options.add_carriage_return);
273  }
274  }
275 };
276 
277 } // namespace seqan3
Provides aliases for qualified.
Core alphabet concept and free function/type trait wrappers.
T back_inserter(T... args)
Provides alphabet adaptations for standard char types.
Provides seqan3::views::char_to.
The FASTQ format.
Definition: format_fastq.hpp:79
void read_sequence_record(stream_type &stream, sequence_file_input_options< seq_legal_alph_type > const &options, stream_pos_type &position_buffer, seq_type &sequence, id_type &id, qual_type &qualities)
Read from the specified stream and back-insert into the given field buffers.
Definition: format_fastq.hpp:104
format_fastq() noexcept=default
Defaulted.
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_fastq.hpp:206
static std::vector< std::string > file_extensions
The valid file extensions for this format; note that you can modify this value.
Definition: format_fastq.hpp:94
Provides various utility functions.
Provides various transformation traits used by the range module.
Provides seqan3::dna5, container aliases and string literals.
Provides seqan3::detail::fast_ostreambuf_iterator.
auto const to_char
A view that calls seqan3::to_char() on each element in the input range.
Definition: to_char.hpp:63
auto const char_to
A view over an alphabet, given a range of characters.
Definition: char_to.hpp:67
constexpr auto is_blank
Checks whether c is a blank character.
Definition: predicate.hpp:142
constexpr auto is_space
Checks whether c is a space character.
Definition: predicate.hpp:125
constexpr auto is_cntrl
Checks whether c is a control character.
Definition: predicate.hpp:90
decltype(detail::transform< trait_t >(list_t{})) transform
Apply a transformation trait to every type in the list and return a seqan3::type_list of the results.
Definition: type_list/traits.hpp:469
constexpr size_t size
The size of a type pack.
Definition: type_pack/traits.hpp:146
Provides seqan3::detail::ignore_output_iterator for writing to null stream.
The generic concept for a (biological) sequence.
Provides various utility functions.
Provides seqan3::detail::istreambuf.
The main SeqAn3 namespace.
Definition: aligned_sequence_concept.hpp:29
SeqAn specific customisations in the standard namespace.
Provides character predicates for tokenisation.
The <ranges> header from C++20's standard library.
Provides seqan3::sequence_file_input_format and auxiliary classes.
Provides seqan3::sequence_file_input_options.
Provides seqan3::sequence_file_output_format and auxiliary classes.
Provides seqan3::sequence_file_output_options.
Thrown if there is a parse error, such as reading an unexpected character from an input stream.
Definition: io/exception.hpp:48
The options type defines various option members that influence the behaviour of all or some formats.
Definition: sequence_file/input_options.hpp:27
bool truncate_ids
Read the ID string only up until the first whitespace character.
Definition: sequence_file/input_options.hpp:29
The options type defines various option members that influence the behaviour of all or some formats.
Definition: sequence_file/output_options.hpp:26
bool add_carriage_return
The default plain text line-ending is "\n", but on Windows an additional carriage return is recommend...
Definition: sequence_file/output_options.hpp:42
bool fastq_double_id
Whether to write the ID only '@' or also after '+' line.
Definition: sequence_file/output_options.hpp:37
Provides seqan3::views::take_exactly and seqan3::views::take_exactly_or_throw.
Provides seqan3::detail::take_line and seqan3::detail::take_line_or_throw.
Provides seqan3::views::take_until and seqan3::views::take_until_or_throw.
Provides seqan3::views::to_char.
Provides traits to inspect some information of a type, for example its name.