| OpenMS 2.5.0

Protected Types | Protected Member Functions | Protected Attributes | Friends | List of all members
EmpiricalFormula Class Reference
Chemistry

Representation of an empirical formula. More...

`#include <OpenMS/CHEMISTRY/EmpiricalFormula.h>`

## Public Types

Typedefs
typedef MapType_::const_iterator | ConstIterator
| Iterators. More...
typedef MapType_::const_iterator | const_iterator
typedef MapType_::iterator | Iterator
typedef MapType_::iterator | iterator

## Public Member Functions

Constructors and Destructors
| EmpiricalFormula ()
| Default constructor. More...
| EmpiricalFormula (const EmpiricalFormula &)=default
| Copy constructor. More...
| EmpiricalFormula (EmpiricalFormula &&)=default
| Move constructor. More...
| EmpiricalFormula (const String &rhs)
| EmpiricalFormula (SignedSize number, const Element *element, SignedSize charge=0)
| Constructor with element pointer and number. More...
virtual | ~EmpiricalFormula ()
| Destructor. More...
Accessors
double | getMonoWeight () const
| returns the mono isotopic weight of the formula (includes proton charges) More...
double | getAverageWeight () const
| returns the average weight of the formula (includes proton charges) More...
double | calculateTheoreticalIsotopesNumber () const
| returns the total number of discrete isotopes More...
bool | estimateFromWeightAndComp (double average_weight, double C, double H, double N, double O, double S, double P)
| Fills this EmpiricalFormula with an approximate elemental composition for a given average weight and approximate elemental stoichiometry. More...
bool | estimateFromWeightAndCompAndS (double average_weight, UInt S, double C, double H, double N, double O, double P)
| Fills this EmpiricalFormula with an approximate elemental composition for a given average weight, exact number of sulfurs, and approximate elemental stoichiometry. More...
IsotopeDistribution | getIsotopeDistribution (const IsotopePatternGenerator &method) const
| returns the isotope distribution of the formula The details of the calculation of the isotope distribution are described in the doc to the CoarseIsotopePatternGenerator class. More...
IsotopeDistribution | getConditionalFragmentIsotopeDist (const EmpiricalFormula &precursor, const std::set< UInt > &precursor_isotopes, const CoarseIsotopePatternGenerator &method) const
| returns the fragment isotope distribution of this given a precursor formula and conditioned on a set of isolated precursor isotopes. More...
SignedSize | getNumberOf (const Element *element) const
| returns the number of atoms for a certain `element` (can be negative) More...
SignedSize | getNumberOfAtoms () const
| returns the atoms total (not absolute: negative counts for certain elements will reduce the overall count). Negative result is possible. More...
Int | getCharge () const
| returns the charge More...
void | setCharge (Int charge)
| sets the charge More...
String | toString () const
| returns the formula as a string (charges are not included) More...
std::map< std::string, int > | toMap () const
| returns the formula as a map (charges are not included) More...
EmpiricalFormula & | operator= (const EmpiricalFormula &)=default
| Assignment operator. More...
EmpiricalFormula & | operator= (EmpiricalFormula &&) &=default
| Move assignment operator. More...
EmpiricalFormula & | operator+= (const EmpiricalFormula &rhs)
| adds the elements of the given formula More...
EmpiricalFormula | operator* (const SignedSize &times) const
| multiplies the elements and charge with a factor More...
EmpiricalFormula | operator+ (const EmpiricalFormula &rhs) const
| adds the elements of the given formula and returns a new formula More...
EmpiricalFormula & | operator-= (const EmpiricalFormula &rhs)
| subtracts the elements of a formula More...
EmpiricalFormula | operator- (const EmpiricalFormula &rhs) const
| subtracts the elements of a formula an returns a new formula More...
Predicates
bool | isEmpty () const
| returns true if the formula does not contain a element More...
bool | isCharged () const
| returns true if charge != 0 More...
bool | hasElement (const Element *element) const
| returns true if the formula contains the element More...
bool | contains (const EmpiricalFormula &ef)
| returns true if all elements from `ef` are LESS abundant (negative allowed) than the corresponding elements of this EmpiricalFormula More...
bool | operator== (const EmpiricalFormula &rhs) const
| returns true if the formulas contain equal elements in equal quantities More...
bool | operator!= (const EmpiricalFormula &rhs) const
| returns true if the formulas differ in elements composition More...
bool | operator< (const EmpiricalFormula &rhs) const
| less operator More...
Iterators
ConstIterator | begin () const
ConstIterator | end () const
Iterator | begin ()
Iterator | end ()

## Protected Types

typedef std::map< const Element *, SignedSize > | MapType_
| Internal typedef for the used map type. More...

## Protected Member Functions

void | removeZeroedElements_ ()
| remove elements with count 0 More...
Int | parseFormula_ (std::map< const Element *, SignedSize > &ef, const String &formula) const

## Protected Attributes

MapType_ | formula_
Int | charge_

## Friends

std::ostream & | operator<< (std::ostream &os, const EmpiricalFormula &formula)
| writes the formula to a stream More...

## Detailed Description

Representation of an empirical formula.

The formula can be used as follows: elements are represented through its symbol or full name. The symbol or name is followed by a number. If not, the frequency is set to one. Examples are CH3OH or CarbonHydrogen3OH. The names must start with an capital letter (symbols always have an upper-case letter at the beginning). Additionally charges can be used with '+' followed by a number, if no number follows the charge of +1 is set. Negative charges can be added using a '-' sign. However, negative charges are only set if the last element in the string also has a number. E.g. H4C-1, does not set a negative charge, only -1 Carbon atoms, correctly it should be stated H4C-1-.

This class also supports the usage of specific isotopes. By default "C" describes not one isotope but a natural distribution or different isotopes. This distribution can be accessed via the member getIsotopeDistribution().

If one wants only use a specific isotope, it can be specified using "(",")" brackets. For example, to specify 14C a heavy isotope of carbon it is expressed as "(14)C". The isotope distribution of that instance contains only one isotope, 14C itself with a frequency of 100%.

Instances EmpiricalFormula support a (limited) set of mathematical operations. Additions and subtractions are supported in different flavors. However, one must be careful, because this can lead to negative frequencies. In most cases this might be misleading, however, the class therefore supports difference formulae. E.g. formula differences of reactions from post-translational modifications.

## Member Typedef Documentation

## ◆ const_iterator

typedef MapType_::const_iterator const_iterator

## ◆ ConstIterator

typedef MapType_::const_iterator ConstIterator

Iterators.

## ◆ Iterator

typedef MapType_::iterator Iterator

## ◆ iterator

typedef MapType_::iterator iterator

## ◆ MapType_

typedef std::map<const Element*, SignedSize> MapType_

protected

Internal typedef for the used map type.

## Constructor & Destructor Documentation

## ◆ EmpiricalFormula() [1/5]

EmpiricalFormula | ( |  | ) |

Default constructor.

## ◆ EmpiricalFormula() [2/5]

EmpiricalFormula | ( | const EmpiricalFormula & |  | ) |

default

Copy constructor.

## ◆ EmpiricalFormula() [3/5]

EmpiricalFormula | ( | EmpiricalFormula && |  | ) |

default

Move constructor.

## ◆ EmpiricalFormula() [4/5]

EmpiricalFormula | ( | const String & | rhs | ) |

explicit

Constructor from an OpenMS String

Exceptions

  throws | ParseError if the formula cannot be parsed

## ◆ EmpiricalFormula() [5/5]

EmpiricalFormula | ( | SignedSize | number,
|  | const Element * | element,
|  | SignedSize | charge = `0`
| ) |  |

Constructor with element pointer and number.

## ◆ ~EmpiricalFormula()

virtual ~EmpiricalFormula | ( |  | ) |

virtual

Destructor.

## Member Function Documentation

## ◆ begin() [1/2]

ConstIterator begin | ( |  | ) | const

inline

## ◆ begin() [2/2]

Iterator begin | ( |  | ) |

inline

## ◆ calculateTheoreticalIsotopesNumber()

double calculateTheoreticalIsotopesNumber | ( |  | ) | const

returns the total number of discrete isotopes

## ◆ contains()

bool contains | ( | const EmpiricalFormula & | ef | ) |

returns true if all elements from `ef` are LESS abundant (negative allowed) than the corresponding elements of this EmpiricalFormula

## ◆ end() [1/2]

ConstIterator end | ( |  | ) | const

inline

## ◆ end() [2/2]

Iterator end | ( |  | ) |

inline

## ◆ estimateFromWeightAndComp()

bool estimateFromWeightAndComp | ( | double | average_weight,
|  | double | C,
|  | double | H,
|  | double | N,
|  | double | O,
|  | double | S,
|  | double | P
| ) |  |

Fills this EmpiricalFormula with an approximate elemental composition for a given average weight and approximate elemental stoichiometry.

Parameters

  average_weight | Average weight to estimate an EmpiricalFormula for
  C | The approximate relative stoichiometry of Carbons to other elements in this molecule
  H | The approximate relative stoichiometry of Hydrogens to other elements in this molecule
  N | The approximate relative stoichiometry of Nitrogens to other elements in this molecule
  O | The approximate relative stoichiometry of Oxygens to other elements in this molecule
  S | The approximate relative stoichiometry of Sulfurs to other elements in this molecule
  P | The approximate relative stoichiometry of Phosphoruses to other elements in this molecule

Returns
  bool flag for whether the approximation succeeded without requesting negative hydrogens. true = no problems, 1 = negative hydrogens requested.

## ◆ estimateFromWeightAndCompAndS()

bool estimateFromWeightAndCompAndS | ( | double | average_weight,
|  | UInt | S,
|  | double | C,
|  | double | H,
|  | double | N,
|  | double | O,
|  | double | P
| ) |  |

Fills this EmpiricalFormula with an approximate elemental composition for a given average weight, exact number of sulfurs, and approximate elemental stoichiometry.

Parameters

  average_weight | Average weight to estimate an EmpiricalFormula for
  S | The exact number of Sulfurs in this molecule
  C | The approximate relative stoichiometry of Carbons to other elements (excluding Sulfur) in this molecule
  H | The approximate relative stoichiometry of Hydrogens to other elements (excluding Sulfur) in this molecule
  N | The approximate relative stoichiometry of Nitrogens to other elements (excluding Sulfur) in this molecule
  O | The approximate relative stoichiometry of Oxygens to other elements (excluding Sulfur) in this molecule
  P | The approximate relative stoichiometry of Phosphoruses to other elements (excluding Sulfur) in this molecule

Returns
  bool flag for whether the approximation succeeded without requesting negative hydrogens. true = no problems, false = negative hydrogens requested.

## ◆ getAverageWeight()

double getAverageWeight | ( |  | ) | const

returns the average weight of the formula (includes proton charges)

Referenced by NucleicAcidSearchEngine::main_().

## ◆ getCharge()

Int getCharge | ( |  | ) | const

returns the charge

## ◆ getConditionalFragmentIsotopeDist()

IsotopeDistribution getConditionalFragmentIsotopeDist | ( | const EmpiricalFormula & | precursor,
|  | const std::set< UInt > & | precursor_isotopes,
|  | const CoarseIsotopePatternGenerator & | method
| ) |  | const

returns the fragment isotope distribution of this given a precursor formula and conditioned on a set of isolated precursor isotopes.

The max_depth of the isotopic distribution is set to max(precursor_isotopes)+1.

Parameters

  precursor | the empirical formula of the precursor
  precursor_isotopes | the precursor isotopes that were isolated
  method | the method that will be used for the calculation of the IsotopeDistribution

Returns
  the conditional IsotopeDistribution of the fragment

## ◆ getIsotopeDistribution()

IsotopeDistribution getIsotopeDistribution | ( | const IsotopePatternGenerator & | method | ) | const

returns the isotope distribution of the formula The details of the calculation of the isotope distribution are described in the doc to the CoarseIsotopePatternGenerator class.

Parameters

  method | the method that will be used for the calculation of the IsotopeDistribution

Referenced by MetaProSIPDecomposition::calculateIsotopePatternsFor13CRange(), MetaProSIPDecomposition::calculateIsotopePatternsFor15NRange(), MetaProSIPDecomposition::calculateIsotopePatternsFor18ORange(), and MetaProSIPDecomposition::calculateIsotopePatternsFor2HRange().

## ◆ getMonoWeight()

double getMonoWeight | ( |  | ) | const

returns the mono isotopic weight of the formula (includes proton charges)

Referenced by NucleicAcidSearchEngine::main_().

## ◆ getNumberOf()

SignedSize getNumberOf | ( | const Element * | element | ) | const

returns the number of atoms for a certain `element` (can be negative)

Referenced by MetaProSIPDecomposition::calculateIsotopePatternsFor13CRange(), MetaProSIPDecomposition::calculateIsotopePatternsFor15NRange(), MetaProSIPDecomposition::calculateIsotopePatternsFor18ORange(), MetaProSIPDecomposition::calculateIsotopePatternsFor2HRange(), and MetaProSIPDecomposition::getNumberOfLabelingElements().

## ◆ getNumberOfAtoms()

SignedSize getNumberOfAtoms | ( |  | ) | const

returns the atoms total (not absolute: negative counts for certain elements will reduce the overall count). Negative result is possible.

## ◆ hasElement()

bool hasElement | ( | const Element * | element | ) | const

returns true if the formula contains the element

## ◆ isCharged()

bool isCharged | ( |  | ) | const

returns true if charge != 0

## ◆ isEmpty()

bool isEmpty | ( |  | ) | const

returns true if the formula does not contain a element

## ◆ operator!=()

bool operator!= | ( | const EmpiricalFormula & | rhs | ) | const

returns true if the formulas differ in elements composition

## ◆ operator*()

EmpiricalFormula operator* | ( | const SignedSize & | times | ) | const

multiplies the elements and charge with a factor

## ◆ operator+()

EmpiricalFormula operator+ | ( | const EmpiricalFormula & | rhs | ) | const

adds the elements of the given formula and returns a new formula

## ◆ operator+=()

EmpiricalFormula& operator+= | ( | const EmpiricalFormula & | rhs | ) |

adds the elements of the given formula

## ◆ operator-()

EmpiricalFormula operator- | ( | const EmpiricalFormula & | rhs | ) | const

subtracts the elements of a formula an returns a new formula

## ◆ operator-=()

EmpiricalFormula& operator-= | ( | const EmpiricalFormula & | rhs | ) |

subtracts the elements of a formula

## ◆ operator<()

bool operator< | ( | const EmpiricalFormula & | rhs | ) | const

less operator

## ◆ operator=() [1/2]

EmpiricalFormula& operator= | ( | const EmpiricalFormula & |  | ) |

default

Assignment operator.

Assignment

## ◆ operator=() [2/2]

EmpiricalFormula& operator= | ( | EmpiricalFormula && |  | ) | &

default

Move assignment operator.

## ◆ operator==()

bool operator== | ( | const EmpiricalFormula & | rhs | ) | const

returns true if the formulas contain equal elements in equal quantities

## ◆ parseFormula_()

Int parseFormula_ | ( | std::map< const Element *, SignedSize > & | ef,
|  | const String & | formula
| ) |  | const

protected

## ◆ removeZeroedElements_()

void removeZeroedElements_ | ( |  | ) |

protected

remove elements with count 0

## ◆ setCharge()

void setCharge | ( | Int | charge | ) |

sets the charge

## ◆ toMap()

std::map<std::string, int> toMap | ( |  | ) | const

returns the formula as a map (charges are not included)

## ◆ toString()

String toString | ( |  | ) | const

returns the formula as a string (charges are not included)

Referenced by SvmTheoreticalSpectrumGenerator::IonType::operator<().

## Friends And Related Function Documentation

## ◆ operator<<

std::ostream& operator<< | ( | std::ostream & | os,
|  | const EmpiricalFormula & | formula
| ) |  |

friend

writes the formula to a stream

## Member Data Documentation

## ◆ charge_

Int charge_

protected

## ◆ formula_

MapType_ formula_

protected