OpenMS
EmpiricalFormula Class Reference

Representation of an empirical formula. More...

#include <OpenMS/CHEMISTRY/EmpiricalFormula.h>

Collaboration diagram for EmpiricalFormula:
[legend]

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

Accessors
double getMonoWeight () const
 returns the monoisotopic (most abundant isotope per element) weight of the formula (includes proton charges) More...
 
double getLightestIsotopeWeight () const
 returns the sum of the lightest isotopes per element in 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 estimateFromMonoWeightAndComp (double mono_weight, double C, double H, double N, double O, double S, double P)
 Fills this EmpiricalFormula with an approximate elemental composition for a given monoisotopic 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...
 
EmpiricalFormulaoperator= (const EmpiricalFormula &)=default
 Assignment operator. More...
 
EmpiricalFormulaoperator= (EmpiricalFormula &&) &=default
 Move assignment operator. More...
 
EmpiricalFormulaoperator+= (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...
 
EmpiricalFormulaoperator-= (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...
 
Iterators
ConstIterator begin () const
 
ConstIterator end () const
 
Iterator begin ()
 
Iterator end ()
 

Protected Types

typedef std::map< const Element *, SignedSizeMapType_
 Internal typedef for the used map type. More...
 

Static member functions

MapType_ formula_
 
Int charge_
 
static EmpiricalFormula hydrogen (int n_atoms=1)
 Efficiently generates a formula for hydrogen. More...
 
static EmpiricalFormula water (int n_molecules=1)
 Efficiently generates a formula for water. More...
 
void removeZeroedElements_ ()
 remove elements with count 0 More...
 
Int parseFormula_ (std::map< const Element *, SignedSize > &ef, const String &formula) const
 

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...
 
static EmpiricalFormula fromString (const String &rhs)
 create EmpiricalFormular object by parsing an OpenMS string 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) const
 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...
 
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 13C a heavy isotope of carbon it is expressed as "(13)C". The isotope distribution of that instance contains only one isotope, 13C itself with a frequency of 100%. It is possible to mix isotopes, for example "(13)C1CH6O" specifies an ethanol molecule with one 12C and one 13C isotope.

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]

Default constructor.

◆ EmpiricalFormula() [2/5]

EmpiricalFormula ( const EmpiricalFormula )
default

Copy constructor.

◆ EmpiricalFormula() [3/5]

Move constructor.

◆ EmpiricalFormula() [4/5]

EmpiricalFormula ( const String rhs)
explicit

Constructor from an OpenMS String

Exceptions
throwsParseError 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]

Iterator begin ( )
inline

◆ begin() [2/2]

ConstIterator begin ( ) const
inline

◆ calculateTheoreticalIsotopesNumber()

double calculateTheoreticalIsotopesNumber ( ) const

returns the total number of discrete isotopes

◆ contains()

bool contains ( const EmpiricalFormula ef) const

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

◆ end() [1/2]

Iterator end ( )
inline

◆ end() [2/2]

ConstIterator end ( ) const
inline

◆ estimateFromMonoWeightAndComp()

bool estimateFromMonoWeightAndComp ( double  mono_weight,
double  C,
double  H,
double  N,
double  O,
double  S,
double  P 
)

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

Parameters
mono_weightMonoisotopic weight to estimate an EmpiricalFormula for
CThe approximate relative stoichiometry of Carbons to other elements in this molecule
HThe approximate relative stoichiometry of Hydrogens to other elements in this molecule
NThe approximate relative stoichiometry of Nitrogens to other elements in this molecule
OThe approximate relative stoichiometry of Oxygens to other elements in this molecule
SThe approximate relative stoichiometry of Sulfurs to other elements in this molecule
PThe 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.

◆ 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_weightAverage weight to estimate an EmpiricalFormula for
CThe approximate relative stoichiometry of Carbons to other elements in this molecule
HThe approximate relative stoichiometry of Hydrogens to other elements in this molecule
NThe approximate relative stoichiometry of Nitrogens to other elements in this molecule
OThe approximate relative stoichiometry of Oxygens to other elements in this molecule
SThe approximate relative stoichiometry of Sulfurs to other elements in this molecule
PThe 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_weightAverage weight to estimate an EmpiricalFormula for
SThe exact number of Sulfurs in this molecule
CThe approximate relative stoichiometry of Carbons to other elements (excluding Sulfur) in this molecule
HThe approximate relative stoichiometry of Hydrogens to other elements (excluding Sulfur) in this molecule
NThe approximate relative stoichiometry of Nitrogens to other elements (excluding Sulfur) in this molecule
OThe approximate relative stoichiometry of Oxygens to other elements (excluding Sulfur) in this molecule
PThe 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.

◆ fromString()

static EmpiricalFormula fromString ( const String rhs)
inlinestatic

create EmpiricalFormular object by parsing an OpenMS string

Parameters
sInput string
Exceptions
Exception::ParseErrorif the formula cannot be parsed

◆ getAverageWeight()

double getAverageWeight ( ) const

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

◆ 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
precursorthe empirical formula of the precursor
precursor_isotopesthe precursor isotopes that were isolated
methodthe 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
methodthe method that will be used for the calculation of the IsotopeDistribution

◆ getLightestIsotopeWeight()

double getLightestIsotopeWeight ( ) const

returns the sum of the lightest isotopes per element in the formula (includes proton charges)

◆ getMonoWeight()

double getMonoWeight ( ) const

returns the monoisotopic (most abundant isotope per element) weight of the formula (includes proton charges)

◆ getNumberOf()

SignedSize getNumberOf ( const Element element) const

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

◆ 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

◆ hydrogen()

static EmpiricalFormula hydrogen ( int  n_atoms = 1)
static

Efficiently generates a formula for hydrogen.

◆ 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)

◆ water()

static EmpiricalFormula water ( int  n_molecules = 1)
static

Efficiently generates a formula for water.

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