DBSuitability.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: Tom Waschischeck $
// $Authors: Tom Waschischeck $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/CONCEPT/Types.h>
#include <OpenMS/DATASTRUCTURES/DefaultParamHandler.h>
#include <OpenMS/FORMAT/FASTAFile.h>
#include <OpenMS/METADATA/ProteinIdentification.h>
 
#include <cfloat>
#include <vector>
 
#include <boost/regex.hpp>
 
namespace OpenMS
{
  class ParamXMLFile;
  class PeptideIdentification;
  class PeptideHit;
  class MSExperiment;
 
  class OPENMS_DLLAPI DBSuitability:
    public DefaultParamHandler
  {
  public:
    struct OPENMS_DLLAPI SuitabilityData
    {
      Size num_top_novo = 0;
 
      Size num_top_db = 0;
      
      Size num_interest = 0;
 
      Size num_re_ranked = 0;
 
      double cut_off = DBL_MAX;
 
      double suitability = 0;
 
      double suitability_no_rerank = 0;
 
      double suitability_corr_no_rerank = 0;
 
      // resets all members to their defaults
      void clear();
 
      void setCorrectionFactor(double factor);
 
      double getCorrectionFactor() const;
 
      double getCorrectedNovoHits() const;
 
      double getCorrectedSuitability() const;
 
      SuitabilityData simulateNoReRanking() const;
 
    private:
      double corr_factor = -1;
 
      double num_top_novo_corr = 0;
 
      double suitability_corr = 0;
    };
 
    DBSuitability();
 
    ~DBSuitability() override = default;
 
    friend class DBSuitability_friend;
 
    void compute(std::vector<PeptideIdentification>&& pep_ids, const MSExperiment& exp, const std::vector<FASTAFile::FASTAEntry>& original_fasta, const std::vector<FASTAFile::FASTAEntry>& novo_fasta, const ProteinIdentification::SearchParameters& search_params);
 
    const std::vector<SuitabilityData>& getResults() const;
 
  private:
    std::vector<SuitabilityData> results_;
 
    const boost::regex decoy_pattern_;
 
    double getDecoyDiff_(const PeptideIdentification& pep_id) const;
 
    double getDecoyCutOff_(const std::vector<PeptideIdentification>& pep_ids, double reranking_cutoff_percentile) const;
 
    bool isNovoHit_(const PeptideHit& hit) const;
 
    bool checkScoreBetterThanThreshold_(const PeptideHit& hit, double threshold, bool higher_score_better) const;
 
    std::pair<String, Param> extractSearchAdapterInfoFromMetaValues_(const ProteinIdentification::SearchParameters& meta_values) const;
 
    void writeIniFile_(const Param& parameters, const String& filename) const;
 
    std::vector<PeptideIdentification> runIdentificationSearch_(const MSExperiment& exp, const std::vector<FASTAFile::FASTAEntry>& fasta_data, const String& adapter_name, Param& parameters) const;
 
    std::vector<FASTAFile::FASTAEntry> getSubsampledFasta_(const std::vector<FASTAFile::FASTAEntry>& fasta_data, double subsampling_rate) const;
 
    void calculateSuitability_(const std::vector<PeptideIdentification>& pep_ids, SuitabilityData& data) const;
 
    void appendDecoys_(std::vector<FASTAFile::FASTAEntry>& fasta) const;
 
    double extractScore_(const PeptideHit& pep_hit) const;
 
    double calculateCorrectionFactor_(const SuitabilityData& data, const SuitabilityData& data_sampled, double sampling_rate) const;
 
    UInt numberOfUniqueProteins_(const std::vector<PeptideIdentification>& peps, UInt number_of_hits = 1) const;
 
    Size getIndexWithMedianNovoHits_(const std::vector<SuitabilityData>& data) const;
 
    double getScoreMatchingFDR_(const std::vector<PeptideIdentification>& pep_ids, double FDR, const String& score_name, bool higher_score_better) const;
  };
 
  // friend class to test private member functions
  class DBSuitability_friend
  {
  public:
    DBSuitability_friend() = default;
 
    ~DBSuitability_friend() = default;
 
    std::vector<FASTAFile::FASTAEntry> getSubsampledFasta(const std::vector<FASTAFile::FASTAEntry>& fasta_data, double subsampling_rate)
    {
      return suit_.getSubsampledFasta_(fasta_data, subsampling_rate);
    }
 
    void appendDecoys(std::vector<FASTAFile::FASTAEntry>& fasta)
    {
      suit_.appendDecoys_(fasta);
    }
 
    double calculateCorrectionFactor(const DBSuitability::SuitabilityData& data, const DBSuitability::SuitabilityData& data_sampled, double sampling_rate)
    {
      return suit_.calculateCorrectionFactor_(data, data_sampled, sampling_rate);
    }
 
    UInt numberOfUniqueProteins(const std::vector<PeptideIdentification>& peps, UInt number_of_hits = 1)
    {
      return suit_.numberOfUniqueProteins_(peps, number_of_hits);
    }
 
    Size getIndexWithMedianNovoHits(const std::vector<DBSuitability::SuitabilityData>& data)
    {
      return suit_.getIndexWithMedianNovoHits_(data);
    }
 
    double getScoreMatchingFDR(const std::vector<PeptideIdentification>& pep_ids, double FDR, String score_name, bool higher_score_better)
    {
      return suit_.getScoreMatchingFDR_(pep_ids, FDR, score_name, higher_score_better);
    }
 
    /* Not tested:
      getDecoyDiff_, getDecoyCutOff_, isNovoHit_, checkScoreBetterThanThreshold_
      Reason: These functions are essential to the normal suitability calculation and if something would not work, the test for 'compute' would fail.
 
      extractSearchAdapterInfoFromMetaValues_, writeIniFile_, extractScore_
      Reason: These functions are very straightforeward.
 
      runIdentificationSearch_
      Reason: This function simulates a whole workflow and testing it would be to complicated.
    */
 
  private:
    DBSuitability suit_;
  };
}