AccurateMassSearchEngine.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: Erhan Kenar, Chris Bielow $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/KERNEL/MassTrace.h>
#include <OpenMS/KERNEL/Feature.h>
#include <OpenMS/KERNEL/ConsensusFeature.h>
#include <OpenMS/KERNEL/FeatureMap.h>
#include <OpenMS/KERNEL/ConsensusMap.h>
#include <OpenMS/FORMAT/MzTab.h>
#include <OpenMS/FORMAT/MzTabM.h>
#include <OpenMS/DATASTRUCTURES/DefaultParamHandler.h>
#include <OpenMS/DATASTRUCTURES/StringUtils.h>
#include <OpenMS/DATASTRUCTURES/ListUtils.h>
#include <OpenMS/CONCEPT/ProgressLogger.h>
#include <OpenMS/SYSTEM/File.h>
#include <OpenMS/CHEMISTRY/AdductInfo.h>
 
 
#include <iosfwd>
#include <vector>
 
namespace OpenMS
{
  class OPENMS_DLLAPI AccurateMassSearchResult
  {
  public:
    AccurateMassSearchResult();
 
    ~AccurateMassSearchResult();
 
    AccurateMassSearchResult(const AccurateMassSearchResult& other);
 
    AccurateMassSearchResult& operator=(const AccurateMassSearchResult& other);
 
    double getObservedMZ() const;
 
    void setObservedMZ(const double& mz);
 
    double getCalculatedMZ() const;
 
    void setCalculatedMZ(const double& mz);
 
    double getQueryMass() const;
 
    void setQueryMass(const double& mass);
 
    double getFoundMass() const;
 
    void setFoundMass(const double& mass);
 
    Int getCharge() const;
 
    void setCharge(const Int& ch);
 
    double getMZErrorPPM() const;
 
    void setMZErrorPPM(const double ppm);
 
    double getObservedRT() const;
 
    void setObservedRT(const double& rt);
 
    double getObservedIntensity() const;
 
    void setObservedIntensity(const double& intensity);
 
    std::vector<double> getIndividualIntensities() const;
 
    void setIndividualIntensities(const std::vector<double>& indiv_ints);
 
    Size getMatchingIndex() const;
 
    void setMatchingIndex(const Size& idx);
 
    Size getSourceFeatureIndex() const;
 
    void setSourceFeatureIndex(const Size& idx);
 
    const std::string& getFoundAdduct() const;
 
    void setFoundAdduct(const std::string& add);
 
    const std::string& getFormulaString() const;
 
    void setEmpiricalFormula(const std::string& ep);
 
    const std::vector<std::string>& getMatchingHMDBids() const;
 
    void setMatchingHMDBids(const std::vector<std::string>& ids);
 
    const std::vector<double>& getMasstraceIntensities() const;
 
    void setMasstraceIntensities(const std::vector<double>& intensities);
 
    double getIsotopesSimScore() const;
 
    void setIsotopesSimScore(const double& score);
 
    friend OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const AccurateMassSearchResult& amsr);
 
private:
    double observed_mz_;                   
    double theoretical_mz_;                
    double searched_mass_;                 
    double db_mass_;                       
    Int charge_;                           
    double mz_error_ppm_;                  
    double observed_rt_;                   
    double observed_intensity_;            
    std::vector<double> individual_intensities_; 
    Size matching_index_;                  
    Size source_feature_index_;            
 
    std::string found_adduct_;                  
    std::string empirical_formula_;             
    std::vector<std::string> matching_hmdb_ids_;
 
    std::vector<double> mass_trace_intensities_; 
    double isotopes_sim_score_;            
  };
 
  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const AccurateMassSearchResult& amsr);
 
  class OPENMS_DLLAPI AccurateMassSearchEngine :
    public DefaultParamHandler,
    public ProgressLogger
  {
public:
 
    static constexpr char search_engine_identifier[] = "AccurateMassSearchEngine";
 
    AccurateMassSearchEngine();
 
    ~AccurateMassSearchEngine() override;
 
    void queryByMZ(const double& observed_mz, const Int& observed_charge, const std::string& ion_mode, std::vector<AccurateMassSearchResult>& results, const EmpiricalFormula& observed_adduct = EmpiricalFormula()) const;
    void queryByFeature(const Feature& feature, const Size& feature_index, const std::string& ion_mode, std::vector<AccurateMassSearchResult>& results) const;
    void queryByConsensusFeature(const ConsensusFeature& cfeat, const Size& cf_index, const Size& number_of_maps, const std::string& ion_mode, std::vector<AccurateMassSearchResult>& results) const;
 
    void run(FeatureMap&, MzTab&) const;
 
    void run(FeatureMap&, MzTabM&) const;
 
    void run(ConsensusMap&, MzTab&) const;
 
    void init();
 
protected:
    void updateMembers_() override;
 
private:
 
    template <typename MAPTYPE> std::string resolveAutoMode_(const MAPTYPE& map) const
    {
      std::string ion_mode_internal;
      std::string ion_mode_detect_msg;
      if (map.size() > 0)
      {
        if (map[0].metaValueExists("scan_polarity"))
        {
          StringList pols = ListUtils::create<std::string>(StringUtils::toStr(map[0].getMetaValue("scan_polarity")), ';');
          if (pols.size() == 1 && !pols[0].empty())
          {
            StringUtils::toLower(pols[0]);
            if (pols[0] == "positive" || pols[0] == "negative")
            {
              ion_mode_internal = pols[0];
              OPENMS_LOG_INFO << "Setting auto ion-mode to '" << ion_mode_internal << "' for file " << File::basename(map.getLoadedFilePath()) << std::endl;
            }
            else ion_mode_detect_msg ="Meta value 'scan_polarity' does not contain unknown ion mode" + StringUtils::toStr(map[0].getMetaValue("scan_polarity"));
          }
          else
          {
            ion_mode_detect_msg ="ambiguous ion mode: " + StringUtils::toStr(map[0].getMetaValue("scan_polarity"));
          }
        }
        else
        {
          ion_mode_detect_msg =std::string("Meta value 'scan_polarity' not found in (Consensus-)Feature map");
        }
      }
      else
      { // do nothing, since map is
        OPENMS_LOG_INFO << "Meta value 'scan_polarity' cannot be determined since (Consensus-)Feature map is empty!" << std::endl;
      }
 
      if (!ion_mode_detect_msg.empty())
      {
        throw Exception::InvalidParameter(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION,std::string("Auto ionization mode could not resolve ion mode of data (") + ion_mode_detect_msg + "!");
      }
 
      return ion_mode_internal;
    }
 
    void parseMappingFile_(const StringList&);
    void parseStructMappingFile_(const StringList&);
    void parseAdductsFile_(const std::string& filename, std::vector<AdductInfo>& result);
    void searchMass_(double neutral_query_mass, double diff_mass, std::pair<Size, Size>& hit_indices) const;
 
    void annotate_(const std::vector<AccurateMassSearchResult>&, BaseFeature&) const;
 
    std::vector<AccurateMassSearchResult> extractQueryResults_(const Feature& feature, const Size& feature_index, const std::string& ion_mode_internal, Size& dummy_count) const;
 
    void addMatchesToID_(
      IdentificationData& id,
      const std::vector<AccurateMassSearchResult>& amr, 
      const IdentificationData::InputFileRef& file_ref,
      const IdentificationData::ScoreTypeRef& mass_error_ppm_score_ref,
      const IdentificationData::ScoreTypeRef& mass_error_Da_score_ref,
      const IdentificationData::ProcessingStepRef& step_ref,
      BaseFeature& f) const;
 
    double computeCosineSim_(const std::vector<double>& x, const std::vector<double>& y) const;
 
    double computeIsotopePatternSimilarity_(const Feature& feat, const EmpiricalFormula& form) const;
 
    typedef std::vector<std::vector<AccurateMassSearchResult> > QueryResultsTable;
 
    void exportMzTab_(const QueryResultsTable& overall_results, const Size number_of_maps, MzTab& mztab_out, const std::vector<std::string>& file_locations) const;
 
    void exportMzTabM_(const FeatureMap& fmap, MzTabM& mztabm_out) const;
 
    typedef std::vector<std::vector<std::string> > MassIDMapping;
    typedef std::map<std::string, std::vector<std::string> > HMDBPropsMapping;
 
    struct MappingEntry_
    {
      double mass;
      std::vector<std::string> massIDs;
      std::string formula;
    };
    std::vector<MappingEntry_> mass_mappings_;
 
    struct CompareEntryAndMass_ // defined here to allow for inlining by compiler
    {
      double asMass(const MappingEntry_& v) const
      {
        return v.mass;
      }
 
      double asMass(double t) const
      {
        return t;
      }
 
      template <typename T1, typename T2>
      bool operator()(T1 const& t1, T2 const& t2) const
      {
        return asMass(t1) < asMass(t2);
      }
 
    };
 
    HMDBPropsMapping hmdb_properties_mapping_;
 
    bool is_initialized_; 
 
    bool legacyID_ = true;
 
    double mass_error_value_;
    std::string mass_error_unit_;
    std::string ion_mode_;
    bool iso_similarity_;
 
    std::string pos_adducts_fname_;
    std::string neg_adducts_fname_;
 
    StringList db_mapping_file_;
    StringList db_struct_file_;
 
    std::vector<AdductInfo> pos_adducts_;
    std::vector<AdductInfo> neg_adducts_;
 
    std::string database_name_;
    std::string database_version_;
    std::string database_location_;
 
    bool keep_unidentified_masses_;
  };
 
}