[DOC] modernize first set of Tutorials; fix docs of affected classes …

…along the way. also update raw input data (avoid parser warnings)

doc/code_examples/Tutorial_AASequence.cpp

@@ -18,21 +18,17 @@ int main()
   const String s = "DEFIANGER";
   AASequence peptide1 = AASequence::fromString(s);
 
-  // generate AASequence object from string literal
+  // ... or generate AASequence object from string literal
   AASequence peptide2 = AASequence::fromString("PEPTIDER");
 
-  // extract prefix and suffix
-  AASequence prefix(peptide1.getPrefix(2));
-  AASequence suffix(peptide1.getSuffix(3));
-  cout << peptide1.toString() << " "
-       << prefix << " "
-       << suffix << endl;
-
+  // extract prefix and suffix of the first/last AA residues
+  AASequence prefix(peptide1.getPrefix(2)); // "PE"
+  AASequence suffix(peptide1.getSuffix(3)); // "DER"
+  cout << peptide1.toString() << " " << prefix << " " << suffix << endl;
+
   // create chemically modified peptide
   AASequence peptide_meth_ox = AASequence::fromString("PEPTIDESEKUEM(Oxidation)CER");
-  cout << peptide_meth_ox.toString() << " "
-       << peptide_meth_ox.toUnmodifiedString()
-       << endl;
+  cout << peptide_meth_ox.toString() << " --> unmodified: " << peptide_meth_ox.toUnmodifiedString() << endl;
 
   // mass of the full, uncharged peptide
   double peptide_mass_mono = peptide_meth_ox.getMonoWeight();
@@ -42,14 +38,19 @@ int main()
   cout << "Average mass of the uncharged, full peptide: " << peptide_mass_avg << endl;
 
   // mass of the 2+ charged b-ion with the given sequence
-  double ion_mass_2plus = peptide_meth_ox.getMonoWeight(Residue::BIon, 2);
-  cout << "Mass of the doubly positively charged b-ion: " << ion_mass_2plus << endl;
+  double ion_mass_b3_2plus = peptide_meth_ox.getPrefix(3).getMonoWeight(Residue::BIon, 2);
+  cout << "Mass of the doubly positively charged b3-ion: " << ion_mass_b3_2plus << endl;
 
   // mass-to-charge ratio (m/z) of the 2+ charged b-ion and full peptide with the given sequence
-  cout << "Mass-to-charge of the doubly positively charged b-ion: " << peptide_meth_ox.getMZ(2, Residue::BIon) << endl;
+  cout << "Mass-to-charge of the doubly positively charged b3-ion: " << peptide_meth_ox.getPrefix(3).getMZ(2, Residue::BIon) << endl;
   cout << "Mass-to-charge of the doubly positively charged peptide: " << peptide_meth_ox.getMZ(2) << endl;
 
-  // ... many more
+  // count AA's to get a frequency table
+  std::map<String, Size> aa_freq;
+  peptide_meth_ox.getAAFrequencies(aa_freq);
+  cout << "Number of Proline (P) residues in '" << peptide_meth_ox.toString() << "' is " << aa_freq['P'] << endl;
+
+
   return 0;
 }
 

doc/code_examples/Tutorial_Clustering.cpp

@@ -5,57 +5,71 @@
 #include <OpenMS/COMPARISON/CLUSTERING/ClusterAnalyzer.h>
 #include <OpenMS/COMPARISON/CLUSTERING/ClusterHierarchical.h>
 #include <OpenMS/COMPARISON/CLUSTERING/CompleteLinkage.h>
+#include <OpenMS/COMPARISON/CLUSTERING/SingleLinkage.h>
 #include <OpenMS/CONCEPT/Exception.h>
-#include <vector>
 #include <algorithm>
 #include <iostream>
+#include <random>
+#include <vector>
 
 using namespace OpenMS;
 using namespace std;
 
 
+
+/// A functor, which provides a similarity value for two entities (here: doubles), in range [0, 1)
 class LowLevelComparator
 {
 public:
   double operator()(const double first, const double second) const
   {
-    double x, y;
-    x = min(second, first);
-    y = max(first, second);
-    if ((y - x) > 1)
-    {
-      throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION);
-    }
-    return 1 - (y - x);
+    // we just use a linear distance between them, i.e. the closer the values, the more similar they are
+    auto distance = std::fabs(first - second);
+    if (distance > 1) { throw Exception::InvalidRange(__FILE__, __LINE__, OPENMS_PRETTY_FUNCTION); }
+    return 1 - distance;
   }
-
 }; // end of LowLevelComparator
 
 Int main()
 {
   // data
-  vector<double> data; // must be filled
-
-  srand(333);
-  Size nr = 12;
-  data.resize(nr);
-  for (Size i = 0; i < nr; ++i)
-  {
-    data[i] = (double)rand() / RAND_MAX;
-  }
+  vector<double> data;
+#if 1  // manual data
+  data = {0.01, 0.02, 0.7, 0.3, 0.31};
+#else  // random data
+  const auto N = 5;
+  std::mt19937 rng;                               // default constructed, seeded with fixed seed
+  std::uniform_real_distribution<> dis(0.0, 1.0); // uniform values between [0, 1)
+  std::generate_n(back_inserter(data), N, [&]() { return dis(rng); });
+#endif
 
+  // print raw data to console
+  std::cout << "raw data: ";
+  for_each(data.begin(), data.end(), [](auto elem) { std::cout << elem << ' '; });
+  std::cout << '\n';
+  // determines the distance between two data points
   LowLevelComparator llc;
-  CompleteLinkage sl;
+
+  SingleLinkage sl; 
+  // or try: 
+  //CompleteLinkage sl;
+
   vector<BinaryTreeNode> tree;
   DistanceMatrix<float> dist; // will be filled
   ClusterHierarchical ch;
-  ch.setThreshold(0.15);
+  ch.setThreshold(1); // maximal distance between clusters; default threshold = 1, i.e. full clustering
+  // note: not all methods support a threshold, e.g. SingleLinkage requires t = 1.
 
-  // clustering
+  // do clustering.
+  // Note: There are other overloads of this function for clustering spectra
   ch.cluster<double, LowLevelComparator>(data, llc, sl, tree, dist);
 
+  // depending on the cluster method, the distance matrix may have shrunken, e.g. for complete linkage to the point where clustering was stopped
+  std::cout << "distance matrix:\n" << dist << "\n\n"; 
+
   ClusterAnalyzer ca;
+  std::cout << "binary tree in Newick format (numbers are indices into the data)";
   std::cout << ca.newickTree(tree) << std::endl;
 
   return 0;
-} //end of main
+} // end of main

doc/code_examples/Tutorial_DPosition.cpp

@@ -9,14 +9,27 @@ using namespace OpenMS;
 
 Int main()
 {
-  DPosition<2> pos;
-  pos[0] = 8.15;
-  pos[1] = 47.11;
+  DPosition<2> pos {-8.15, 47.11};
+  static_assert(pos.size() == 2);
 
-  for (Size i = 0; i < DPosition<2>::DIMENSION; ++i)
+  std::cout << "largest possible value: " << DPosition<2>::maxPositive() << '\n';
+  // make values in all dimensions positive and print
+  std::cout << "abs: " << pos.abs() << '\n';
+
+  // manipulate individual dimensions
+  pos[0] = -3.15;
+  pos[1] = 7.11;
+
+  for (Size i = 0; i < pos.DIMENSION; ++i)
   {
     std::cout << "Dimension " << i << ": " << pos[i] << std::endl;
   }
+  // same thing
+  int i = 0;
+  for (const auto e : pos)
+  {
+    std::cout << "Dimension " << i++ << ": " << e << std::endl;
+  }
 
   return 0;
 } //end of main

doc/code_examples/Tutorial_DRange.cpp

@@ -9,15 +9,30 @@ using namespace OpenMS;
 
 Int main()
 {
+  // A D-dimensional range, without units;
+  // Note: if you want something more modern with dimensions for RT, m/z, intensity and mobility, then use RangeManager.
+  // 
+  // You can use any dimension you like; for D=2 and D=3 there are some convenience overloads though, especially for C'tors
+  // a 2-dimensional, i.e. [x_min..x_max, y_min..y_max],  range
   DRange<2> range;
-  range.setMin(DPosition<2>(2.0, 3.0));
-  range.setMax(DPosition<2>(1.0, 5.0));
+  range.setMin(DPosition<2>(2.0, 3.0)); // for (x_min, y_min)
+  range.setMax(DPosition<2>(4.0, 5.0)); // for (x_max, y_max)
+  std::cout << "values:\n" << range; // prints [2..4, 3..5]
 
-  for (UInt i = 0; i < DRange<2>::DIMENSION; ++i)
+  // Note: the class maintains the invariant min<=max for each dimension
+  //       Thus, setting a 'min' which is larger than the current 'max', also adjusts 'max' to the same value
+  range.setMin(DPosition<2>(10.0, 2.0)); // for (x_max, y_max)
+  std::cout << "\nadjusted max:\n" << range; // prints [10..10, 2..5]
+
+  // you can also set each dimension's min/max: 0 = X, 1 = Y
+  range.setDimMinMax(0, {0.6, 6.6});
+  std::cout << "\nnew X range:\n" << range;
+
+  // print values using a custom format
+  for (UInt i = 0; i < range.DIMENSION; ++i)
   {
-    std::cout << "min " << i << ": " << range.minPosition()[i] << std::endl;
-    std::cout << "max " << i << ": " << range.maxPosition()[i] << std::endl;
+    std::cout << "DIM " << i << ": " << range.minPosition()[i] << " ... " << range.maxPosition()[i] << '\n';
   }
 
-  return 0;
+
 } //end of main

doc/code_examples/Tutorial_Element.cpp

@@ -4,28 +4,60 @@
 
 //! [doxygen_snippet_Element]
 
-#include <OpenMS/CHEMISTRY/ElementDB.h>
 #include <OpenMS/CHEMISTRY/Element.h>
+#include <OpenMS/CHEMISTRY/ElementDB.h>
+#include <OpenMS/DATASTRUCTURES/StringListUtils.h>
 #include <iostream>
+#include <iomanip>
 
 using namespace OpenMS;
 using namespace std;
 
 Int main()
 {
-  const ElementDB * db = ElementDB::getInstance();
+  const ElementDB& db = *ElementDB::getInstance();
 
   // extract carbon element from ElementDB
   // .getResidue("C") would work as well
-  Element carbon = *db->getElement("Carbon"); 
+  const Element& carbon = *db.getElement("Carbon");
 
   // output name, symbol, monoisotopic weight and average weight
-  cout << carbon.getName() << " "
-       << carbon.getSymbol() << " "
-       << carbon.getMonoWeight() << " "
-       << carbon.getAverageWeight() << endl;
-
-  return 0;
-} //end of main
+  cout << carbon.getName() << " " << carbon.getSymbol() << " " << carbon.getMonoWeight() << " " << carbon.getAverageWeight() << endl;
+
+
+  if (db.hasElement("foo")) { std::cout << "worth a try..."; }
+
+  // get all elements currently known; you can also get them by atomic number or symbols:
+  const auto all_elements_name = db.getNames();
+  const auto all_elements_AN = db.getAtomicNumbers();
+  const auto all_elements_symbols = db.getSymbols();
+  std::cout << "We currently know of: " << all_elements_name.size() << " elements (incl. isotopes)\n"
+            << "                with: " << all_elements_AN.size() << " different atomic numbers (linking to the monoisotopic isotope)\n"
+            << "                 and: " << all_elements_symbols.size() << " different symbols\n\n";
+
+  std::cout << "\nLet's find all hydrogen isotopes:\n";
+  for (const auto e : all_elements_name)
+  {
+    // all hydrogens have AN == 1
+    if (e.second->getAtomicNumber() == 1)
+    {
+      std::cout << "  --> " << std::setw(30) << e.first 
+                << "      Symbol: " << std::setw(5) << e.second->getSymbol() 
+                << "          AN: " << std::setw(3) << e.second->getAtomicNumber()
+                << " mono-weight: " << std::setw(14)<< e.second->getMonoWeight() << "\n";
+    }
+  }
+
+  std::cout << "\nLets print all monoisotopic elements:\n";
+  for (const auto e : all_elements_AN)
+  {
+      std::cout << std::setw(30) << e.first 
+                << "      Symbol: " << std::setw(5) << e.second->getSymbol() 
+                << "          AN: " << std::setw(3) << e.second->getAtomicNumber()
+                << " mono-weight: " << std::setw(14)<< e.second->getMonoWeight() << "\n";
+  }
+
+
+} // end of main
 
 //! [doxygen_snippet_Element]

doc/code_examples/Tutorial_EmpiricalFormula.cpp

@@ -16,26 +16,26 @@ Int main()
 {
   EmpiricalFormula methanol("CH3OH"), water("H2O");
 
-  // sum up empirical formula
+  // sum up empirical formulae
   EmpiricalFormula sum = methanol + water;
 
   // get element from ElementDB
   const Element * carbon = ElementDB::getInstance()->getElement("Carbon");
 
   // output number of carbon atoms and average weight 
-  cout << sum << " "
-       << sum.getNumberOf(carbon) << " "
-       << sum.getAverageWeight() << endl;
+  cout << "Formula: " << sum 
+       << "\n  average weight: " << sum.getAverageWeight() 
+       << "\n  # of Carbons: " << sum.getNumberOf(carbon);
 
   // extract the isotope distribution
   IsotopeDistribution iso_dist = sum.getIsotopeDistribution(CoarseIsotopePatternGenerator(3));
 
+  std::cout << "\n\nCoarse isotope distribution of " << sum << ": \n";
   for (const auto& it : iso_dist)
   {
-    cout << it.getMZ() << " " << it.getIntensity() << endl;
+    cout << "m/z: " << it.getMZ() << " abundance: " << it.getIntensity() << endl;
   }
 
-  return 0;
 } //end of main
 
 //! [doxygen_snippet_EmpiricalFormula]

doc/code_examples/Tutorial_Enzyme.cpp

@@ -28,28 +28,34 @@ int main()
 
   // digest C-terminally amidated peptide 
   vector<AASequence> products;
-  protease.digest(AASequence::fromString("ARCDRE.(Amidated)"), products);
+  auto aa_seq = AASequence::fromString("ARCDRE.(Amidated)");
+  protease.digest(aa_seq, products);
 
   // output digestion products
+  std::cout << "digesting " << aa_seq.toString() << " into:\n";
   for (const AASequence& p : products)
   {
-    cout << p.toString() << " ";
+    cout << "-->  " << p.toString() << "\n";
   }
   cout << endl;
 
   // allow many miss-cleavages
   protease.setMissedCleavages(10);
-  protease.digest(AASequence::fromString("ARCDRE.(Amidated)"), products);
+  protease.digest(aa_seq, products);
 
   // output digestion products
+  std::cout << "digesting " << aa_seq.toString() << " with 10 MCs into:\n";
   for (const AASequence& p : products)
   {
-    cout << p.toString() << " ";
+    cout << "-->  " << p.toString() << "\n";
   }
   cout << endl;
 
-  // ... many more
-  return 0;
+  // verify an infix of a protein is a digestion product:
+  String peptide = "FFFRAAA";
+  cout << "Is '" << peptide.prefix(4) << "' a valid digestion product of '" << peptide << "'? " 
+       << std::boolalpha << protease.isValidProduct(peptide, 0, 4); // yes it is!
+
 }
 
 //! [doxygen_snippet_Enzyme]

doc/code_examples/Tutorial_FeatureFinder.cpp

@@ -21,5 +21,4 @@ Int main()
 
   ff.run("simple", input, output, parameters, seeds);
 
-  return 0;
 } //end of main

doc/code_examples/Tutorial_FeatureMap.cpp

@@ -24,9 +24,9 @@ int main()
   map.push_back(feature); //append feature 2
 
   // Iteration over FeatureMap
-  for (auto it = map.begin(); it != map.end(); ++it)
+  for (auto& f : map)
   {
-    cout << it->getRT() << " - " << it->getMZ() << endl;
+    cout << f.getRT() << " - " << f.getMZ() << endl;
   }
 
   // Calculate and output the ranges
@@ -35,8 +35,6 @@ int main()
   cout << "RT:  " << map.getMinRT() << " - " << map.getMaxRT() << endl;
   cout << "m/z: " << map.getMinMZ() << " - " << map.getMaxMZ() << endl;
 
-  // ... and many more
-  return 0;
 } //end of main
 
 //! [doxygen_snippet_FeatureMap]