Representation of an empirical formula. More...

#include <OpenMS/CHEMISTRY/EmpiricalFormula.h>

Collaboration diagram for EmpiricalFormula:

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...

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...

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...

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 EmpiricalFormula object from a 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]

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]

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_weight	Monoisotopic 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.

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

◆ fromString()

static EmpiricalFormula fromString ( const String & rhs )

inlinestatic

Create EmpiricalFormula object from a String.

Parameters

rhs	Input string

Exceptions

Exception::ParseError if 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

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

◆ 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

Public Types

Public Member Functions

Protected Types

Static member functions

Constructors and Destructors

Predicates

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ ConstIterator

◆ Iterator

◆ iterator

◆ MapType_

Constructor & Destructor Documentation

◆ EmpiricalFormula() [1/5]

◆ EmpiricalFormula() [2/5]

◆ EmpiricalFormula() [3/5]

◆ EmpiricalFormula() [4/5]

◆ EmpiricalFormula() [5/5]

◆ ~EmpiricalFormula()

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ calculateTheoreticalIsotopesNumber()

◆ contains()

◆ end() [1/2]

◆ end() [2/2]

◆ estimateFromMonoWeightAndComp()

◆ estimateFromWeightAndComp()

◆ estimateFromWeightAndCompAndS()

◆ fromString()

◆ getAverageWeight()

◆ getCharge()

◆ getConditionalFragmentIsotopeDist()

◆ getIsotopeDistribution()

◆ getLightestIsotopeWeight()

◆ getMonoWeight()

◆ getNumberOf()

◆ getNumberOfAtoms()

◆ hasElement()

◆ hydrogen()

◆ isCharged()

◆ isEmpty()

◆ operator!=()

◆ operator*()

◆ operator+()

◆ operator+=()

◆ operator-()

◆ operator-=()

◆ operator<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ parseFormula_()

◆ removeZeroedElements_()

◆ setCharge()

◆ toMap()

◆ toString()

◆ water()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ charge_

◆ formula_