OpenMS  2.8.0
ExperimentalDesign.h
Go to the documentation of this file.
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-2021.
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.
29 //
30 // --------------------------------------------------------------------------
31 // $Maintainer: Timo Sachsenberg $
32 // $Authors: Timo Sachsenberg $
33 // --------------------------------------------------------------------------
34 
35 #pragma once
36 
40 
41 #include <vector>
42 #include <map>
43 #include <set>
44 
45 namespace OpenMS
46 {
47  class ConsensusMap;
48  class FeatureMap;
49 
242  class OPENMS_DLLAPI ExperimentalDesign
243  {
244 
245  public:
252  class OPENMS_DLLAPI MSFileSectionEntry
253  {
254  public:
255  MSFileSectionEntry() = default;
256  unsigned fraction_group = 1;
257  unsigned fraction = 1;
258  std::string path = "UNKNOWN_FILE";
259  unsigned label = 1;
260  unsigned sample = 1;
261  };
262 
263  class OPENMS_DLLAPI SampleSection
264  {
265  public:
266 
267  SampleSection() = default;
268 
270  const std::vector< std::vector < String > >& content,
271  const std::map< unsigned, Size >& sample_to_rowindex,
272  const std::map< String, Size >& columnname_to_columnindex
273  );
274 
275  // Get set of all samples that are present in the sample section
276  std::set< unsigned > getSamples() const;
277 
278  // Add a sample as the last row
279  void addSample(unsigned sample, const std::vector<String>& content = {});
280 
281  // TODO should it include the Sample ID column or not??
282  // Get set of all factors (column names) that were defined for the sample section
283  std::set< String > getFactors() const;
284 
285  // Checks whether sample section has row for a sample number
286  bool hasSample(unsigned sample) const;
287 
288  // Checks whether Sample Section has a specific factor (i.e. column name)
289  bool hasFactor(const String &factor) const;
290 
291  // Returns value of factor for given sample and factor name
292  String getFactorValue(unsigned sample, const String &factor) const;
293 
294  // Returns column index of factor
295  Size getFactorColIdx( const String &factor) const;
296 
297  private:
298 
299  // The entries of the Sample Section, filled while parsing
300  // the Experimental Design File
301  std::vector< std::vector < String > > content_;
302 
303  // Maps the Sample Entry to the row where the sample
304  // appears in the Sample section
305  std::map< unsigned, Size > sample_to_rowindex_;
306 
307  // Maps the column name of the SampleSection to the
308  // Index of the column
309  std::map< String, Size > columnname_to_columnindex_;
310  };
311 
312  using MSFileSection = std::vector<MSFileSectionEntry>;
313 
314  // Experimental Design c'tors
315  ExperimentalDesign() = default;
316 
317  ExperimentalDesign(const MSFileSection& msfile_section, const SampleSection& sample_section);
318 
320 
321  void setMSFileSection(const MSFileSection& msfile_section);
322 
323  // Returns the Sample Section of the experimental design file
325 
326  void setSampleSection(const SampleSection& sample_section);
327 
330  std::map<std::vector<String>, std::set<unsigned>> getUniqueSampleRowToSampleMapping() const;
331 
334  std::map<unsigned, unsigned> getSampleToPrefractionationMapping() const;
335 
337  //TODO this probably needs a basename parameter to be fully compatible with the other mappings!! Implicit full path.
338  std::map<unsigned int, std::vector<String> > getFractionToMSFilesMapping() const;
339 
342  //TODO this probably needs a basename parameter to be fully compatible with the other mappings!! Implicit full path.
343  std::vector<std::vector<std::pair<String, unsigned>>> getConditionToPathLabelVector() const;
344 
346  std::map<std::vector<String>, std::set<unsigned>> getConditionToSampleMapping() const;
347 
348  /*
349  * The (Path, Label) tuples in the experimental design have to be unique, so we can map them
350  * uniquely to the sample number, fraction number, and fraction_group number
351  */
352 
355  std::map< std::pair< String, unsigned >, unsigned> getPathLabelToPrefractionationMapping(bool use_basename_only) const;
356 
359  std::map< std::pair< String, unsigned >, unsigned> getPathLabelToConditionMapping(bool use_basename_only) const;
360 
363  std::map<unsigned, unsigned> getSampleToConditionMapping() const;
364 
366  std::map< std::pair< String, unsigned >, unsigned> getPathLabelToSampleMapping(bool use_basename_only) const;
367 
369  std::map< std::pair< String, unsigned >, unsigned> getPathLabelToFractionMapping(bool use_basename_only) const;
370 
372  std::map< std::pair< String, unsigned >, unsigned> getPathLabelToFractionGroupMapping(bool use_basename_only) const;
373 
374  // @return the number of samples measured (= highest sample index)
375  unsigned getNumberOfSamples() const;
376 
377  // @return the number of fractions (= highest fraction index)
378  unsigned getNumberOfFractions() const;
379 
380  // @return the number of labels per file
381  unsigned getNumberOfLabels() const;
382 
383  // @return the number of MS files (= fractions * fraction groups)
384  unsigned getNumberOfMSFiles() const;
385 
386  // @return the number of fraction_groups
387  // Allows to group fraction ids and source files
388  unsigned getNumberOfFractionGroups() const;
389 
390  // @return sample index (depends on fraction_group and label)
391  unsigned getSample(unsigned fraction_group, unsigned label = 1);
392 
394  // This is the case if we have at least one fraction group with >= 2 fractions
395  bool isFractionated() const;
396 
400  Size filterByBasenames(const std::set<String>& bns);
401 
404 
407 
410 
412  static ExperimentalDesign fromIdentifications(const std::vector<ProteinIdentification>& proteins);
413  //TODO create another overload here, that takes two enums outerVec and innerVec with entries Replicate, Fraction, Sample
414 
415  private:
416  // MS filename column, optionally trims to basename
417  std::vector< String > getFileNames_(bool basename) const;
418 
419  // returns label column
420  std::vector<unsigned> getLabels_() const;
421 
422  // returns fraction column
423  std::vector<unsigned> getFractions_() const;
424 
426  std::map< std::pair< String, unsigned >, unsigned> pathLabelMapper_(
427  bool,
428  unsigned (*f)(const ExperimentalDesign::MSFileSectionEntry&)) const;
429 
430  // sort to obtain the default order
431  void sort_();
432 
433  template<typename T>
434  static void errorIfAlreadyExists(std::set<T> &container, T &item, const String &message);
435 
436  // basic consistency checks
437  void isValid_();
438 
441  };
442 }
443 
A container for consensus elements.
Definition: ConsensusMap.h:90
Definition: ExperimentalDesign.h:253
Definition: ExperimentalDesign.h:264
SampleSection(const std::vector< std::vector< String > > &content, const std::map< unsigned, Size > &sample_to_rowindex, const std::map< String, Size > &columnname_to_columnindex)
std::vector< std::vector< String > > content_
Definition: ExperimentalDesign.h:301
std::map< String, Size > columnname_to_columnindex_
Definition: ExperimentalDesign.h:309
String getFactorValue(unsigned sample, const String &factor) const
bool hasSample(unsigned sample) const
std::set< String > getFactors() const
Size getFactorColIdx(const String &factor) const
bool hasFactor(const String &factor) const
std::set< unsigned > getSamples() const
std::map< unsigned, Size > sample_to_rowindex_
Definition: ExperimentalDesign.h:305
void addSample(unsigned sample, const std::vector< String > &content={})
Representation of an experimental design in OpenMS. Instances can be loaded with the ExperimentalDesi...
Definition: ExperimentalDesign.h:243
unsigned getNumberOfLabels() const
static void errorIfAlreadyExists(std::set< T > &container, T &item, const String &message)
unsigned getNumberOfFractions() const
static ExperimentalDesign fromConsensusMap(const ConsensusMap &c)
Extract experimental design from consensus map.
std::map< std::vector< String >, std::set< unsigned > > getUniqueSampleRowToSampleMapping() const
unsigned getSample(unsigned fraction_group, unsigned label=1)
unsigned getNumberOfSamples() const
void setSampleSection(const SampleSection &sample_section)
std::vector< unsigned > getLabels_() const
bool sameNrOfMSFilesPerFraction() const
Size filterByBasenames(const std::set< String > &bns)
unsigned getNumberOfFractionGroups() const
std::map< unsigned int, std::vector< String > > getFractionToMSFilesMapping() const
return fraction index to file paths (ordered by fraction_group)
std::map< std::pair< String, unsigned >, unsigned > getPathLabelToFractionMapping(bool use_basename_only) const
return <file_path, label> to fraction mapping
std::map< std::pair< String, unsigned >, unsigned > getPathLabelToPrefractionationMapping(bool use_basename_only) const
std::map< std::vector< String >, std::set< unsigned > > getConditionToSampleMapping() const
return a condition (unique combination of sample section values except replicate) to Sample index map...
void setMSFileSection(const MSFileSection &msfile_section)
std::vector< MSFileSectionEntry > MSFileSection
Definition: ExperimentalDesign.h:312
std::map< std::pair< String, unsigned >, unsigned > getPathLabelToConditionMapping(bool use_basename_only) const
MSFileSection msfile_section_
Definition: ExperimentalDesign.h:439
static ExperimentalDesign fromIdentifications(const std::vector< ProteinIdentification > &proteins)
Extract experimental design from identifications.
std::map< std::pair< String, unsigned >, unsigned > pathLabelMapper_(bool, unsigned(*f)(const ExperimentalDesign::MSFileSectionEntry &)) const
Generic Mapper (Path, Label) -> f(row)
ExperimentalDesign(const MSFileSection &msfile_section, const SampleSection &sample_section)
std::vector< unsigned > getFractions_() const
const MSFileSection & getMSFileSection() const
std::vector< String > getFileNames_(bool basename) const
const ExperimentalDesign::SampleSection & getSampleSection() const
std::map< unsigned, unsigned > getSampleToConditionMapping() const
static ExperimentalDesign fromFeatureMap(const FeatureMap &f)
Extract experimental design from feature map.
std::vector< std::vector< std::pair< String, unsigned > > > getConditionToPathLabelVector() const
std::map< std::pair< String, unsigned >, unsigned > getPathLabelToSampleMapping(bool use_basename_only) const
return <file_path, label> to sample mapping
SampleSection sample_section_
Definition: ExperimentalDesign.h:440
unsigned getNumberOfMSFiles() const
std::map< std::pair< String, unsigned >, unsigned > getPathLabelToFractionGroupMapping(bool use_basename_only) const
return <file_path, label> to fraction_group mapping
std::map< unsigned, unsigned > getSampleToPrefractionationMapping() const
A container for features.
Definition: FeatureMap.h:106
A more convenient string class.
Definition: String.h:60
size_t Size
Size type e.g. used as variable which can hold result of size()
Definition: Types.h:127
const double c
Definition: Constants.h:209
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:47