Residue.h

Go to the documentation of this file.

// Copyright (c) 2002-present, OpenMS Inc. -- EKU Tuebingen, ETH Zurich, and FU Berlin
// SPDX-License-Identifier: BSD-3-Clause
//
// --------------------------------------------------------------------------
// $Maintainer: Timo Sachsenberg $
// $Authors: Andreas Bertsch, Jang Jang Jin$
// --------------------------------------------------------------------------
//
 
#pragma once
 
#include <OpenMS/CHEMISTRY/EmpiricalFormula.h>
#include <OpenMS/CONCEPT/CommonEnums.h>
#include <OpenMS/CONCEPT/HashUtils.h>
#include <OpenMS/CONCEPT/Types.h>
#include <OpenMS/DATASTRUCTURES/StringUtils.h>
 
#include <array>
#include <functional>
#include <iosfwd>
#include <set>
#include <vector>
 
namespace OpenMS
{
  class ResidueModification;
 
  class OPENMS_DLLAPI Residue
  {
    friend class ResidueDB;
 
public:
 
 
    inline static const EmpiricalFormula& getInternalToFull()
    {
      static const EmpiricalFormula to_full = EmpiricalFormula("H2O");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToNTerm()
    {
      static const EmpiricalFormula to_full = EmpiricalFormula("H");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToCTerm()
    {
      static const EmpiricalFormula to_full = EmpiricalFormula("OH");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToAIon()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToNTerm() - EmpiricalFormula("CHO");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToBIon()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToNTerm() - EmpiricalFormula("H");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToCIon()
    {
      static const EmpiricalFormula to_full =
        getInternalToNTerm() + EmpiricalFormula("NH2");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToXIon()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToCTerm() + EmpiricalFormula("CO") - EmpiricalFormula("H");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToYIon()
    {
      static const EmpiricalFormula to_full =
        getInternalToCTerm() + EmpiricalFormula("H");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToZIon()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToCTerm() - EmpiricalFormula("NH2");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToZp1Ion()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToCTerm() - EmpiricalFormula("NH");
      return to_full;
    }
 
    inline static const EmpiricalFormula& getInternalToZp2Ion()
    {
      // Mind the "-"
      static const EmpiricalFormula to_full =
        getInternalToCTerm() - EmpiricalFormula("N");
      return to_full;
    }
 
 
 
    enum ResidueType
    {
      Full = 0,       
      Internal,       
      NTerminal,      
      CTerminal,      
      AIon,           
      BIon,           
      CIon,           
      XIon,           
      YIon,           
      ZIon,           
      Zp1Ion,         
      Zp2Ion,         
      Precursor,      
      BIonMinusH20,   
      YIonMinusH20,   
      BIonMinusNH3,   
      YIonMinusNH3,   
      NonIdentified,  
      Unannotated,    
      DIon,           
      VIon,           
      WIon,           
      SizeOfResidueType
    };
    
    static inline std::array<std::string_view, Residue::ResidueType::SizeOfResidueType> names_of_residuetype {
      "full",
      "internal",
      "N-terminal",
      "C-terminal",
      "a-ion",
      "b-ion",
      "c-ion",
      "x-ion",
      "y-ion",
      "z-ion",
      "z+1-ion",
      "z+2-ion",
      "precursor-ion",
      "b-H2O-ion",
      "y-H2O-ion",
      "b-NH3-ion",
      "y-NH3-ion",
      "Non-identified ion",
      "unannotated",
      "d-ion",
      "v-ion",
      "w-ion"
    };
 
    static std::string getResidueTypeName(const ResidueType res_type);
 
 
    Residue();
 
    Residue(const Residue&) = default;
 
    Residue(Residue&&) = default;
           
    // Detailed constructor 
    Residue(const std::string& name,
            const std::string& three_letter_code,
            const std::string& one_letter_code,
            const EmpiricalFormula& formula,
            double pka = 0,
            double pkb = 0,
            double pkc = -1,
            double gb_sc = 0,
            double gb_bb_l = 0,
            double gb_bb_r = 0,
            const std::set<std::string>& synonyms = std::set<std::string>());
 
    virtual ~Residue();
 
 
    Residue& operator=(const Residue&) = default;
 
    Residue& operator=(Residue&&) & = default;
 
    void setName(const std::string& name);
 
    const std::string& getName() const;
 
    void setSynonyms(const std::set<std::string>& synonyms);
 
    void addSynonym(const std::string& synonym);
 
    const std::set<std::string>& getSynonyms() const;
 
    void setThreeLetterCode(const std::string& three_letter_code);
 
    const std::string& getThreeLetterCode() const;
 
    void setOneLetterCode(const std::string& one_letter_code);
 
    const std::string& getOneLetterCode() const;
 
    void addLossFormula(const EmpiricalFormula&);
 
    void setLossFormulas(const std::vector<EmpiricalFormula>&);
 
    void addNTermLossFormula(const EmpiricalFormula&);
 
    void setNTermLossFormulas(const std::vector<EmpiricalFormula>&);
 
    const std::vector<EmpiricalFormula>& getLossFormulas() const;
 
    const std::vector<EmpiricalFormula>& getNTermLossFormulas() const;
 
    void setLossNames(const std::vector<std::string>& name);
 
    void setNTermLossNames(const std::vector<std::string>& name);
 
    void addLossName(const std::string& name);
 
    void addNTermLossName(const std::string& name);
 
    const std::vector<std::string>& getLossNames() const;
 
    const std::vector<std::string>& getNTermLossNames() const;
 
    void setFormula(const EmpiricalFormula& formula);
 
    EmpiricalFormula getFormula(ResidueType res_type = Full) const;
 
    void setAverageWeight(double weight);
 
    double getAverageWeight(ResidueType res_type = Full) const;
 
    void setMonoWeight(double weight);
 
    double getMonoWeight(ResidueType res_type = Full) const;
 
    const ResidueModification* getModification() const;
 
    void setModification(const std::string& name);
 
    void setModification(const ResidueModification* mod);
 
    void setModification(const ResidueModification& mod);
 
    void setModificationByDiffMonoMass(double diffMonoMass);
    
    const std::string& getModificationName() const;
 
    void setLowMassIons(const std::vector<EmpiricalFormula>& low_mass_ions);
 
    const std::vector<EmpiricalFormula>& getLowMassIons() const;
 
    void setResidueSets(const std::set<std::string>& residues_sets);
 
    void addResidueSet(const std::string& residue_sets);
 
    const std::set<std::string>& getResidueSets() const;
 
    double getPka() const;
 
    double getPkb() const;
 
    double getPkc() const;
 
    double getPiValue() const;
 
    void setPka(double value);
 
    void setPkb(double value);
 
    void setPkc(double value);
 
    double getSideChainBasicity() const;
 
    void setSideChainBasicity(double gb_sc);
 
    double getBackboneBasicityLeft() const;
 
    void setBackboneBasicityLeft(double gb_bb_l);
 
    double getBackboneBasicityRight() const;
 
    void setBackboneBasicityRight(double gb_bb_r);
 
    bool hasNeutralLoss() const;
 
    bool hasNTermNeutralLosses() const;
 
    bool operator==(const Residue& residue) const;
 
    bool operator!=(const Residue& residue) const;
 
    bool operator==(char one_letter_code) const;
 
    bool operator!=(char one_letter_code) const;
 
    bool isModified() const;
 
    bool isInResidueSet(const std::string& residue_set);
 
    bool hasVLoss() const;
 
    EmpiricalFormula getVLossFormula() const;
 
    bool hasSatelliteLoss(char subtype = '\0') const;
 
    EmpiricalFormula getSatelliteLossFormula(char subtype = '\0') const;
 
    static std::string residueTypeToIonLetter(const ResidueType& res_type);
 
    std::string toString() const;
 
    friend OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const Residue& residue);
    
    double getHydrophobicity(const HydrophobicityScaleMethod scale) const;
 
protected:
    void validateSatelliteIon_(ResidueType type) const;
 
 
    std::string name_ = "unknown";
 
    std::set<std::string> synonyms_;
 
    std::string three_letter_code_;
 
    std::string one_letter_code_;
 
    EmpiricalFormula formula_;
 
    EmpiricalFormula internal_formula_;
 
    double average_weight_ = 0;
 
    double mono_weight_ = 0;
 
    const ResidueModification* modification_ = nullptr;
 
    // loss
    std::vector<std::string> loss_names_;
 
    std::vector<EmpiricalFormula> loss_formulas_;
 
    std::vector<std::string> NTerm_loss_names_;
 
    std::vector<EmpiricalFormula> NTerm_loss_formulas_;
 
    std::vector<EmpiricalFormula> low_mass_ions_;
 
    // pka values
    double pka_ = 0;
 
    // pkb values
    double pkb_ = 0;
 
    // pkc values
    double pkc_ = -1.0;
 
    double gb_sc_ = 0;
 
    double gb_bb_l_ = 0;
 
    double gb_bb_r_ = 0;
 
    std::set<std::string> residue_sets_;
 
    // pre-calculated residue type delta weights for more efficient weight calculation
    static const double internal_to_full_monoweight_;
    static const double internal_to_nterm_monoweight_;
    static const double internal_to_cterm_monoweight_;
    static const double internal_to_a_monoweight_;
    static const double internal_to_b_monoweight_;
    static const double internal_to_c_monoweight_;
    static const double internal_to_x_monoweight_;
    static const double internal_to_y_monoweight_;
    static const double internal_to_z_monoweight_;
    static const double internal_to_zp1_monoweight_;
    static const double internal_to_zp2_monoweight_;
  };
 
  // write 'name threelettercode onelettercode formula'
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const Residue& residue);
 
} // namespace OpenMS
 
namespace std
{
  template<>
  struct hash<OpenMS::Residue>
  {
    std::size_t operator()(const OpenMS::Residue& r) const noexcept
    {
      std::size_t seed = 0;
 
      // Hash name_
      OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(r.getName()));
 
      // Hash synonyms_ (std::set<std::string>)
      for (const auto& syn : r.getSynonyms())
      {
        OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(syn));
      }
 
      // Hash three_letter_code_
      OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(r.getThreeLetterCode()));
 
      // Hash one_letter_code_
      OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(r.getOneLetterCode()));
 
      // Hash formula_
      OpenMS::hash_combine(seed, std::hash<OpenMS::EmpiricalFormula>{}(r.getFormula()));
 
      // Hash average_weight_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getAverageWeight()));
 
      // Hash mono_weight_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getMonoWeight()));
 
      // Hash modification_ (pointer comparison in operator==)
      OpenMS::hash_combine(seed, OpenMS::hash_int(reinterpret_cast<std::uintptr_t>(r.getModification())));
 
      // Hash loss_names_ (std::vector<std::string>)
      for (const auto& name : r.getLossNames())
      {
        OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(name));
      }
 
      // Hash loss_formulas_ (std::vector<EmpiricalFormula>)
      for (const auto& formula : r.getLossFormulas())
      {
        OpenMS::hash_combine(seed, std::hash<OpenMS::EmpiricalFormula>{}(formula));
      }
 
      // Hash NTerm_loss_names_ (std::vector<std::string>)
      for (const auto& name : r.getNTermLossNames())
      {
        OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(name));
      }
 
      // Hash NTerm_loss_formulas_ (std::vector<EmpiricalFormula>)
      for (const auto& formula : r.getNTermLossFormulas())
      {
        OpenMS::hash_combine(seed, std::hash<OpenMS::EmpiricalFormula>{}(formula));
      }
 
      // Hash low_mass_ions_ (std::vector<EmpiricalFormula>)
      for (const auto& formula : r.getLowMassIons())
      {
        OpenMS::hash_combine(seed, std::hash<OpenMS::EmpiricalFormula>{}(formula));
      }
 
      // Hash pka_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getPka()));
 
      // Hash pkb_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getPkb()));
 
      // Hash pkc_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getPkc()));
 
      // Hash gb_sc_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getSideChainBasicity()));
 
      // Hash gb_bb_l_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getBackboneBasicityLeft()));
 
      // Hash gb_bb_r_
      OpenMS::hash_combine(seed, OpenMS::hash_float(r.getBackboneBasicityRight()));
 
      // Hash residue_sets_ (std::set<std::string>)
      for (const auto& rs : r.getResidueSets())
      {
        OpenMS::hash_combine(seed, OpenMS::fnv1a_hash_string(rs));
      }
 
      return seed;
    }
  };
} // namespace std