← Back to branch summary

~ubuntu-branches/ubuntu/wily/openms/wily

« back to all changes in this revision

Viewing changes to include/OpenMS/KERNEL/ConsensusFeature.h

  • Committer: Package Import Robot
  • Author(s): Filippo Rusconi
  • Date: 2013-12-20 11:30:16 UTC
  • mfrom: (5.1.2 sid)
  • Revision ID: package-import@ubuntu.com-20131220113016-wre5g9bteeheq6he
Tags: 1.11.1-3
* remove version number from libbost development package names;
* ensure that AUTHORS is correctly shipped in all packages.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/OpenMS/KERNEL/ConsensusFeature.h
1
 
// -*- mode: C++; tab-width: 2; -*-
2
 
// vi: set ts=2:
3
 
//
4
 
// --------------------------------------------------------------------------
5
 
//                   OpenMS Mass Spectrometry Framework
6
 
// --------------------------------------------------------------------------
7
 
//  Copyright (C) 2003-2011 -- Oliver Kohlbacher, Knut Reinert
8
 
//
9
 
//  This library is free software; you can redistribute it and/or
10
 
//  modify it under the terms of the GNU Lesser General Public
11
 
//  License as published by the Free Software Foundation; either
12
 
//  version 2.1 of the License, or (at your option) any later version.
13
 
//
14
 
//  This library is distributed in the hope that it will be useful,
15
 
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
16
 
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17
 
//  Lesser General Public License for more details.
18
 
//
19
 
//  You should have received a copy of the GNU Lesser General Public
20
 
//  License along with this library; if not, write to the Free Software
21
 
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
1
// --------------------------------------------------------------------------
 
2
//                   OpenMS -- Open-Source Mass Spectrometry
 
3
// --------------------------------------------------------------------------
 
4
// Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
 
5
// ETH Zurich, and Freie Universitaet Berlin 2002-2013.
 
6
//
 
7
// This software is released under a three-clause BSD license:
 
8
//  * Redistributions of source code must retain the above copyright
 
9
//    notice, this list of conditions and the following disclaimer.
 
10
//  * Redistributions in binary form must reproduce the above copyright
 
11
//    notice, this list of conditions and the following disclaimer in the
 
12
//    documentation and/or other materials provided with the distribution.
 
13
//  * Neither the name of any author or any participating institution
 
14
//    may be used to endorse or promote products derived from this software
 
15
//    without specific prior written permission.
 
16
// For a full list of authors, refer to the file AUTHORS.
 
17
// --------------------------------------------------------------------------
 
18
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 
19
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 
20
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 
21
// ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
 
22
// INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 
23
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 
24
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 
25
// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 
26
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 
27
// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 
28
// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
22
29
//
23
30
// --------------------------------------------------------------------------
24
31
// $Maintainer: Erhan Kenar $
37
44
 
38
45
namespace OpenMS
39
46
{
40
 
        /**
41
 
                @brief A 2-dimensional consensus feature.
42
 
 
43
 
                A consensus feature represents corresponding features in multiple feature
44
 
                maps. The corresponding features are represented a set of @ref
45
 
                FeatureHandle instances.  Each ConsensusFeature "contains" zero or more
46
 
                FeatureHandles.
47
 
 
48
 
                @see ConsensusMap
49
 
 
50
 
                @ingroup Kernel
51
 
        */
52
 
        class OPENMS_DLLAPI ConsensusFeature
53
 
                : public BaseFeature,
54
 
                        public std::set<FeatureHandle, FeatureHandle::IndexLess>
55
 
        {
56
 
         public:
57
 
                ///Type definitions
58
 
                //@{
59
 
                typedef std::set<FeatureHandle, FeatureHandle::IndexLess> HandleSetType;
60
 
                //@}
61
 
 
62
 
                /// Compare by size(), the number of consensus elements
63
 
                struct SizeLess
64
 
                        : std::binary_function < ConsensusFeature, ConsensusFeature, bool >
65
 
                {
66
 
                        inline bool operator () ( ConsensusFeature const & left, ConsensusFeature const & right ) const
67
 
                        {
68
 
                                return ( left.size() < right.size() );
69
 
                        }
70
 
                        inline bool operator () ( ConsensusFeature const & left, UInt64 const & right ) const
71
 
                        {
72
 
                                return ( left.size() < right );
73
 
                        }
74
 
                        inline bool operator () ( UInt64 const & left, ConsensusFeature const & right ) const
75
 
                        {
76
 
                                return ( left< right.size() );
77
 
                        }
78
 
                        inline bool operator () ( const UInt64 & left,  const UInt64 & right ) const
79
 
                        {
80
 
                                return ( left < right );
81
 
                        }
82
 
                };
83
 
 
84
 
                /// Compare by the sets of consensus elements (lexicographically)
85
 
                struct MapsLess
86
 
                        : std::binary_function < ConsensusFeature, ConsensusFeature, bool >
87
 
                {
88
 
                        inline bool operator () ( ConsensusFeature const & left, ConsensusFeature const & right ) const
89
 
                        {
90
 
                                return std::lexicographical_compare( left.begin(), left.end(), right.begin(), right.end(), FeatureHandle::IndexLess() );
91
 
                        }
92
 
                };
93
 
 
94
 
 
95
 
                ///@name Constructors and Destructor
96
 
                //@{
97
 
                /// Default constructor
98
 
                ConsensusFeature();
99
 
 
100
 
                /// Copy constructor
101
 
                ConsensusFeature(const ConsensusFeature& rhs);
102
 
 
103
 
                /// Constructor from basic feature
104
 
                ConsensusFeature(const BaseFeature& feature);
105
 
 
106
 
                /**
107
 
                        @brief Constructor with map and element index for a singleton consensus
108
 
                        feature.
109
 
 
110
 
                        Sets the consensus feature position and intensity to the values of @p element as well.
111
 
                */
112
 
                ConsensusFeature(UInt64 map_index, const Peak2D& element, UInt64 element_index);
113
 
 
114
 
                /**
115
 
                        @brief Constructor with map index for a singleton consensus     feature.
116
 
 
117
 
                        Sets the consensus feature position, intensity, charge, quality, and peptide identifications to the values of @p element as well.
118
 
                */
119
 
                ConsensusFeature(UInt64 map_index, const BaseFeature& element);
120
 
 
121
 
                /// Assignment operator
122
 
                ConsensusFeature& operator=(const ConsensusFeature& rhs);
123
 
 
124
 
                /// Destructor
125
 
                virtual ~ConsensusFeature();
126
 
                //@}
127
 
 
128
 
 
129
 
                ///@name Management of feature handles
130
 
                //@{
131
 
                /**
132
 
                @brief Adds an feature handle into the consensus feature
133
 
 
134
 
                @exception Exception::InvalidValue is thrown if a handle with the same map index and unique id already exists.
135
 
                */
136
 
                void insert(const FeatureHandle& handle);
137
 
 
138
 
                /// Adds all feature handles in @p handle_set to this consensus feature.
139
 
                void insert(const HandleSetType& handle_set);
140
 
 
141
 
                /**
142
 
                        @brief Creates a FeatureHandle and adds it
143
 
 
144
 
                        @exception Exception::InvalidValue is thrown if a handle with the same map index and unique id already exists.
145
 
                */
146
 
                void insert(UInt64 map_index, const Peak2D& element, UInt64 element_index);
147
 
 
148
 
                /**
149
 
                        @brief Creates a FeatureHandle and adds it
150
 
 
151
 
                        @exception Exception::InvalidValue is thrown if a handle with the same map index and unique id already exists.
152
 
                */
153
 
                void insert(UInt64 map_index, const BaseFeature& element);
154
 
 
155
 
                /// Non-mutable access to the contained feature handles
156
 
                const HandleSetType& getFeatures() const;
157
 
                //@}
158
 
 
159
 
                ///@name Accessors
160
 
                //@{
161
 
                /// Returns the position range of the contained elements
162
 
                DRange<2> getPositionRange() const;
163
 
                /// Returns the intensity range of the contained elements
164
 
                DRange<1> getIntensityRange() const;
165
 
                
166
 
                //@}
167
 
 
168
 
                /**
169
 
       @brief Computes and updates the consensus position, intensity, and charge.
170
 
 
171
 
       The position and intensity of the contained feature handles is averaged.
172
 
       The most frequent charge state wins, while the tie breaking prefers
173
 
       smaller (absolute) charges.
174
 
 
175
 
       @note This method has to be called explicitly, <i>after</i> adding the feature handles.
176
 
       */
177
 
                void computeConsensus();
178
 
 
179
 
                /**
180
 
                       @brief Computes and updates the consensus position, intensity, and charge.
181
 
 
182
 
                       The m/z position is the lowest m/z value of the feature handles. The RT position and intensity of the contained feature handles is averaged.
183
 
                       The most frequent charge state wins, while the tie breaking prefers
184
 
                       smaller (absolute) charges.
185
 
 
186
 
                       @note This method has to be called explicitly, <i>after</i> adding the feature handles.
187
 
                 */
188
 
                void computeMonoisotopicConsensus();
189
 
 
190
 
                /**
191
 
       @brief Computes the uncharged parent RT & mass, assuming the handles are charge variants.
192
 
 
193
 
       The position of the feature handles (decharged) is averaged (using intensity as weights if @param intensity_weighted_averaging is true).
194
 
       Intensities are summed up.
195
 
       Charge is set to 0.
196
 
       Mass calculation: If the given features contain a metavalue "dc_charge_adduct_mass" then this will be used as adduct mass instead of
197
 
       weight(H+) * charge.
198
 
 
199
 
       @note This method has to be called explicitly, <i>after</i> adding the feature handles.
200
 
       
201
 
       @param fm Input feature map, which provides additional information on the features
202
 
       @param intensity_weighted_averaging Use unweighted averaging (default) or weighted by intensity
203
 
    */
204
 
                void computeDechargeConsensus(const FeatureMap<>& fm, bool intensity_weighted_averaging=false);
205
 
 
206
 
        };
207
 
 
208
 
        ///Print the contents of a ConsensusFeature to a stream
209
 
        OPENMS_DLLAPI std::ostream& operator << (std::ostream& os, const ConsensusFeature& cons);
 
47
  /**
 
48
    @brief A 2-dimensional consensus feature.
 
49
 
 
50
    A consensus feature represents corresponding features in multiple feature
 
51
    maps. The corresponding features are represented a set of @ref
 
52
    FeatureHandle instances.  Each ConsensusFeature "contains" zero or more
 
53
    FeatureHandles.
 
54
 
 
55
    @see ConsensusMap
 
56
 
 
57
    @ingroup Kernel
 
58
  */
 
59
  class OPENMS_DLLAPI ConsensusFeature :
 
60
    public BaseFeature
 
61
  {
 
62
public:
 
63
    ///Type definitions
 
64
    //@{
 
65
    typedef std::set<FeatureHandle, FeatureHandle::IndexLess> HandleSetType;
 
66
    typedef HandleSetType::const_iterator const_iterator;
 
67
    typedef HandleSetType::iterator iterator;
 
68
    typedef HandleSetType::const_reverse_iterator const_reverse_iterator;
 
69
    typedef HandleSetType::reverse_iterator reverse_iterator;
 
70
    //@}
 
71
 
 
72
    /// Compare by size(), the number of consensus elements
 
73
    struct SizeLess :
 
74
      std::binary_function<ConsensusFeature, ConsensusFeature, bool>
 
75
    {
 
76
      inline bool operator()(ConsensusFeature const & left, ConsensusFeature const & right) const
 
77
      {
 
78
        return left.size() < right.size();
 
79
      }
 
80
 
 
81
      inline bool operator()(ConsensusFeature const & left, UInt64 const & right) const
 
82
      {
 
83
        return left.size() < right;
 
84
      }
 
85
 
 
86
      inline bool operator()(UInt64 const & left, ConsensusFeature const & right) const
 
87
      {
 
88
        return left < right.size();
 
89
      }
 
90
 
 
91
      inline bool operator()(const UInt64 & left, const UInt64 & right) const
 
92
      {
 
93
        return left < right;
 
94
      }
 
95
 
 
96
    };
 
97
 
 
98
    /// Compare by the sets of consensus elements (lexicographically)
 
99
    struct MapsLess :
 
100
      std::binary_function<ConsensusFeature, ConsensusFeature, bool>
 
101
    {
 
102
      inline bool operator()(ConsensusFeature const & left, ConsensusFeature const & right) const
 
103
      {
 
104
        return std::lexicographical_compare(left.begin(), left.end(), right.begin(), right.end(), FeatureHandle::IndexLess());
 
105
      }
 
106
 
 
107
    };
 
108
 
 
109
    /// slim struct to feed the need for systematically storing of ratios ( @see MSQuantifications ).
 
110
    struct Ratio
 
111
    {
 
112
      Ratio()
 
113
      {
 
114
      }
 
115
 
 
116
      Ratio(const Ratio & rhs)
 
117
      {
 
118
        ratio_value_ = rhs.ratio_value_;
 
119
        denominator_ref_ = rhs.denominator_ref_;
 
120
        numerator_ref_ = rhs.numerator_ref_;
 
121
        description_ = rhs.description_;
 
122
      }
 
123
 
 
124
      virtual ~Ratio()
 
125
      {
 
126
      }
 
127
 
 
128
      Ratio & operator=(const Ratio & rhs)
 
129
      {
 
130
        if (&rhs != this)
 
131
        {
 
132
          ratio_value_ = rhs.ratio_value_;
 
133
          denominator_ref_ = rhs.denominator_ref_;
 
134
          numerator_ref_ = rhs.numerator_ref_;
 
135
          description_ = rhs.description_;
 
136
        }
 
137
        return *this;
 
138
      }
 
139
 
 
140
      DoubleReal ratio_value_;
 
141
      String denominator_ref_;
 
142
      String numerator_ref_;
 
143
      std::vector<String> description_;
 
144
      //TODO ratio cv info
 
145
    };
 
146
 
 
147
    ///@name Constructors and Destructor
 
148
    //@{
 
149
    /// Default constructor
 
150
    ConsensusFeature();
 
151
 
 
152
    /// Copy constructor
 
153
    ConsensusFeature(const ConsensusFeature & rhs);
 
154
 
 
155
    /// Constructor from basic feature
 
156
    explicit ConsensusFeature(const BaseFeature & feature);
 
157
 
 
158
    /**
 
159
      @brief Constructor with map and element index for a singleton consensus
 
160
      feature.
 
161
 
 
162
      Sets the consensus feature position and intensity to the values of @p element as well.
 
163
    */
 
164
    ConsensusFeature(UInt64 map_index, const Peak2D & element, UInt64 element_index);
 
165
 
 
166
    /**
 
167
      @brief Constructor with map index for a singleton consensus feature.
 
168
 
 
169
      Sets the consensus feature position, intensity, charge, quality, and peptide identifications
 
170
      to the values of @p element as well.
 
171
    */
 
172
    ConsensusFeature(UInt64 map_index, const BaseFeature & element);
 
173
 
 
174
    /// Assignment operator
 
175
    ConsensusFeature & operator=(const ConsensusFeature & rhs);
 
176
 
 
177
    /// Destructor
 
178
    virtual ~ConsensusFeature();
 
179
    //@}
 
180
 
 
181
 
 
182
    ///@name Management of feature handles
 
183
    //@{
 
184
 
 
185
    /**
 
186
      @brief Adds all feature handles (of the CF) into the consensus feature
 
187
    */
 
188
    void insert(const ConsensusFeature & cf);
 
189
 
 
190
    /**
 
191
      @brief Adds an feature handle into the consensus feature
 
192
 
 
193
      @exception Exception::InvalidValue is thrown if a handle with the same map index and unique
 
194
      id already exists.
 
195
    */
 
196
    void insert(const FeatureHandle & handle);
 
197
 
 
198
    /// Adds all feature handles in @p handle_set to this consensus feature.
 
199
    void insert(const HandleSetType & handle_set);
 
200
 
 
201
    /**
 
202
      @brief Creates a FeatureHandle and adds it
 
203
 
 
204
      @exception Exception::InvalidValue is thrown if a handle with the same map index and unique
 
205
      id already exists.
 
206
    */
 
207
    void insert(UInt64 map_index, const Peak2D & element, UInt64 element_index);
 
208
 
 
209
    /**
 
210
      @brief Creates a FeatureHandle and adds it
 
211
 
 
212
      @exception Exception::InvalidValue is thrown if a handle with the same map index and unique
 
213
      id already exists.
 
214
    */
 
215
    void insert(UInt64 map_index, const BaseFeature & element);
 
216
 
 
217
    /// Non-mutable access to the contained feature handles
 
218
    const HandleSetType & getFeatures() const;
 
219
    //@}
 
220
 
 
221
    ///@name Accessors
 
222
    //@{
 
223
    /// Returns the position range of the contained elements
 
224
    DRange<2> getPositionRange() const;
 
225
    /// Returns the intensity range of the contained elements
 
226
    DRange<1> getIntensityRange() const;
 
227
 
 
228
    //@}
 
229
 
 
230
    /**
 
231
      @brief Computes and updates the consensus position, intensity, and charge.
 
232
 
 
233
      The position and intensity of the contained feature handles is averaged.
 
234
      The most frequent charge state wins, while the tie breaking prefers
 
235
      smaller (absolute) charges.
 
236
 
 
237
      @note This method has to be called explicitly, <i>after</i> adding the feature handles.
 
238
    */
 
239
    void computeConsensus();
 
240
 
 
241
    /**
 
242
      @brief Computes and updates the consensus position, intensity, and charge.
 
243
 
 
244
      The m/z position is the lowest m/z value of the feature handles. The RT position and intensity
 
245
      of the contained feature handles is averaged. The most frequent charge state wins, while the
 
246
      tie breaking prefers smaller (absolute) charges.
 
247
 
 
248
      @note This method has to be called explicitly, <i>after</i> adding the feature handles.
 
249
    */
 
250
    void computeMonoisotopicConsensus();
 
251
 
 
252
    /**
 
253
      @brief Computes the uncharged parent RT & mass, assuming the handles are charge variants.
 
254
 
 
255
      The position of the feature handles (decharged) is averaged (using intensity as weights if
 
256
      @param intensity_weighted_averaging is true). Intensities are summed up. Charge is set to 0.
 
257
      Mass calculation: If the given features contain a metavalue "dc_charge_adduct_mass" then this
 
258
      will be used as adduct mass instead of weight(H+) * charge.
 
259
 
 
260
      @note This method has to be called explicitly, <i>after</i> adding the feature handles.
 
261
 
 
262
      @param fm Input feature map, which provides additional information on the features
 
263
      @param intensity_weighted_averaging Use unweighted averaging (default) or weighted by intensity
 
264
    */
 
265
    void computeDechargeConsensus(const FeatureMap<> & fm, bool intensity_weighted_averaging = false);
 
266
 
 
267
    /**
 
268
      @brief Add a ratio.
 
269
 
 
270
      Connects a ratio to the ConsensusFeature.
 
271
 
 
272
      @note still experimental. consensusfeaturehandler will ignore it.
 
273
    */
 
274
    void addRatio(const Ratio & r);
 
275
 
 
276
    /**
 
277
      @brief Add a ratio vector.
 
278
 
 
279
      Connects the ratios to the ConsensusFeature.
 
280
 
 
281
      @note still experimental. consensusfeaturehandler will ignore it.
 
282
    */
 
283
    void setRatios(std::vector<Ratio> & rs);
 
284
 
 
285
    /**
 
286
      @brief Get the ratio vector.
 
287
    */
 
288
    std::vector<Ratio> getRatios() const;
 
289
 
 
290
    /**
 
291
      @brief Get the ratio vector.
 
292
    */
 
293
    std::vector<Ratio> & getRatios();
 
294
 
 
295
    ///@name Accessors for set of FeatureHandles
 
296
    //@{
 
297
    Size size() const;
 
298
 
 
299
    const_iterator begin() const;
 
300
 
 
301
    iterator begin();
 
302
    
 
303
    const_iterator end() const;
 
304
 
 
305
    iterator end();
 
306
 
 
307
    const_reverse_iterator rbegin() const;
 
308
 
 
309
    reverse_iterator rbegin();
 
310
 
 
311
    const_reverse_iterator rend() const;
 
312
 
 
313
    reverse_iterator rend();
 
314
 
 
315
    void clear();
 
316
 
 
317
    bool empty() const;
 
318
    //@}
 
319
 
 
320
  private:
 
321
    HandleSetType handles_;
 
322
    std::vector<Ratio> ratios_;
 
323
 
 
324
  };
 
325
 
 
326
  ///Print the contents of a ConsensusFeature to a stream
 
327
  OPENMS_DLLAPI std::ostream & operator<<(std::ostream & os, const ConsensusFeature & cons);
210
328
 
211
329
} // namespace OpenMS
212
330