SeqAn3  3.1.0
The Modern C++ library for sequence analysis.
format_fastq.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 <seqan3/std/algorithm>
16 #include <iterator>
17 #include <seqan3/std/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
95  {
96  { "fastq" },
97  { "fq" }
98  };
99 
100 protected:
102  template <typename stream_type, // constraints checked by file
103  typename seq_legal_alph_type,
104  typename seq_type, // other constraints checked inside function
105  typename id_type,
106  typename qual_type>
107  void read_sequence_record(stream_type & stream,
109  seq_type & sequence,
110  id_type & id,
111  qual_type & qualities)
112  {
113  auto stream_view = detail::istreambuf(stream);
114  auto stream_it = begin(stream_view);
115 
116  // cache the begin position so we write quals to the same position as seq in seq_qual case
117  size_t sequence_size_before = 0;
118  size_t sequence_size_after = 0;
119  if constexpr (!detail::decays_to_ignore_v<seq_type>)
120  sequence_size_before = size(sequence);
121 
122  /* ID */
123  if (*stream_it != '@') // [[unlikely]]
124  {
125  throw parse_error{std::string{"Expected '@' on beginning of ID line, got: "} +
126  detail::make_printable(*stream_it)};
127  }
128  ++stream_it; // skip '@'
129 
130  if constexpr (!detail::decays_to_ignore_v<id_type>)
131  {
132  if (options.truncate_ids)
133  {
134  std::ranges::copy(stream_view | detail::take_until_or_throw(is_cntrl || is_blank)
135  | views::char_to<std::ranges::range_value_t<id_type>>,
136  std::cpp20::back_inserter(id));
137  detail::consume(stream_view | detail::take_line_or_throw);
138  }
139  else
140  {
141  std::ranges::copy(stream_view | detail::take_line_or_throw
142  | views::char_to<std::ranges::range_value_t<id_type>>,
143  std::cpp20::back_inserter(id));
144  }
145  }
146  else
147  {
148  detail::consume(stream_view | detail::take_line_or_throw);
149  }
150 
151  /* Sequence */
152  auto seq_view = stream_view | detail::take_until_or_throw(is_char<'+'>) // until 2nd ID line
153  | std::views::filter(!is_space); // ignore whitespace
154  if constexpr (!detail::decays_to_ignore_v<seq_type>)
155  {
156  auto constexpr is_legal_alph = char_is_valid_for<seq_legal_alph_type>;
157  std::ranges::copy(seq_view | std::views::transform([is_legal_alph] (char const c) // enforce legal alphabet
158  {
159  if (!is_legal_alph(c))
160  {
161  throw parse_error{std::string{"Encountered an unexpected letter: "} +
162  "char_is_valid_for<" +
163  detail::type_name_as_string<seq_legal_alph_type> +
164  "> evaluated to false on " +
165  detail::make_printable(c)};
166  }
167  return c;
168  })
169  | views::char_to<std::ranges::range_value_t<seq_type>>, // convert to actual target alphabet
170  std::cpp20::back_inserter(sequence));
171  sequence_size_after = size(sequence);
172  }
173  else // consume, but count
174  {
175  auto it = begin(seq_view);
176  auto it_end = end(seq_view);
177  while (it != it_end)
178  {
179  ++it;
180  ++sequence_size_after;
181  }
182  }
183 
184  detail::consume(stream_view | detail::take_line_or_throw);
185 
186  /* Qualities */
187  auto qview = stream_view | std::views::filter(!is_space) // this consumes trailing newline
188  | detail::take_exactly_or_throw(sequence_size_after - sequence_size_before);
189  if constexpr (!detail::decays_to_ignore_v<qual_type>)
190  {
191  std::ranges::copy(qview | views::char_to<std::ranges::range_value_t<qual_type>>,
192  std::cpp20::back_inserter(qualities));
193  }
194  else
195  {
196  detail::consume(qview);
197  }
198  }
199 
201  template <typename stream_type, // constraints checked by file
202  typename seq_type, // other constraints checked inside function
203  typename id_type,
204  typename qual_type>
205  void write_sequence_record(stream_type & stream,
206  sequence_file_output_options const & options,
207  seq_type && sequence,
208  id_type && id,
209  qual_type && qualities)
210  {
211  seqan3::detail::fast_ostreambuf_iterator stream_it{*stream.rdbuf()};
212 
213  // ID
214  if constexpr (detail::decays_to_ignore_v<id_type>)
215  {
216  throw std::logic_error{"The ID field may not be set to ignore when writing FASTQ files."};
217  }
218  else
219  {
220  if (std::ranges::empty(id)) //[[unlikely]]
221  throw std::runtime_error{"The ID field may not be empty when writing FASTQ files."};
222 
223  stream_it = '@';
224  stream_it.write_range(id);
225  stream_it.write_end_of_line(options.add_carriage_return);
226  }
227 
228  // Sequence
229  if constexpr (detail::decays_to_ignore_v<seq_type>)
230  {
231  throw std::logic_error{"The SEQ and SEQ_QUAL fields may not both be set to ignore when writing FASTQ files."};
232  }
233  else
234  {
235  if (std::ranges::empty(sequence)) //[[unlikely]]
236  throw std::runtime_error{"The SEQ field may not be empty when writing FASTQ files."};
237 
238  stream_it.write_range(sequence | views::to_char);
239  stream_it.write_end_of_line(options.add_carriage_return);
240  }
241 
242  // 2nd ID-line
243  if constexpr (!detail::decays_to_ignore_v<id_type>)
244  {
245  stream_it = '+';
246 
247  if (options.fastq_double_id)
248  stream_it.write_range(id);
249 
250  stream_it.write_end_of_line(options.add_carriage_return);
251  }
252 
253  // Quality line
254  if constexpr (detail::decays_to_ignore_v<qual_type>)
255  {
256  throw std::logic_error{"The QUAL and SEQ_QUAL fields may not both be set to ignore when writing FASTQ files."};
257  }
258  else
259  {
260  if (std::ranges::empty(qualities)) //[[unlikely]]
261  throw std::runtime_error{"The SEQ field may not be empty when writing FASTQ files."};
262 
263  if constexpr (std::ranges::sized_range<seq_type> && std::ranges::sized_range<qual_type>)
264  {
265  assert(std::ranges::size(sequence) == std::ranges::size(qualities));
266  }
267 
268  stream_it.write_range(qualities | views::to_char);
269  stream_it.write_end_of_line(options.add_carriage_return);
270  }
271  }
272 };
273 
274 } // namespace seqan
The <algorithm> header from C++20's standard library.
Provides aliases for qualified.
Core alphabet concept and free function/type trait wrappers.
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, 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:107
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:205
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:95
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:145
constexpr auto is_space
Checks whether c is a space character.
Definition: predicate.hpp:128
constexpr auto is_cntrl
Checks whether c is a control character.
Definition: predicate.hpp:92
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: traits.hpp:471
constexpr size_t size
The size of a type pack.
Definition: traits.hpp:151
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: exception.hpp:48
The options type defines various option members that influence the behaviour of all or some formats.
Definition: input_options.hpp:27
bool truncate_ids
Read the ID string only up until the first whitespace character.
Definition: input_options.hpp:29
The options type defines various option members that influence the behaviour of all or some formats.
Definition: 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: output_options.hpp:43
bool fastq_double_id
Whether to write the ID only '@' or also after '+' line.
Definition: output_options.hpp:38
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.