RangeManager.h

Go to the documentation of this file.

// --------------------------------------------------------------------------
//                   OpenMS -- Open-Source Mass Spectrometry
// --------------------------------------------------------------------------
// Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
// ETH Zurich, and Freie Universitaet Berlin 2002-2023.
//
// This software is released under a three-clause BSD license:
//  * Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//  * Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//  * Neither the name of any author or any participating institution
//    may be used to endorse or promote products derived from this software
//    without specific prior written permission.
// For a full list of authors, refer to the file AUTHORS.
// --------------------------------------------------------------------------
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
// INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// --------------------------------------------------------------------------
// $Maintainer: Chris Bielow $
// $Authors: Chris Bielow $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/config.h>
#include <OpenMS/CONCEPT/Exception.h>
#include <OpenMS/CONCEPT/CommonEnums.h>
 
#include <cmath> // for nan()
#include <algorithm> // for min/max
#include <cassert>
#include <iosfwd>  // for std::ostream
 
namespace OpenMS
{
  enum class MSDim
  {
    RT,
    MZ,
    INT,
    IM
  };
 
  struct RangeRT;
  struct RangeMZ;
  struct RangeIntensity;
  struct RangeMobility;
 
  struct OPENMS_DLLAPI RangeBase
  {
  public:
    RangeBase() = default;
    
    RangeBase(const double min, const double max) :
        min_(min), max_(max)
    {
      if (min_ > max_)
        throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "Invalid initialization of range");
    }
    RangeBase(const RangeBase& rhs) = default;
 
    RangeBase(RangeBase&& rhs) noexcept = default;
 
    RangeBase& operator=(const RangeBase& rhs) = default;
 
    RangeBase& operator=(RangeBase&& rhs) noexcept = default;
 
    ~RangeBase() noexcept = default;
 
    operator RangeRT() const;
    operator RangeMZ() const;
    operator RangeIntensity() const;
    operator RangeMobility() const;
 
    void clear()
    {
      *this = RangeBase(); // overwrite with fresh instance
    }
 
    bool isEmpty() const
    {
      return min_ > max_; 
    }
 
    bool contains(const double value) const
    {
      return uint8_t(min_ <= value) & uint8_t(value <= max_); // using && leads to branches on all compilers in Debug and in Release on MVSC
    }
 
    bool contains(const RangeBase& inner_range) const
    {
      return uint8_t(contains(inner_range.min_)) & uint8_t(contains(inner_range.max_)); // using && leads to branches on all compilers in Debug and in Release on MVSC
    }
 
    
    void setMin(const double min)
    {
      min_ = min;
      if (max_ < min)
        max_ = min;
    }
 
    void setMax(const double max)
    {
      max_ = max;
      if (min_ > max)
        min_ = max;
    }
 
    double getMin() const
    {
      return min_;
    }
 
    double getMax() const
    {
      return max_;
    }
 
    void extend(const RangeBase& other)
    {
      min_ = std::min(min_, other.min_);
      max_ = std::max(max_, other.max_);
    }
    
    void extend(const double value)
    {
      min_ = std::min(min_, value);
      max_ = std::max(max_, value);
    }
 
    void extendLeftRight(const double by)
    {
      if (isEmpty()) return;
      min_ -= by;
      max_ += by;
    }
 
    void minSpanIfSingular(const double min_span)
    {
      if (min_ == max_) extendLeftRight(min_span / 2);
    }
 
    void clampTo(const RangeBase& other)
    {
      if (isEmpty()) return;
      if (other.isEmpty()) throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION);
 
      min_ = std::max(min_, other.min_);
      max_ = std::min(max_, other.max_);
    }
 
    void pushInto(const RangeBase& sandbox)
    {
      if (isEmpty()) return;
      if (sandbox.isEmpty()) throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION);
 
      if (!sandbox.contains(*this))
      {
        if (getSpan() > sandbox.getSpan())
        { // make interval fit into sandbox (= ensure full containment)
          max_ = min_ + sandbox.getSpan();
        }
        if (min_ < sandbox.min_)
        { // need to shift right (positive shift)
          shift(sandbox.min_ - min_);
        }
        else if (max_ > sandbox.max_)
        { // need to shift left (negative shift)
          shift(sandbox.max_ - max_);
        }
      }
 
    }
 
 
    void scaleBy(const double factor)
    {
      if (isEmpty()) return;
      const double dist = max_ - min_;
      const double extension = dist * (factor - 1) / 2;
      min_ -= extension;
      max_ += extension;
    }
 
    void shift(const double distance)
    {
      if (isEmpty()) return;
      min_ += distance;
      max_ += distance;
    }
 
    double center() const
    {
      if (isEmpty()) return nan("");
      return min_ + (max_ - min_) / 2.0;
    }
 
    double getSpan() const
    {
      if (isEmpty()) return nan("");
      return max_ - min_;
    }
 
    bool operator==(const RangeBase& rhs) const
    {
      return min_ == rhs.min_ && max_ == rhs.max_;
    }
 
    std::pair<double, double> getNonEmptyRange() const
    {
      // pair with full range
      if (isEmpty()) return {std::numeric_limits<double>::lowest(), std::numeric_limits<double>::max()};
      else return {min_, max_};
    }
 
  protected:
    // make members non-accessible to maintain invariant: min <= max  (unless uninitialized)
    double min_ = std::numeric_limits<double>::max();
    double max_ = std::numeric_limits<double>::lowest();
  };
  
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& out, const RangeBase& b);
 
  struct OPENMS_DLLAPI RangeRT : public RangeBase {
 
    const static MSDim DIM = MSDim::RT;
 
    // Rule of 0!
    using RangeBase::RangeBase; // inherit C'tors from base
 
 
    void setMinRT(const double min)
    {
      setMin(min);
    }
 
    void setMaxRT(const double max)
    {
      setMax(max);
    }
 
    double getMinRT() const
    {
      return min_;
    }
 
    double getMaxRT() const
    {
      return max_;
    }
 
    void extendRT(const double value)
    {
      extend(value);
    }
 
    bool containsRT(const double value) const
    {
      return RangeBase::contains(value);
    }
 
    bool containsRT(const RangeBase& inner_range) const
    {
      return RangeBase::contains(inner_range);
    }
  };
  
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& out, const RangeRT& range);
 
  struct OPENMS_DLLAPI RangeMZ : public RangeBase
  {
 
    const static MSDim DIM = MSDim::MZ;
 
    // Rule of 0!
    using RangeBase::RangeBase; // inherit C'tors from base
 
 
    void setMinMZ(const double min)
    {
      setMin(min);
    }
 
    void setMaxMZ(const double max)
    {
      setMax(max);
    }
 
    double getMinMZ() const
    {
      return min_;
    }
 
    double getMaxMZ() const
    {
      return max_;
    }
 
    void extendMZ(const double value)
    {
      extend(value);
    }
 
    bool containsMZ(const double value) const
    {
      return RangeBase::contains(value);
    }
 
    bool containsMZ(const RangeBase& inner_range) const
    {
      return RangeBase::contains(inner_range);
    }
  };
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& out, const RangeMZ& range);
 
  struct OPENMS_DLLAPI RangeIntensity : public RangeBase {
 
    const static MSDim DIM = MSDim::INT;
 
    // Rule of 0!
    using RangeBase::RangeBase; // inherit C'tors from base
 
 
    void setMinIntensity(const double min)
    {
      setMin(min);
    }
 
    void setMaxIntensity(const double max)
    {
      setMax(max);
    }
 
    double getMinIntensity() const
    {
      return min_;
    }
 
    double getMaxIntensity() const
    {
      return max_;
    }
 
    void extendIntensity(const double value)
    {
      extend(value);
    }
 
    bool containsIntensity(const double value) const
    {
      return RangeBase::contains(value);
    }
 
    bool containsIntensity(const RangeBase& inner_range) const
    {
      return RangeBase::contains(inner_range);
    }
  };
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& out, const RangeIntensity& range);
 
  struct OPENMS_DLLAPI RangeMobility : public RangeBase
  {
    const static MSDim DIM = MSDim::IM;
 
    // Rule of 0!
    using RangeBase::RangeBase; // inherit C'tors from base
 
 
    void setMinMobility(const double min)
    {
      setMin(min);
    }
 
    void setMaxMobility(const double max)
    {
      setMax(max);
    }
 
    double getMinMobility() const
    {
      return min_;
    }
 
    double getMaxMobility() const
    {
      return max_;
    }
 
    void extendMobility(const double value)
    {
      extend(value);
    }
 
    bool containsMobility(const double value) const
    {
      return RangeBase::contains(value);
    }
 
    bool containsMobility(const RangeBase& inner_range) const
    {
      return RangeBase::contains(inner_range);
    }
  };
 
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& out, const RangeMobility& range);
  
  enum class HasRangeType
  {
    ALL, 
    SOME,
    NONE 
  };
 
  template<typename... RangeBases>
  class RangeManager : public RangeBases...
  {
  public:
    using ThisRangeType = RangeManager<RangeBases...>;
    // rule of 0 -- no need for a virtual d'tor or anything fancy
    // ...
 
    bool operator==(const RangeManager& rhs) const
    {
      bool equal = true;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        equal &= ((T_BASE&) rhs == (T_BASE&) *this);
      });
      return equal;
    }
 
    bool operator!=(const RangeManager& rhs) const
    {
      return !operator==(rhs);
    }
 
    template <typename... RangeBasesOther>
    bool assignUnsafe(const RangeManager<RangeBasesOther...>& rhs)
    {
      bool found = false;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if constexpr (std::is_base_of_v<T_BASE, RangeManager<RangeBasesOther...>>)
        {
          base->operator=((T_BASE&) rhs);
          found = true;
        }
      });
 
      return found;
    }
 
    template<typename... RangeBasesOther>
    auto& assign(const RangeManager<RangeBasesOther...>& rhs)
    {
      if (!assignUnsafe(rhs))
      {
        throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION , "No assignment took place (no dimensions in common!);");
      }
      return *this;
    }                 
 
    template<typename... RangeBasesOther>
    bool extendUnsafe(const RangeManager<RangeBasesOther...>& rhs)
    {
      bool found = false;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if constexpr (std::is_base_of_v<T_BASE, RangeManager<RangeBasesOther...>>)
        {
          base->extend((T_BASE&) rhs);
          found = true;
        }
      });
      return found;
    }
 
    template<typename... RangeBasesOther>
    void extend(const RangeManager<RangeBasesOther...>& rhs)
    {
      if (!extendUnsafe(rhs))
      {
        throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "No assignment took place (no dimensions in common!);");
      }
    }
 
    void scaleBy(const double factor)
    {
      for_each_base_([&](auto* base) {
        base->scaleBy(factor);
      });
    }
 
    void minSpanIfSingular(const double min_span)
    {
      for_each_base_([&](auto* base) {
        base->minSpanIfSingular(min_span);
      });
    }
 
 
    template<typename... RangeBasesOther>
    bool pushIntoUnsafe(const RangeManager<RangeBasesOther...>& rhs)
    {
      bool found = false;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if constexpr (std::is_base_of_v<T_BASE, RangeManager<RangeBasesOther...>>)
        {
          const auto& rhs_base = (T_BASE&)rhs;
          if (!rhs_base.isEmpty()) base->pushInto(rhs_base);
          found = true;
        }
      });
      return found;
    }
 
    template<typename... RangeBasesOther>
    void pushInto(const RangeManager<RangeBasesOther...>& sandbox)
    {
      if (!pushIntoUnsafe(sandbox))
      {
        throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "No assignment took place (no dimensions in common!);");
      }
    }
 
    
    template<typename... RangeBasesOther>
    bool clampToUnsafe(const RangeManager<RangeBasesOther...>& rhs)
    {
      bool found = false;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if constexpr (std::is_base_of_v<T_BASE, RangeManager<RangeBasesOther...>>)
        {
          const auto& rhs_base = (T_BASE&)rhs;
          if (!rhs_base.isEmpty()) base->clampTo(rhs_base);
          found = true;
        }
      });
      return found;
    }
 
    template<typename... RangeBasesOther>
    void clampTo(const RangeManager<RangeBasesOther...>& rhs)
    {
      if (!clampToUnsafe(rhs))
      {
        throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION, "No assignment took place (no dimensions in common!);");
      }
    }
 
    const RangeBase& getRangeForDim(MSDim dim) const
    {
      RangeBase* r_base = nullptr;
 
      static_for_each_base_([&](auto* base) {
        using Base = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if (base->DIM == dim)
          r_base = (Base*)this;
      });
 
      assert((r_base != nullptr) && "No base class has this MSDim!");
      return *r_base;
    }
 
    RangeBase& getRangeForDim(MSDim dim)
    {
      RangeBase* r_base = nullptr;
 
      static_for_each_base_([&](auto* base) {
        using Base = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if (base->DIM == dim)
          r_base = (Base*) this;
      });
 
      assert((r_base != nullptr) && "No base class has this MSDim!");
      return *r_base;
    }
    
    HasRangeType hasRange() const
    {
      constexpr size_t total{sizeof...(RangeBases)};// total number of bases
      size_t count{0};
      for_each_base_([&](auto* base) {
        count += !base->isEmpty();
      });
      switch (count)
      {
        case 0:
          return HasRangeType::NONE;
        case total:
          return HasRangeType::ALL;
        default:
          return HasRangeType::SOME;
      }
    }
 
    template<typename... RangeBasesOther>
    bool containsAll(const RangeManager<RangeBasesOther...>& rhs) const
    {
      bool contained = true; // assume rhs is contained, until proven otherwise
      bool has_overlap = false;
      for_each_base_([&](auto* base) {
        using T_BASE = std::decay_t<decltype(*base)>; // remove const/ref qualifiers
        if constexpr (std::is_base_of_v<T_BASE, RangeManager<RangeBasesOther...>>)
        {
          has_overlap = true; // at least one dimension overlaps
          if (((T_BASE&)rhs).isEmpty()) return;
          if (base->contains((T_BASE&) rhs)) return;
          contained = false;
        }
      });
      if (!has_overlap) throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION);
 
      return contained;
    }
 
    void clearRanges()
    {
      for_each_base_([&](auto* base) {
        base->clear();
      });
    }
 
    ThisRangeType& clear(const DIM_UNIT range)
    {
      switch (range)
      {
        case DIM_UNIT::RT:
          if constexpr (std::is_base_of_v<RangeRT, ThisRangeType>) this->RangeRT::clear();
          break;
        case DIM_UNIT::MZ:
          if constexpr (std::is_base_of_v<RangeMZ, ThisRangeType>) this->RangeMZ::clear();
          break;
        case DIM_UNIT::INT:
          if constexpr (std::is_base_of_v<RangeIntensity, ThisRangeType>) this->RangeIntensity::clear();
          break;
        // assume all ion mobility ranges are the same and never occur together. If this is violated at some point, then split RangeMobility into subclasses...
        case DIM_UNIT::IM_MS:
        case DIM_UNIT::IM_VSSC:
        case DIM_UNIT::FAIMS_CV:
          if constexpr (std::is_base_of_v<RangeMobility, ThisRangeType>) this->RangeMobility::clear();
          break;
        default:
          // all cases should be covered above
          assert(false && "This should never be reached. Did you forget to implement a new DIM_UNIT?");
      }
      return *this;
    }
 
    void printRange(std::ostream& out) const
    {
      for_each_base_([&](auto* base) {
        out << *base;
      });
    }
 
  protected:
    template<typename Visitor>
    void for_each_base_(Visitor&& visitor)
    {
      (void(visitor(static_cast<RangeBases*>(this))), ...);
    }
    template<typename Visitor>
    void for_each_base_(Visitor&& visitor) const
    {
      (void(visitor(static_cast<const RangeBases*>(this))), ...);
    }
 
    template<typename Visitor>
    static void static_for_each_base_(Visitor&& visitor)
    {
      (void(visitor(static_cast<const RangeBases*>(nullptr))), ...);
    }
  };
 
  template<typename... Range>
  std::ostream& operator<<(std::ostream& out, const RangeManager<Range...>& me)
  {
    me.printRange(out);
    return out;
  }
 
  template <typename ...RangeBases>
  class RangeManagerContainer
    : public RangeManager<RangeBases...>
  {
  public:
    using ThisRangeType = typename RangeManager<RangeBases...>::ThisRangeType;
 
    virtual ~RangeManagerContainer() = default; // required since we have virtual methods
 
    virtual void updateRanges() = 0;
 
    const ThisRangeType& getRange() const
    {
      return (ThisRangeType&)*this;
    }
 
    ThisRangeType& getRange()
    {
      return (ThisRangeType&)*this;
    }
  };
 
  using RangeAllType = RangeManager<RangeRT, RangeMZ, RangeIntensity, RangeMobility>;
 
}  // namespace OpenMS