MzPAF.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/StringUtils.h>
#include <OpenMS/CHEMISTRY/EmpiricalFormula.h>
#include <OpenMS/CHEMISTRY/AASequence.h>
#include <OpenMS/METADATA/PeptideHit.h>
#include <OpenMS/OpenMSConfig.h>
 
#include <iosfwd>
#include <optional>
#include <utility>
#include <vector>
 
namespace OpenMS
{
 
  //--------------------------------------------------------------------------
  // Data Structures
  //--------------------------------------------------------------------------
 
  enum class MzPAFIonSeries
  {
    A,          
    B,          
    C,          
    X,          
    Y,          
    Z,          
    PRECURSOR,  
    IMMONIUM,   
    INTERNAL,   
    REPORTER,   
    FORMULA,    
    NAMED,      
    UNKNOWN,    
    // The satellite series are appended after UNKNOWN on purpose. They were added later, and
    // the enumerator values are exposed arithmetically to Python (nb::is_arithmetic), so the
    // existing values have to stay put. Do not "tidy" this by moving UNKNOWN back to the end.
    D,          
    V,          
    W           
  };
 
  enum class MzPAFDeltaUnit
  {
    DALTON,  
    PPM      
  };
 
  struct OPENMS_DLLAPI MzPAFNeutralLoss
  {
    EmpiricalFormula formula;   
 
    bool operator==(const MzPAFNeutralLoss& other) const;
    bool operator!=(const MzPAFNeutralLoss& other) const { return !(*this == other); }
  };
 
  struct OPENMS_DLLAPI MzPAFMassDelta
  {
    double value = 0.0;         
    MzPAFDeltaUnit unit = MzPAFDeltaUnit::DALTON; 
 
    bool operator==(const MzPAFMassDelta& other) const;
    bool operator!=(const MzPAFMassDelta& other) const { return !(*this == other); }
  };
 
  struct OPENMS_DLLAPI MzPAFAnnotation
  {
    std::optional<int> analyte_index;               
    MzPAFIonSeries ion_series = MzPAFIonSeries::UNKNOWN; 
    std::optional<int> ordinal;                     
    std::optional<char> immonium_residue;           
    std::optional<std::pair<int, int>> internal_range; 
    std::optional<std::string> reporter_name;            
    std::optional<EmpiricalFormula> formula;        
    std::optional<std::string> named_compound;           
    std::vector<MzPAFNeutralLoss> neutral_losses;   
    std::optional<int> isotope_offset;              
    std::optional<EmpiricalFormula> adduct;         
    std::optional<int> charge;                      
    std::optional<MzPAFMassDelta> mass_delta;       
    std::optional<double> confidence;               
    std::optional<std::string> embedded_sequence;        
    std::optional<char> satellite_subtype;               
 
    bool isValid() const;
 
    bool operator==(const MzPAFAnnotation& other) const;
    bool operator!=(const MzPAFAnnotation& other) const { return !(*this == other); }
  };
 
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const MzPAFAnnotation& ann);
 
  struct OPENMS_DLLAPI MzPAFPeakAnnotations
  {
    std::vector<MzPAFAnnotation> annotations;  
 
    bool empty() const { return annotations.empty(); }
 
    size_t size() const { return annotations.size(); }
 
    bool operator==(const MzPAFPeakAnnotations& other) const;
    bool operator!=(const MzPAFPeakAnnotations& other) const { return !(*this == other); }
  };
 
  //--------------------------------------------------------------------------
  // Error Handling
  //--------------------------------------------------------------------------
 
  enum class MzPAFErrorCode
  {
    UNEXPECTED_CHARACTER,       
    UNCLOSED_BRACKET,           
    INVALID_ION_SERIES,         
    INVALID_NUMBER,             
    INVALID_FORMULA,            
    INVALID_CHARGE,             
    INVALID_DELTA,              
    INVALID_CONFIDENCE,         
    EMPTY_INPUT,                
    UNEXPECTED_END_OF_INPUT,    
    INTERNAL_ERROR              
  };
 
  OPENMS_DLLAPI const char* mzPAFErrorCodeToString(MzPAFErrorCode code);
 
  class OPENMS_DLLAPI MzPAFParseError : public Exception::ParseError
  {
  public:
    MzPAFParseError(
      const char* file,
      int line,
      const char* function,
      MzPAFErrorCode error_code,
      size_t error_position,
      const std::string& input,
      const std::string& message
    ) noexcept;
 
    MzPAFErrorCode getErrorCode() const noexcept { return code_; }
    size_t getPosition() const noexcept { return position_; }
    std::string getFormattedMessage() const;
 
  private:
    MzPAFErrorCode code_;
    size_t position_;
    std::string context_before_;
    std::string context_after_;
 
    void extractContext_(const std::string& input, size_t pos);
  };
 
  //--------------------------------------------------------------------------
  // Parser API
  //--------------------------------------------------------------------------
 
  class OPENMS_DLLAPI MzPAF
  {
  public:
    //--------------------------------------------------------------------------
    // Parsing
    //--------------------------------------------------------------------------
 
    static MzPAFAnnotation parse(const std::string& input);
 
    static MzPAFPeakAnnotations parseMultiple(const std::string& input);
 
    static std::optional<MzPAFAnnotation> tryParse(const std::string& input);
 
    static std::optional<MzPAFPeakAnnotations> tryParseMultiple(const std::string& input);
 
    //--------------------------------------------------------------------------
    // Serialization
    //--------------------------------------------------------------------------
 
    static std::string toString(const MzPAFAnnotation& ann);
 
    static std::string toString(const MzPAFPeakAnnotations& anns);
 
    //--------------------------------------------------------------------------
    // PeakAnnotation Integration
    //--------------------------------------------------------------------------
 
    static PeptideHit::PeakAnnotation toPeakAnnotation(
      const MzPAFAnnotation& mzpaf, double mz, double intensity);
 
    static MzPAFPeakAnnotations fromPeakAnnotation(
      const PeptideHit::PeakAnnotation& peak_annotation);
 
    //--------------------------------------------------------------------------
    // Utilities
    //--------------------------------------------------------------------------
 
    static bool isMzPAFFormat(const std::string& annotation);
 
    static std::optional<double> calculateTheoreticalMZ(
      const MzPAFAnnotation& ann, const AASequence& sequence);
 
    static bool isPeptideFragmentIon(MzPAFIonSeries series);
 
    static char ionSeriesToChar(MzPAFIonSeries series);
 
    static bool charToIonSeries(char c, MzPAFIonSeries& series);
 
  private:
    MzPAF() = delete;  // Static class, no instantiation
  };
 
} // namespace OpenMS