ProForma.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: Timo Sachsenberg $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/CONCEPT/Exception.h>
#include <OpenMS/DATASTRUCTURES/String.h>
#include <OpenMS/OpenMSConfig.h>
 
#include <optional>
#include <utility>
#include <variant>
#include <vector>
 
namespace OpenMS
{
 
  // Forward declarations
  class ResidueModification;
  class AASequence;
  class MSSpectrum;
 
  class OPENMS_DLLAPI ProForma
  {
  public:
    //==========================================================================
    // Enums
    //==========================================================================
 
    enum class ConversionPolicy
    {
      FAIL_ON_LOSS,      
      DROP_UNLOCALISED,  
      BEST_EFFORT        
    };
 
 
    enum class ConversionIssueType
    {
      UNRESOLVED_MOD,      
      UNLOCALISED_MOD,     
      LABILE_MOD,          
      GLOBAL_MOD,          
      AMBIGUOUS_MOD,       
      AMBIGUOUS_REGION,    
      MODIFIED_RANGE,      
      CROSS_LINK,          
      MULTIPLE_CHAINS,     
      ALTERNATIVE_MODS,    
      UNSUPPORTED_FEATURE  
    };
 
 
    enum class WriteMode
    {
      LOSSLESS,   
      CANONICAL   
    };
 
 
    enum class CvDatabase
    {
      UNIMOD, 
      MOD,    
      RESID,  
      XLMOD,  
      GNO     
    };
 
 
    enum class ErrorCode
    {
      UNEXPECTED_CHARACTER,       
      UNCLOSED_BRACKET,           
      UNMATCHED_BRACKET,          
      INVALID_CV_PREFIX,          
      INVALID_CV_ACCESSION,       
      INVALID_AMINO_ACID,         
      INVALID_MASS_VALUE,         
      INVALID_FORMULA,            
      UNKNOWN_MONOSACCHARIDE,     
      DANGLING_CROSSLINK_LABEL,   
      EMPTY_SEQUENCE,             
      INVALID_CHARGE,             
      INVALID_OCCURRENCE_SPECIFIER, 
      UNEXPECTED_END_OF_INPUT,    
      INTERNAL_ERROR              
    };
 
 
    //==========================================================================
    // Data Structures
    //==========================================================================
 
    struct OPENMS_DLLAPI ConversionIssue
    {
      ConversionIssueType type;   
      String description;         
      size_t position;            
    };
 
 
    struct OPENMS_DLLAPI CvAccession
    {
      CvDatabase database;  
      String accession;     
    };
 
 
    struct OPENMS_DLLAPI NamedMod
    {
      std::optional<CvDatabase> cv_hint;  
      String name;                        
    };
 
 
    struct OPENMS_DLLAPI MassDelta
    {
      enum class Source
      {
        NONE,  
        OBS,   
        U,     
        M,     
        R,     
        X,     
        G      
      };
 
      Source source = Source::NONE;  
      double mass;                   
      String original_text;          
    };
 
 
    struct OPENMS_DLLAPI FormulaTag
    {
      String formula_string;        
      std::optional<int> charge;    
    };
 
 
    struct OPENMS_DLLAPI GlycanComposition
    {
      using Monosaccharide = std::variant<String, FormulaTag>;
 
      std::vector<std::pair<Monosaccharide, int>> components;  
    };
 
 
    struct OPENMS_DLLAPI InfoTag
    {
      String text;  
    };
 
 
    struct OPENMS_DLLAPI PositionConstraint
    {
      std::vector<char> residues;  
      bool n_term = false;         
      bool c_term = false;         
    };
 
 
    using ModificationTag = std::variant<
      CvAccession,
      NamedMod,
      MassDelta,
      FormulaTag,
      GlycanComposition,
      InfoTag,
      PositionConstraint
    >;
 
 
    struct OPENMS_DLLAPI Label
    {
      enum class Type
      {
        CROSSLINK,  
        BRANCH,     
        AMBIGUOUS   
      };
 
      Type type;                        
      String identifier;                
      std::optional<double> score;      
    };
 
 
    struct OPENMS_DLLAPI Modification
    {
      std::vector<std::pair<ModificationTag, std::optional<Label>>> alternatives;
 
      const ResidueModification* resolved_mod = nullptr;
    };
 
 
    struct OPENMS_DLLAPI SequenceElement
    {
      char amino_acid;                          
      std::vector<Modification> modifications;  
    };
 
 
    struct OPENMS_DLLAPI AmbiguousRegion
    {
      std::vector<SequenceElement> elements;  
    };
 
 
    struct OPENMS_DLLAPI ModifiedRange
    {
      std::vector<SequenceElement> elements;    
      std::vector<Modification> modifications;  
    };
 
 
    using SequenceSection = std::variant<
      SequenceElement,
      AmbiguousRegion,
      ModifiedRange
    >;
 
 
    struct OPENMS_DLLAPI UnlocalisedMod
    {
      std::vector<Modification> modifications;  
      std::optional<int> occurrence;            
    };
 
 
    struct OPENMS_DLLAPI LabileModification
    {
      Modification modification;  
    };
 
 
    struct OPENMS_DLLAPI GlobalModification
    {
      Modification modification;        
      std::vector<String> locations;    
    };
 
 
    struct OPENMS_DLLAPI IsotopeReplacement
    {
      String isotope;  
    };
 
 
    using GlobalModEntry = std::variant<
      IsotopeReplacement,
      GlobalModification
    >;
 
 
    struct OPENMS_DLLAPI AdductIon
    {
      String formula;                   
      int charge;                       
      std::optional<int> occurrence;    
    };
 
 
    using ChargeState = std::variant<
      int,                       
      std::vector<AdductIon>     
    >;
 
 
    struct OPENMS_DLLAPI Peptidoform
    {
      std::optional<String> name;                       
      std::vector<GlobalModEntry> global_mods;          
      std::vector<UnlocalisedMod> unlocalised_mods;     
      std::vector<LabileModification> labile_mods;      
      std::vector<Modification> n_term_mods;            
      std::vector<SequenceSection> sequence;            
      std::vector<Modification> c_term_mods;            
      std::optional<ChargeState> charge;                
    };
 
 
    struct OPENMS_DLLAPI PeptidoformIon
    {
      std::optional<String> name;           
      std::vector<Peptidoform> chains;      
      std::optional<ChargeState> charge;    
      bool is_chimeric = false;             
    };
 
 
    struct OPENMS_DLLAPI CrossLinkGroup
    {
      String label;                                     
      std::vector<std::pair<size_t, size_t>> sites;     
    };
 
 
    //==========================================================================
    // ParseError Exception
    //==========================================================================
 
    class OPENMS_DLLAPI ParseError :
      public Exception::ParseError
    {
    public:
      ParseError(
        const char* file,
        int line,
        const char* function,
        ErrorCode error_code,
        size_t error_position,
        const String& input,
        const String& message
      ) noexcept;
 
      ErrorCode getErrorCode() const noexcept
      {
        return code_;
      }
 
      size_t getPosition() const noexcept
      {
        return position_;
      }
 
      const String& getContextBefore() const noexcept
      {
        return context_before_;
      }
 
      const String& getContextAfter() const noexcept
      {
        return context_after_;
      }
 
      const String& getExpected() const noexcept
      {
        return expected_;
      }
 
      const String& getFound() const noexcept
      {
        return found_;
      }
 
      String getFormattedMessage() const;
 
      void setExpectedFound(const String& expected, const String& found);
 
    private:
      ErrorCode code_;              
      size_t position_;             
      String context_before_;       
      String context_after_;        
      String expected_;             
      String found_;                
 
      void extractContext_(const String& input, size_t pos);
    };
 
 
    //==========================================================================
    // Static Methods - Parsing
    //==========================================================================
 
    static Peptidoform parse(const String& input);
 
    static PeptidoformIon parseIon(const String& input);
 
 
    //==========================================================================
    // Static Methods - Serialization
    //==========================================================================
 
    static String toString(const Peptidoform& pf,
                           WriteMode mode = WriteMode::LOSSLESS);
 
    static String toString(const PeptidoformIon& pfi,
                           WriteMode mode = WriteMode::LOSSLESS);
 
 
    //==========================================================================
    // Static Methods - JSON Serialization
    //==========================================================================
 
    static String toJSON(const Peptidoform& pf);
 
    static Peptidoform peptidoformFromJSON(const String& json_str);
 
    static String toJSON(const PeptidoformIon& pfi);
 
    static PeptidoformIon peptidoformIonFromJSON(const String& json_str);
 
 
    //==========================================================================
    // Static Methods - AASequence Conversion
    //==========================================================================
 
    static void resolveModifications(Peptidoform& pf);
 
    static AASequence toAASequence(
      const Peptidoform& pf,
      ConversionPolicy policy = ConversionPolicy::FAIL_ON_LOSS);
 
    static Peptidoform fromAASequence(const AASequence& seq);
 
    static bool isRepresentableAsAASequence(const Peptidoform& pf);
 
    static std::vector<ConversionIssue> getAASequenceConversionIssues(const Peptidoform& pf);
 
 
    //==========================================================================
    // Static Methods - Mass Calculation
    //==========================================================================
 
    static bool canCalculateMass(const Peptidoform& pf);
 
    static bool canCalculateMass(const PeptidoformIon& pfi);
 
    static std::vector<ConversionIssue> getMassCalculationIssues(const Peptidoform& pf);
 
    static std::vector<ConversionIssue> getMassCalculationIssues(const PeptidoformIon& pfi);
 
    static double getMonoWeight(const Peptidoform& pf);
 
    static double getMonoWeight(const PeptidoformIon& pfi);
 
    static double getMZ(const PeptidoformIon& pfi);
 
    static double getMZ(const Peptidoform& pf, int charge);
 
    // ---- Non-throwing variants (single-pass, efficient) ----
 
    static std::optional<double> tryGetMonoWeight(const Peptidoform& pf);
 
    static std::optional<double> tryGetMonoWeight(const Peptidoform& pf,
                                                   std::vector<ConversionIssue>& issues_out);
 
    static std::optional<double> tryGetMonoWeight(const PeptidoformIon& pfi);
 
    static std::optional<double> tryGetMonoWeight(const PeptidoformIon& pfi,
                                                   std::vector<ConversionIssue>& issues_out);
 
    static std::optional<double> tryGetMZ(const Peptidoform& pf, int charge);
 
    static std::optional<double> tryGetMZ(const Peptidoform& pf, int charge,
                                           std::vector<ConversionIssue>& issues_out);
 
    static std::optional<double> tryGetMZ(const PeptidoformIon& pfi);
 
    static std::optional<double> tryGetMZ(const PeptidoformIon& pfi,
                                           std::vector<ConversionIssue>& issues_out);
 
 
    //==========================================================================
    // Static Methods - Spectrum Generation
    //==========================================================================
 
    static bool canGenerateSpectrum(const Peptidoform& pf);
 
    static bool canGenerateSpectrum(const PeptidoformIon& pfi);
 
    static std::vector<ConversionIssue> getSpectrumGenerationIssues(const Peptidoform& pf);
 
    static std::vector<ConversionIssue> getSpectrumGenerationIssues(const PeptidoformIon& pfi);
 
    static MSSpectrum generateSpectrum(
      const Peptidoform& pf,
      int min_charge = 1,
      int max_charge = 1,
      const std::string& ion_types = "by",
      bool add_losses = false,
      bool add_metainfo = true);
 
    static MSSpectrum generateSpectrum(
      const PeptidoformIon& pfi,
      int min_charge = 1,
      int max_charge = 1,
      const std::string& ion_types = "by",
      bool add_losses = false,
      bool add_metainfo = true);
 
 
    //==========================================================================
    // Utility Functions
    //==========================================================================
 
    static const char* errorCodeToString(ErrorCode code);
  }; // class ProForma
 
} // namespace OpenMS