Class MolecularFormulaGenerator

java.lang.Object
org.openscience.cdk.formula.MolecularFormulaGenerator

public class MolecularFormulaGenerator extends Object
This class generates molecular formulas within given mass range and elemental composition. Usage:
 IsotopeFactory ifac = Isotopes.getInstance();
 IIsotope c = ifac.getMajorIsotope("C");
 IIsotope h = ifac.getMajorIsotope("H");
 IIsotope n = ifac.getMajorIsotope("N");
 IIsotope o = ifac.getMajorIsotope("O");
 IIsotope p = ifac.getMajorIsotope("P");
 IIsotope s = ifac.getMajorIsotope("S");

 MolecularFormulaRange mfRange = new MolecularFormulaRange();
 mfRange.addIsotope(c, 0, 50);
 mfRange.addIsotope(h, 0, 100);
 mfRange.addIsotope(o, 0, 50);
 mfRange.addIsotope(n, 0, 50);
 mfRange.addIsotope(p, 0, 10);
 mfRange.addIsotope(s, 0, 10);

 MolecularFormulaGenerator mfg = new MolecularFormulaGenerator(builder, minMass,
         maxMass, mfRange);
 double minMass = 133.003;
 double maxMass = 133.005;
 IMolecularFormulaSet mfSet = mfg.getAllFormulas();
 
This class offers two implementations: The Round Robin algorithm [Böcker, Sebastian et. al.. Bioinformatics. 2008. 24] on mass ranges [Unknown BibTeXML type: Duehrkop2013] is used on most inputs. For special cases (e.g. single elements, extremely large mass ranges) a full enumeration algorithm [Pluskal, Tomas et. al.. Analytical Chemistry. 2012. 84] is used. The Round Robin algorithm was originally developed for the SIRIUS 3 software. The full enumeration algorithm was originally developed for a MZmine 2 framework module, published in Pluskal et al. [Pluskal, Tomas et. al.. Analytical Chemistry. 2012. 84].
Author:
Tomas Pluskal, Kai Dührkop, Marcus Ludwig
Source code:
main
Belongs to CDK module:
formula
Created on:
2014-12-28
  • Field Details

    • formulaGenerator

      protected final org.openscience.cdk.formula.IFormulaGenerator formulaGenerator
      The chosen implementation
  • Constructor Details

    • MolecularFormulaGenerator

      public MolecularFormulaGenerator(IChemObjectBuilder builder, double minMass, double maxMass, MolecularFormulaRange mfRange)
      Initiate the MolecularFormulaGenerator.
      Parameters:
      minMass - Lower boundary of the target mass range
      maxMass - Upper boundary of the target mass range
      mfRange - A range of elemental compositions defining the search space
      Throws:
      IllegalArgumentException - In case some of the isotopes in mfRange has undefined exact mass or in case illegal parameters are provided (e.g., negative mass values or empty MolecularFormulaRange)
      See Also:
  • Method Details

    • getNextFormula

      public IMolecularFormula getNextFormula()
      Returns next generated formula or null in case no new formula was found (search is finished). There is no guaranteed order in which the formulas are generated.
    • getAllFormulas

      public IMolecularFormulaSet getAllFormulas()
      Generates a IMolecularFormulaSet by repeatedly calling getNextFormula() until all possible formulas are generated. There is no guaranteed order to the formulas in the resulting IMolecularFormulaSet. Note: if some formulas were already generated by calling getNextFormula() on this MolecularFormulaGenerator instance, those formulas will not be included in the returned IMolecularFormulaSet.
      See Also:
    • getFinishedPercentage

      public double getFinishedPercentage()
      Returns a value between 0.0 and 1.0 indicating what portion of the search space has been examined so far by this MolecularFormulaGenerator. Before the first call to getNextFormula(), this method returns 0. After all possible formulas are generated, this method returns 1.0 (the exact returned value might be slightly off due to rounding errors). This method can be called from any thread.
    • cancel

      public void cancel()
      Cancel the current search. This method can be called from any thread. If another thread is executing the getNextFormula() method, that method call will return immediately with null return value. If another thread is executing the getAllFormulas() method, that method call will return immediately, returning all formulas generated until this moment. The search cannot be restarted once canceled - any subsequent calls to getNextFormula() will return null.
    • checkInputParameters

      protected void checkInputParameters(IChemObjectBuilder builder, double minMass, double maxMass, MolecularFormulaRange mfRange)
      Checks if input parameters are valid and throws an IllegalArgumentException otherwise.