translate.hpp

Go to the documentation of this file.

// -----------------------------------------------------------------------------------------------------
// Copyright (c) 2006-2021, Knut Reinert & Freie Universität Berlin
// Copyright (c) 2016-2021, Knut Reinert & MPI für molekulare Genetik
// This file may be used, modified and/or redistributed under the terms of the 3-clause BSD-License
// shipped with this file and also available at: https://github.com/seqan/seqan3/blob/master/LICENSE.md
// -----------------------------------------------------------------------------------------------------
 
#pragma once
 
#include <seqan3/std/concepts>
#include <seqan3/std/ranges>
#include <vector>
#include <stdexcept>
 
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/alphabet/aminoacid/aa27.hpp>
#include <seqan3/alphabet/aminoacid/translation.hpp>
#include <seqan3/core/add_enum_bitwise_operators.hpp>
#include <seqan3/core/range/detail/adaptor_from_functor.hpp>
#include <seqan3/core/range/type_traits.hpp>
#include <seqan3/utility/container/small_string.hpp>
#include <seqan3/utility/views/deep.hpp>
 
// ============================================================================
//  forwards
// ============================================================================
 
namespace seqan3::detail
{
 
template <std::ranges::view urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
class view_translate;
 
template <std::ranges::view urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
class view_translate_single;
 
} // namespace seqan3::detail
 
// ============================================================================
//  translation_frames
// ============================================================================
 
namespace seqan3
{
 
enum class translation_frames : uint8_t
{
    forward_frame0 = 1, 
    forward_frame1 = 1 << 1, 
    forward_frame2 = 1 << 2, 
    reverse_frame0 = 1 << 3, 
    reverse_frame1 = 1 << 4, 
    reverse_frame2 = 1 << 5, 
    forward_reverse0 = forward_frame0 | reverse_frame0, 
    forward_reverse1 = forward_frame1 | reverse_frame1, 
    forward_reverse2 = forward_frame2 | reverse_frame2, 
    forward_frames = forward_frame0 | forward_frame1 | forward_frame2, 
    reverse_frames = reverse_frame0 | reverse_frame1 | reverse_frame2, 
    six_frames = forward_frames | reverse_frames, 
 
#ifdef SEQAN3_DEPRECATED_310
    FWD_FRAME_0 SEQAN3_DEPRECATED_310 = forward_frame0, 
    FWD_FRAME_1 SEQAN3_DEPRECATED_310 = forward_frame1, 
    FWD_FRAME_2 SEQAN3_DEPRECATED_310 = forward_frame2, 
    REV_FRAME_0 SEQAN3_DEPRECATED_310 = reverse_frame0, 
    REV_FRAME_1 SEQAN3_DEPRECATED_310 = reverse_frame1, 
    REV_FRAME_2 SEQAN3_DEPRECATED_310 = reverse_frame2, 
    FWD_REV_0 SEQAN3_DEPRECATED_310 = forward_reverse0, 
    FWD_REV_1 SEQAN3_DEPRECATED_310 = forward_reverse1, 
    FWD_REV_2 SEQAN3_DEPRECATED_310 = forward_reverse2, 
    FWD SEQAN3_DEPRECATED_310 = forward_frames, 
    REV SEQAN3_DEPRECATED_310 = reverse_frames, 
    SIX_FRAME SEQAN3_DEPRECATED_310 = six_frames 
#endif // SEQAN3_DEPRECATED_310
};
 
template <>
constexpr bool add_enum_bitwise_operators<translation_frames> = true;
 
}
 
namespace seqan3::detail
{
 
// ============================================================================
//  translate_fn (adaptor definition for both views)
// ============================================================================
 
template <bool single>
struct translate_fn
{
    static constexpr translation_frames default_frames = single ?
                                                         translation_frames::forward_frame0 :
                                                         translation_frames::six_frames;
 
    constexpr auto operator()(translation_frames const tf = default_frames) const
    {
        return detail::adaptor_from_functor{*this, tf};
    }
 
    template <std::ranges::range urng_t>
    constexpr auto operator()(urng_t && urange, translation_frames const tf = default_frames) const
    {
        static_assert(std::ranges::viewable_range<urng_t>,
            "The range parameter to views::translate[_single] cannot be a temporary of a non-view range.");
        static_assert(std::ranges::sized_range<urng_t>,
            "The range parameter to views::translate[_single] must model std::ranges::sized_range.");
        static_assert(std::ranges::random_access_range<urng_t>,
            "The range parameter to views::translate[_single] must model std::ranges::random_access_range.");
        static_assert(nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>,
            "The range parameter to views::translate[_single] must be over elements of seqan3::nucleotide_alphabet.");
 
        if constexpr (single)
            return detail::view_translate_single{std::forward<urng_t>(urange), tf};
        else
            return detail::view_translate{std::forward<urng_t>(urange), tf};
    }
 
    template <std::ranges::range urng_t>
    constexpr friend auto operator|(urng_t && urange, translate_fn const & me)
    {
        return me(std::forward<urng_t>(urange));
    }
};
 
// ============================================================================
//  view_translate_single (range definition)
// ============================================================================
 
template <std::ranges::view urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
class view_translate_single : public std::ranges::view_base
{
private:
    urng_t urange;
    translation_frames tf;
    static constexpr small_string multiple_frame_error{"Error: Invalid type of frame. Choose one out of "
                                                       "forward_frame0, reverse_frame0, forward_frame1, "
                                                       "reverse_frame1, forward_frame2 and reverse_frame2."};
public:
    using reference         = aa27;
    using const_reference   = aa27;
    using value_type        = aa27;
    using size_type         = std::ranges::range_size_t<urng_t>;
    using difference_type   = std::ranges::range_difference_t<urng_t>;
    using iterator          = detail::random_access_iterator<view_translate_single>;
    using const_iterator    = detail::random_access_iterator<view_translate_single const>;
 
    view_translate_single()                                                        noexcept = default; 
    constexpr view_translate_single(view_translate_single const & rhs)             noexcept = default; 
    constexpr view_translate_single(view_translate_single && rhs)                  noexcept = default; 
    constexpr view_translate_single & operator=(view_translate_single const & rhs) noexcept = default; 
    constexpr view_translate_single & operator=(view_translate_single && rhs)      noexcept = default; 
    ~view_translate_single()                                                       noexcept = default; 
 
 
    view_translate_single(urng_t _urange, translation_frames const _tf = translation_frames::forward_frame0)
        : urange{std::move(_urange)}, tf{_tf}
    {
        if (__builtin_popcount(static_cast<uint8_t>(_tf)) > 1)
        {
            throw std::invalid_argument(multiple_frame_error.c_str());
        }
    }
 
    template <typename rng_t>
     requires (!std::same_as<std::remove_cvref_t<rng_t>, view_translate_single>) &&
              std::ranges::viewable_range<rng_t> &&
              std::constructible_from<urng_t, std::ranges::ref_view<std::remove_reference_t<rng_t>>>
    view_translate_single(rng_t && _urange, translation_frames const _tf = translation_frames::forward_frame0)
     : view_translate_single{std::views::all(std::forward<rng_t>(_urange)), _tf}
    {}
 
    iterator begin() noexcept
    {
        return {*this, 0};
    }
 
    const_iterator begin() const noexcept
    {
        return {*this, 0};
    }
 
    iterator end() noexcept
    {
        return {*this, size()};
    }
 
    const_iterator end() const noexcept
    {
        return {*this, size()};
    }
 
    size_type size()
    {
        switch (tf)
        {
            case translation_frames::forward_frame0:
                [[fallthrough]];
            case translation_frames::reverse_frame0:
                return std::ranges::size(urange) / 3;
                break;
            case translation_frames::forward_frame1:
                [[fallthrough]];
            case translation_frames::reverse_frame1:
                return (std::max<size_type>(std::ranges::size(urange), 1) - 1) / 3;
                break;
            case translation_frames::forward_frame2:
                [[fallthrough]];
            case translation_frames::reverse_frame2:
                return (std::max<size_type>(std::ranges::size(urange), 2) - 2) / 3;
                break;
            default:
                throw std::invalid_argument(multiple_frame_error.c_str());
                break;
        }
    }
 
    size_type size() const
    {
        switch (tf)
        {
            case translation_frames::forward_frame0:
                [[fallthrough]];
            case translation_frames::reverse_frame0:
                return std::ranges::size(urange) / 3;
                break;
            case translation_frames::forward_frame1:
                [[fallthrough]];
            case translation_frames::reverse_frame1:
                return (std::max<size_type>(std::ranges::size(urange), 1) - 1) / 3;
                break;
            case translation_frames::forward_frame2:
                [[fallthrough]];
            case translation_frames::reverse_frame2:
                return (std::max<size_type>(std::ranges::size(urange), 2) - 2) / 3;
                break;
            default:
                throw std::invalid_argument(multiple_frame_error.c_str());
                break;
        }
    }
 
    reference operator[](size_type const n)
    {
        // size will throw (only in debug-builds!) if translation_frames is neither (FWD|REV)_FRAME_(0|1|2),
        // we catch that error in debug-builds to make this function consistent with the behaviour in
        // release-builds (-DNDEBUG).
#ifndef NDEBUG
        try { assert(n < size()); } catch (std::invalid_argument const &) {}
#endif
 
        switch (tf)
        {
         case translation_frames::forward_frame0:
             return translate_triplet((urange)[n * 3], (urange)[n * 3 + 1], (urange)[n * 3 + 2]);
             break;
         case translation_frames::reverse_frame0:
             return translate_triplet(complement((urange)[(urange).size() - n * 3 - 1]),
                                      complement((urange)[(urange).size() - n * 3 - 2]),
                                      complement((urange)[(urange).size() - n * 3 - 3]));
             break;
         case translation_frames::forward_frame1:
             return translate_triplet((urange)[n * 3 + 1], (urange)[n * 3 + 2], (urange)[n * 3 + 3]);
             break;
         case translation_frames::reverse_frame1:
             return translate_triplet(complement((urange)[(urange).size() - n * 3 - 2]),
                                      complement((urange)[(urange).size() - n * 3 - 3]),
                                      complement((urange)[(urange).size() - n * 3 - 4]));
             break;
         case translation_frames::forward_frame2:
             return translate_triplet((urange)[n * 3 + 2], (urange)[n * 3 + 3], (urange)[n * 3 + 4]);
             break;
         case translation_frames::reverse_frame2:
             return translate_triplet(complement((urange)[(urange).size() - n * 3 - 3]),
                                      complement((urange)[(urange).size() - n * 3 - 4]),
                                      complement((urange)[(urange).size() - n * 3 - 5]));
             break;
         default:
             throw std::invalid_argument(multiple_frame_error.c_str());
             break;
        }
    }
 
    const_reference operator[](size_type const n) const
    {
        // size will throw (only in debug-builds!) if translation_frames is neither (FWD|REV)_FRAME_(0|1|2),
        // we catch that error in debug-builds to make this function consistent with the behaviour in
        // release-builds (-DNDEBUG).
#ifndef NDEBUG
        try { assert(n < size()); } catch (std::invalid_argument const &) {}
#endif
 
        switch (tf)
        {
            case translation_frames::forward_frame0:
                return translate_triplet((urange)[n * 3], (urange)[n * 3 + 1], (urange)[n * 3 + 2]);
                break;
            case translation_frames::reverse_frame0:
                return translate_triplet(complement((urange)[(urange).size() - n * 3 - 1]),
                                         complement((urange)[(urange).size() - n * 3 - 2]),
                                         complement((urange)[(urange).size() - n * 3 - 3]));
                break;
            case translation_frames::forward_frame1:
                return translate_triplet((urange)[n * 3 + 1], (urange)[n * 3 + 2], (urange)[n * 3 + 3]);
                break;
            case translation_frames::reverse_frame1:
                return translate_triplet(complement((urange)[(urange).size() - n * 3 - 2]),
                                         complement((urange)[(urange).size() - n * 3 - 3]),
                                         complement((urange)[(urange).size() - n * 3 - 4]));
                break;
            case translation_frames::forward_frame2:
                return translate_triplet((urange)[n * 3 + 2], (urange)[n * 3 + 3], (urange)[n * 3 + 4]);
                break;
            case translation_frames::reverse_frame2:
                return translate_triplet(complement((urange)[(urange).size() - n * 3 - 3]),
                                         complement((urange)[(urange).size() - n * 3 - 4]),
                                         complement((urange)[(urange).size() - n * 3 - 5]));
                break;
            default:
                throw std::invalid_argument(multiple_frame_error.c_str());
                break;
        }
    }
};
 
template <typename urng_t>
view_translate_single(urng_t &&, translation_frames const) -> view_translate_single<std::views::all_t<urng_t>>;
 
 
template <typename urng_t>
view_translate_single(urng_t &&) -> view_translate_single<std::views::all_t<urng_t>>;
 
} // namespace seqan3::detail
 
// ============================================================================
//  translate_single (adaptor object)
// ============================================================================
 
namespace seqan3::views
{
 
inline constexpr auto translate_single = deep{detail::translate_fn<true>{}};
 
} // seqan3::views
 
// ============================================================================
//  view_translate (range definition)
// ============================================================================
 
namespace seqan3::detail
{
 
template <std::ranges::view urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
class view_translate : public std::ranges::view_base
{
private:
    urng_t urange;
    translation_frames tf;
    small_vector<translation_frames, 6> selected_frames{};
 
public:
    using reference         = view_translate_single<urng_t>;
    using const_reference   = reference;
    using value_type        = reference;
    using size_type         = std::ranges::range_size_t<urng_t>;
    using difference_type   = std::ranges::range_difference_t<urng_t>;
    using iterator          = detail::random_access_iterator<view_translate>;
    using const_iterator    = detail::random_access_iterator<view_translate const>;
 
protected:
    // unfortunately we cannot specialise the variable template so we have to add an auxiliary here
    template <typename t>
        requires (range_dimension_v<t> == range_dimension_v<value_type> + 1) &&
                 std::is_same_v<std::remove_cvref_t<range_innermost_value_t<value_type>>,
                                std::remove_cvref_t<range_innermost_value_t<t>>>
    static constexpr bool is_compatible_this_aux = true;
 
public:
 
    view_translate()                                                 noexcept = default; 
    constexpr view_translate(view_translate const & rhs)             noexcept = default; 
    constexpr view_translate(view_translate && rhs)                  noexcept = default; 
    constexpr view_translate & operator=(view_translate const & rhs) noexcept = default; 
    constexpr view_translate & operator=(view_translate && rhs)      noexcept = default; 
    ~view_translate()                                                noexcept = default; 
 
    view_translate(urng_t _urange, translation_frames const _tf = translation_frames::six_frames)
        : urange{std::move(_urange)}, tf{_tf}
    {
        if ((_tf & translation_frames::forward_frame0) == translation_frames::forward_frame0)
            selected_frames.push_back(translation_frames::forward_frame0);
        if ((_tf & translation_frames::forward_frame1) == translation_frames::forward_frame1)
            selected_frames.push_back(translation_frames::forward_frame1);
        if ((_tf & translation_frames::forward_frame2) == translation_frames::forward_frame2)
            selected_frames.push_back(translation_frames::forward_frame2);
        if ((_tf & translation_frames::reverse_frame0) == translation_frames::reverse_frame0)
            selected_frames.push_back(translation_frames::reverse_frame0);
        if ((_tf & translation_frames::reverse_frame1) == translation_frames::reverse_frame1)
            selected_frames.push_back(translation_frames::reverse_frame1);
        if ((_tf & translation_frames::reverse_frame2) == translation_frames::reverse_frame2)
            selected_frames.push_back(translation_frames::reverse_frame2);
    }
 
    template <typename rng_t>
        requires (!std::same_as<std::remove_cvref_t<rng_t>, view_translate>) &&
                 std::ranges::viewable_range<rng_t> &&
                 std::constructible_from<urng_t, std::ranges::ref_view<std::remove_reference_t<rng_t>>>
    view_translate(rng_t && _urange, translation_frames const _tf)
     : view_translate{std::views::all(std::forward<rng_t>(_urange)), _tf}
    {}
 
    #ifdef SEQAN3_DEPRECATED_310
    template <typename rng_t>
        requires (!std::same_as<std::remove_cvref_t<rng_t>, view_translate>) &&
                 std::ranges::viewable_range<rng_t> &&
                 std::constructible_from<urng_t, std::ranges::ref_view<std::remove_reference_t<rng_t>>>
    view_translate(rng_t && _urange)
     : view_translate{std::views::all(std::forward<rng_t>(_urange)), translation_frames::six_frames}
    {}
    #endif // SEQAN3_DEPRECATED_310
 
    iterator begin() noexcept
    {
        return {*this, 0};
    }
 
    const_iterator begin() const noexcept
    {
        return {*this, 0};
    }
 
    iterator end() noexcept
    {
        return {*this, size()};
    }
 
    const_iterator end() const noexcept
    {
        return {*this, size()};
    }
 
    size_type size() noexcept
    {
        return (size_type) selected_frames.size();
    }
 
    size_type size() const noexcept
    {
        return (size_type) selected_frames.size();
    }
 
    reference operator[](size_type const n)
    {
        assert(n < size());
        return urange | views::translate_single(selected_frames[n]);
    }
 
    const_reference operator[](size_type const n) const
    {
        assert(n < size());
        return urange | views::translate_single(selected_frames[n]);
    }
};
 
#ifdef SEQAN3_DEPRECATED_310
template <typename urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
view_translate (urng_t &&) -> view_translate<std::views::all_t<urng_t>>;
#endif // SEQAN3_DEPRECATED_310
 
template <typename urng_t>
    requires std::ranges::sized_range<urng_t> &&
             std::ranges::random_access_range<urng_t> &&
             nucleotide_alphabet<std::ranges::range_reference_t<urng_t>>
view_translate(urng_t &&, translation_frames const) -> view_translate<std::views::all_t<urng_t>>;
} // namespace seqan3::detail
 
// ============================================================================
//  translate (adaptor object)
// ============================================================================
 
namespace seqan3::views
{
 
inline constexpr auto translate = deep{detail::translate_fn<false>{}};
 
} // namespace seqan3::views