ProteoWizard
DemuxHelpers.hpp
Go to the documentation of this file.
1 //
2 // $Id: DemuxHelpers.hpp 10348 2017-01-11 18:26:26Z chambm $
3 //
4 //
5 // Original author: Austin Keller <atkeller .@. uw.edu>
6 //
7 // Licensed under the Apache License, Version 2.0 (the "License");
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
10 //
11 // http://www.apache.org/licenses/LICENSE-2.0
12 //
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an "AS IS" BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
18 //
19 
20 // Note: The following Doxygen comment is required in order to have global functions, variables, etc. parsed.
21 /** \file DemuxHelpers.hpp
22 * Helper functions for demultiplexing
23 * Helper functions include nice methods of accessing CV parameters and other generally useful functions.
24 */
25 
26 #ifndef _DEMUXHELPERS_HPP
27 #define _DEMUXHELPERS_HPP
28 
29 #include "DemuxTypes.hpp"
31 #include <boost/tokenizer.hpp>
33 
34 namespace pwiz
35 {
36 namespace analysis
37 {
38  /**
39  * Converts an enum to it's corresponding string in a prebuilt map. Exception is thrown if map does not contain enum.
40  * @param[in] e The enum
41  * @param[out] m The map pairing each enum to a string
42  * @return Returns the string from the map
43  */
44  template <typename T>
45  const std::string& enumToString(T e, std::map<T, std::string> m)
46  {
47  return m.at(e);
48  }
49 
50  /**
51  * Converts a string to it's corresponding enum in a prebuilt map. Exception is thrown if map does not contain string.
52  * @param[in] s The string
53  * @param[out] m The map pairing each enum to a string
54  * @return Returns the enum from the map
55  */
56  template<typename T>
57  T stringToEnum(const std::string& s, std::map<T, std::string> m)
58  {
59  for (auto it = m.begin(); it != m.end(); ++it) {
60  if (it->second.compare(s) == 0)
61  return it->first;
62  }
63  throw EnumConstantNotPresentException("Given string doesn't correspond to an enum");
64  }
65 
66  /// Tool for pulling each scan id attribute and its value from a scan id.
67  /// Scan ids contain sets of attribute-value pairs. Each pair is separated from others by a space. Each attribute is separated from its
68  /// value by an "=". E.g. "attribute1=value1 attribute2=value2 attribute3=value3"
69  typedef boost::tokenizer<boost::char_separator<char> > ScanIdTokenizer;
70 
71  /**
72  * Tries to read the given token from a spectrum identity id. The spectrum identity id is a set of pairs of attribute names (tokens) and their
73  * corresponding values.
74  * @param[in] spectrumIdentity The SpectrumIdentity to search
75  * @param[in] tokenName attribute
76  * @param[out] value value
77  * @return false if the given token does not exist in the SpectrumIdentity id
78  */
79  bool TryGetScanIDToken(const msdata::SpectrumIdentity& spectrumIdentity, const std::string& tokenName, std::string& value);
80 
81  /**
82  * Tries to read the index of the demultiplexed spectrum relative to the multiplexed spectrum it was derived from.
83  * For example, if a multiplexed spectrum is split into 3 demultiplexed spectra, the resulting spectra will have indices 0, 1, and 2.
84  * @param[in] spectrumIdentity The SpectrumIdentity to search
85  * @param[out] index The demux index of the spectrum
86  * @return false if the given SpectrumIdentity does not contain information about the scan index. E.g., if the given spectrum is not a
87  * demultiplexed spectrum.
88  */
89  bool TryGetDemuxIndex(const msdata::SpectrumIdentity& spectrumIdentity, size_t& index);
90 
91  /**
92  * Tries to read the original index of the spectrum before demultiplexing using the SpectrumIdentity of a (demultiplexed) spectrum.
93  * Demultiplexing effectively splits each spectrum into multiple demultiplexed spectra. This method allows for retrieval of the original
94  * spectrum before this split.
95  * @param[in] spectrumIdentity The SpectrumIdentity to search
96  * @param[out] index The original index of the spectrum
97  * @return false if the given SpectrumIdentity does not contain information about the scan index
98  */
99  bool TryGetOriginalIndex(const msdata::SpectrumIdentity& spectrumIdentity, size_t& index);
100 
101  /**
102  * Tries to read MS level from spectrum
103  * @param[in] spectrum The mass spectrum to read
104  * @param[out] msLevel The number of sequential MS analyses (e.g. MS = 1, MS/MS = 2)
105  * @return true if successful, false otherwise
106  */
107  bool TryGetMSLevel(const msdata::Spectrum& spectrum, int& msLevel);
108 
109  /**
110  * Tries to get the number of precursors contributing to a multiplexed spectrum.
111  * This is only well defined for spectra of MS2 or greater. (Note: only parsing of MS2 is implemented currently)
112  * @param[in] spectrum The mass spectrum to read
113  * @param[out] numPrecursors The number of precursor windows contributing to the given mass spectrum
114  * @return true if successful, false otherwise
115  */
116  bool TryGetNumPrecursors(const msdata::Spectrum& spectrum, int& numPrecursors);
117 
118  /**
119  * Tries to get the start time of the scan
120  * @param[in] spectrum The mass spectrum to read
121  * @param[out] startTime The start time of the scan (may also be interpreted as retention time)
122  * @return true if successful, false otherwise
123  */
124  bool TryGetStartTime(const msdata::Spectrum& spectrum, double& startTime);
125 
126  /**
127  * Tries to find a given number of ms2 spectra near the given spectrum index.
128  * This handles edge cases near the beginning and end of the SpectrumList and tries to distribute the spectra surrounding the centerIndex
129  * as evenly as possible. Throws std::out_of_range exception if center index is not in range of SpectrumList.
130  * @param[out] spectraIndices The indices to the nearby spectra.
131  * @param[in] slPtr The spectrum list to search
132  * @param[in] centerIndex Index of spectrum in the given SpectrumList around which to search
133  * @param[in] numSpectraToFind Number of spectra to find
134  * @param[in] stride Number of ms2 spectra to step through to find a nearby spectrum. E.g. a stride of 2 would skip every other ms2 spectrum. This will still return
135  the chosen total number of spectra. This is useful when ms2 spectra are collected cyclically and only a single index within that cycle is desired.
136  * @return false if not enough spectra can be found
137  */
138  bool FindNearbySpectra(std::vector<size_t>& spectraIndices, pwiz::msdata::SpectrumList_const_ptr slPtr, size_t centerIndex,
139  size_t numSpectraToFind, size_t stride = 1);
140 } // namespace analysis
141 } // namespace pwiz
142 #endif // _DEMUXHELPERS_HPP
bool TryGetOriginalIndex(const msdata::SpectrumIdentity &spectrumIdentity, size_t &index)
Tries to read the original index of the spectrum before demultiplexing using the SpectrumIdentity of ...
T stringToEnum(const std::string &s, std::map< T, std::string > m)
Converts a string to it&#39;s corresponding enum in a prebuilt map.
const std::string & enumToString(T e, std::map< T, std::string > m)
Converts an enum to it&#39;s corresponding string in a prebuilt map.
boost::tokenizer< boost::char_separator< char > > ScanIdTokenizer
Tool for pulling each scan id attribute and its value from a scan id.
bool TryGetStartTime(const msdata::Spectrum &spectrum, double &startTime)
Tries to get the start time of the scan.
bool TryGetScanIDToken(const msdata::SpectrumIdentity &spectrumIdentity, const std::string &tokenName, std::string &value)
Tries to read the given token from a spectrum identity id.
bool FindNearbySpectra(std::vector< size_t > &spectraIndices, pwiz::msdata::SpectrumList_const_ptr slPtr, size_t centerIndex, size_t numSpectraToFind, size_t stride=1)
Tries to find a given number of ms2 spectra near the given spectrum index.
bool TryGetDemuxIndex(const msdata::SpectrumIdentity &spectrumIdentity, size_t &index)
Tries to read the index of the demultiplexed spectrum relative to the multiplexed spectrum it was der...
bool TryGetMSLevel(const msdata::Spectrum &spectrum, int &msLevel)
Tries to read MS level from spectrum.
An exception class inspired by Java&#39;s EnumConstantNotPresentException.
Identifying information for a spectrum.
Definition: MSData.hpp:469
PWIZ_API_DECL std::string value(const std::string &id, const std::string &name)
convenience function to extract a named value from an id string
The structure that captures the generation of a peak list (including the underlying acquisitions) ...
Definition: MSData.hpp:504
bool TryGetNumPrecursors(const msdata::Spectrum &spectrum, int &numPrecursors)
Tries to get the number of precursors contributing to a multiplexed spectrum.
boost::shared_ptr< const msdata::SpectrumList > SpectrumList_const_ptr
Definition: DemuxTypes.hpp:28