IDMapper.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-2018.
//
// 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: Chris Bielow $
// $Authors: Marc Sturm, Hendrik Weisser, Chris Bielow $
// --------------------------------------------------------------------------

#pragma once

#include <OpenMS/KERNEL/StandardTypes.h>
#include <OpenMS/KERNEL/MSExperiment.h>
#include <OpenMS/KERNEL/FeatureMap.h>
#include <OpenMS/KERNEL/ConsensusMap.h>

#include <OpenMS/DATASTRUCTURES/ListUtils.h>

#include <OpenMS/CONCEPT/LogStream.h>

#include <OpenMS/DATASTRUCTURES/DefaultParamHandler.h>

#include <algorithm>
#include <limits>

namespace OpenMS
{
  class OPENMS_DLLAPI IDMapper :
    public DefaultParamHandler
  {
public:
    enum Measure {MEASURE_PPM = 0, MEASURE_DA};

    IDMapper();

    IDMapper(const IDMapper& cp);

    IDMapper& operator=(const IDMapper& rhs);

    void annotate(PeakMap& map, const std::vector<PeptideIdentification>& peptide_ids, const std::vector<ProteinIdentification>& protein_ids, const bool clear_ids = false, const bool mapMS1 = false)
    {
      checkHits_(peptide_ids);

      if (clear_ids)
      { // start with empty IDs
        std::vector<PeptideIdentification> empty_ids;
        for (PeakMap::iterator it = map.begin(); it != map.end(); ++it)
        {
          it->setPeptideIdentifications(empty_ids);
        }
        std::vector<ProteinIdentification> empty_prot_ids;
        map.setProteinIdentifications(empty_prot_ids);
      }

      if (peptide_ids.empty()) return;

      // append protein identifications
      map.getProteinIdentifications().insert(map.getProteinIdentifications().end(), protein_ids.begin(), protein_ids.end());

      // store mapping of scan RT to index
      std::multimap<double, Size> experiment_precursors;
      for (Size i = 0; i < map.size(); i++)
      {
        experiment_precursors.insert(std::make_pair(map[i].getRT(), i));
      }

      // store mapping of identification RT to index (ignore empty hits)
      std::multimap<double, Size> identifications_precursors;
      for (Size i = 0; i < peptide_ids.size(); ++i)
      {
        if (!peptide_ids[i].empty())
        {
          identifications_precursors.insert(std::make_pair(peptide_ids[i].getRT(), i));
        }
      }
      // note that mappings are sorted by key via multimap (we rely on that down below)

      // remember which peptides were mapped (for stats later)
      std::set<Size> peptides_mapped;

      // calculate the actual mapping
      std::multimap<double, Size>::const_iterator experiment_iterator = experiment_precursors.begin();
      std::multimap<double, Size>::const_iterator identifications_iterator = identifications_precursors.begin();
      // to achieve O(n) complexity we now move along the spectra
      // and for each spectrum we look at the peptide id's with the allowed RT range
      // once we finish a spectrum, we simply move back in the peptide id window a little to get from the
      // right end of the old interval to the left end of the new interval
      while (experiment_iterator != experiment_precursors.end())
      {
        // maybe we hit end() of IDs during the last scan .. go back to a real value
        if (identifications_iterator == identifications_precursors.end())
        {
          --identifications_iterator; // this is valid, since we have at least one peptide ID
        }

        // go to left border of RT interval
        while (identifications_iterator != identifications_precursors.begin() &&
               (experiment_iterator->first - identifications_iterator->first) < rt_tolerance_) // do NOT use fabs() here, since we want the LEFT border
        {
          --identifications_iterator;
        }
        // ... we might have stepped too far left
        if (identifications_iterator != identifications_precursors.end() && ((experiment_iterator->first - identifications_iterator->first) > rt_tolerance_))
        {
          ++identifications_iterator; // get into interval again (we can potentially be at end() afterwards)
        }

        if (identifications_iterator == identifications_precursors.end())
        { // no more ID's, so we don't have any chance of matching the next spectra
          break; // ... do NOT put this block below, since hitting the end of ID's for one spec, still allows to match stuff in the next (when going to left border)
        }

        // run through RT interval
        while (identifications_iterator != identifications_precursors.end() &&
               (identifications_iterator->first - experiment_iterator->first) < rt_tolerance_) // fabs() not required here, since are definitely within left border, and wait until exceeding the right
        {
          if (mapMS1 || 
               // testing whether the m/z fits
               ((!map[experiment_iterator->second].getPrecursors().empty()) && 
                isMatch_(0, peptide_ids[identifications_iterator->second].getMZ(), map[experiment_iterator->second].getPrecursors()[0].getMZ())))
          {
            map[experiment_iterator->second].getPeptideIdentifications().push_back(peptide_ids[identifications_iterator->second]);
            peptides_mapped.insert(identifications_iterator->second);
          }
          ++identifications_iterator;
        }
        // we are the right border now (or likely even beyond)
        ++experiment_iterator;
      }

      // some statistics output
      LOG_INFO << "Peptides assigned to a precursor: " << peptides_mapped.size() << "\n" 
               << "             Unassigned peptides: " << peptide_ids.size() - peptides_mapped.size() << "\n"
               << "       Unmapped (empty) peptides: " << peptide_ids.size() - identifications_precursors.size() << std::endl;

    }

    void annotate(PeakMap& map, FeatureMap fmap, const bool clear_ids = false, const bool mapMS1 = false)
    {
      const std::vector<ProteinIdentification>& protein_ids = fmap.getProteinIdentifications();
      std::vector<PeptideIdentification> peptide_ids;

      for (FeatureMap::const_iterator it = fmap.begin(); it != fmap.end(); ++it)
      {
        const std::vector<PeptideIdentification>& pi = it->getPeptideIdentifications();
        for (std::vector<PeptideIdentification>::const_iterator itp = pi.begin(); itp != pi.end(); ++itp)
        {
          peptide_ids.push_back(*itp);
          // if pepID has no m/z or RT, use the values of the feature
          if (!itp->hasMZ()) peptide_ids.back().setMZ(it->getMZ());
          if (!itp->hasRT()) peptide_ids.back().setRT(it->getRT());
        }

      }
      annotate(map, peptide_ids, protein_ids, clear_ids, mapMS1);
    }

    void annotate(FeatureMap& map, const std::vector<PeptideIdentification>& ids, const std::vector<ProteinIdentification>& protein_ids, bool use_centroid_rt = false, bool use_centroid_mz = false, const PeakMap& spectra = PeakMap());

    void annotate(ConsensusMap& map, const std::vector<PeptideIdentification>& ids, 
                  const std::vector<ProteinIdentification>& protein_ids, 
                  bool measure_from_subelements = false, 
                  bool annotate_ids_with_subelements = false, 
                  const PeakMap& spectra = PeakMap());


    struct SpectraIdentificationState
    {
      std::vector<Size> no_precursors;
      std::vector<Size> identified;
      std::vector<Size> unidentified;
    }; 

    static SpectraIdentificationState mapPrecursorsToIdentifications(const PeakMap& spectra, 
                                                                     const std::vector<PeptideIdentification>& ids, 
                                                                     double mz_tol = 0.001, 
                                                                     double rt_tol = 0.001)
    {
      SpectraIdentificationState ret;
      for (Size spectrum_index = 0; spectrum_index < spectra.size(); ++spectrum_index)
      {
        const MSSpectrum& spectrum = spectra[spectrum_index];
        if (!spectrum.getPrecursors().empty())
        {
          bool identified(false);
          const std::vector<Precursor>& precursors = spectrum.getPrecursors();

          // check if precursor has been identified
          for (Size i_p = 0; i_p < precursors.size(); ++i_p)
          {
            // check by precursor mass and spectrum RT
            double mz_p = precursors[i_p].getMZ();
            double rt_s = spectrum.getRT();
          
            for (Size i_id = 0; i_id != ids.size(); ++i_id)
            {
              const PeptideIdentification& pid = ids[i_id];

              // do not count empty ids as identification of a spectrum
              if (pid.getHits().empty()) continue;

              double mz_id = pid.getMZ();
              double rt_id = pid.getRT();

              if ( fabs(mz_id - mz_p) < mz_tol && fabs(rt_s - rt_id) < rt_tol )
              {
                identified = true;
                break; 
              }
            }
          }   
          if (!identified) 
          {
            ret.unidentified.push_back(spectrum_index);
          }
          else
          {
            ret.identified.push_back(spectrum_index);
          }
        }
        else
        {
          ret.no_precursors.push_back(spectrum_index);
        }
      }
      return ret;
    }


protected:
    void updateMembers_() override;

    double rt_tolerance_;
    double mz_tolerance_;
    Measure measure_;
    bool ignore_charge_;

    double getAbsoluteMZTolerance_(const double mz) const;

    bool isMatch_(const double rt_distance, const double mz_theoretical, const double mz_observed) const;

    void checkHits_(const std::vector<PeptideIdentification>& ids) const;

    void getIDDetails_(const PeptideIdentification& id, double& rt_pep, DoubleList& mz_values, IntList& charges, bool use_avg_mass = false) const;

    void increaseBoundingBox_(DBoundingBox<2>& box);

    bool checkMassType_(const std::vector<DataProcessing>& processing) const;

  };

} // namespace OpenMS