Package org.openscience.cdk.formula

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 Summary

Fields

Modifier and Type	Field	Description
protected org.openscience.cdk.formula.IFormulaGenerator	formulaGenerator	The chosen implementation

Constructor Summary

Constructors

Constructor	Description
MolecularFormulaGenerator(IChemObjectBuilder builder, double minMass, double maxMass, MolecularFormulaRange mfRange)	Initiate the MolecularFormulaGenerator.

Method Summary

Modifier and Type	Method	Description
void	cancel()	Cancel the current search.
protected void	checkInputParameters(IChemObjectBuilder builder, double minMass, double maxMass, MolecularFormulaRange mfRange)	Checks if input parameters are valid and throws an IllegalArgumentException otherwise.
IMolecularFormulaSet	getAllFormulas()	Generates a IMolecularFormulaSet by repeatedly calling getNextFormula() until all possible formulas are generated.
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.
IMolecularFormula	getNextFormula()	Returns next generated formula or null in case no new formula was found (search is finished).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

formulaGenerator

protected final org.openscience.cdk.formula.IFormulaGenerator formulaGenerator

The chosen implementation

Constructor Detail

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:

MolecularFormulaRange

Method Detail

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:

getNextFormula()

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.