`chemistry_tools.formulae.formula`

Attention

This module has the following additional requirements:

cawdrey>=0.5.0
mathematical>=0.5.1
pyparsing>=2.4.6
tabulate>=0.8.9

These can be installed as follows:

python -m pip install chemistry-tools[formulae]

Parse formulae into a Python object.

Data:

`F`	Invariant `TypeVar` bound to `chemistry_tools.formulae.formula.Formula`.

Classes:

Formula([composition, charge])

A Formula object stores a chemical composition of a compound.

F = TypeVar(F, bound=Formula)

Type: TypeVar

Invariant TypeVar bound to chemistry_tools.formulae.formula.Formula.

class Formula(composition=None, charge=0)[source]

Bases: defaultdict, Counter

A Formula object stores a chemical composition of a compound. It is based on dict, with the symbols of chemical elements as keys and the values equal to the number of atoms of the corresponding element in the compound.

Parameters

composition (Optional[Dict[str, int]]) – A Formula object with the elemental composition of a substance, or a dict representing the same. If None an empty object is created. Default None.
charge (int) – Default 0.

Methods:

`__add__`(other)	Return `self + value`.
`__eq__`(other)	Return `self == other`.
`__iadd__`(other)	Inplace add from another counter, keeping only positive counts.
`__imul__`(other)	rtype `Formula`
`__isub__`(other)	Inplace subtract counter, but keep only results with positive counts.
`__mul__`(other)	Return `self * value`.
`__radd__`(other)	Return `value + self`.
`__repr__`()	Return a string representation of the `Formula`.
`__rmul__`(other)	Return `value * self`.
`__rsub__`(other)	Return `value - self`.
`__setitem__`(key, value)	Set `self[key]` to `value`.
`__str__`()	Return `str(self)`.
`__sub__`(other)	Return `value - self`.
`copy`()	Returns a copy of the `Formula`.
`from_kwargs`(*[, charge])	Create a new `Formula` object from keyword arguments representing the elements in the compound.
`from_mass_fractions`(fractions[, charge, …])	Create a new `Formula` object from elemental mass fractions by parsing a string.
`from_string`(formula[, charge])	Create a new `Formula` object by parsing a string.
`get_mz`([average, charge])	Calculate the average mass:charge ratio (m/z) of a `Formula`.
`isotope_distribution`()	Returns an `IsotopeDistribution` object representing the distribution of the isotopologues of the formula.
`iter_isotopologues`([report_abundance, …])	Iterate over possible isotopic states of the molecule.
`most_probable_isotopic_composition`([…])	Calculate the most probable isotopic composition of a molecule/ion.

Attributes:

`average_mass`	Calculate the average mass of a `Formula`.
`average_mz`	The average mass to charge ratio of the formula.
`composition`	A `Composition` object representing the elemental composition of the Formula.
`elements`	A list of the element symbols in the formula.
`empirical_formula`	Returns the empirical formula in Hill notation.
`exact_mass`	Calculate the monoisotopic mass of a `Formula`.
`hill_formula`	Returns the formula in Hill notation.
`isotopic_composition_abundance`	Calculate the relative abundance of the current isotopic composition of this molecule.
`mass`	Calculate the average mass of a `Formula`.
`monoisotopic_mass`	Calculate the monoisotopic mass of a `Formula`.
`mz`	The mass to charge ratio of the formula.
`n_atoms`	Return the number of atoms in the formula.
`n_elements`	Return the number of elements in the formula.
`no_isotope_hill_formula`	Returns formula in Hill notation, without any isotopes specified.
`nominal_mass`	Calculate the monoisotopic mass of a `Formula`.

__add__(other)[source]: Return self + value.

__eq__(other)[source]

Return self == other.

Return type: bool

__iadd__(other)[source]

Inplace add from another counter, keeping only positive counts.

>>> c = Counter('abbb')
>>> c += Counter('bcc')
>>> c
Counter({'b': 4, 'c': 2, 'a': 1})

Return type: Formula

__imul__(other)[source]

Return type: Formula

__isub__(other)[source]

Inplace subtract counter, but keep only results with positive counts.

>>> c = Counter('abbbc')
>>> c -= Counter('bccd')
>>> c
Counter({'b': 2, 'a': 1})

Return type: Formula

__mul__(other)[source]

Return self * value.

Return type: Formula

__radd__(other)[source]: Return value + self.

__repr__()[source]

Return a string representation of the Formula.

Return type: str

__rmul__(other)[source]: Return value * self.

__rsub__(other)[source]: Return value - self.

__setitem__(key, value)[source]: Set self[key] to value.

__str__()[source]

Return str(self).

Return type: str

__sub__(other)[source]: Return value - self.

property average_mass

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Return type: float

property average_mz

The average mass to charge ratio of the formula.

Return type: float

property composition

A Composition object representing the elemental composition of the Formula.

Return type: Composition

copy()[source]

Returns a copy of the Formula.

Return type: ~F

property elements

A list of the element symbols in the formula.

Return type: List[str]

property empirical_formula

Returns the empirical formula in Hill notation.

The empirical formula has the simplest whole number ratio of atoms of each element present in the formula.

Examples:

>>> Formula.from_string('H2O').empirical_formula
'H2O'
>>> Formula.from_string('S4').empirical_formula
'S'
>>> Formula.from_string('C6H12O6').empirical_formula
'CH2O'

Return type: str

property exact_mass

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Return type: float

classmethod from_kwargs(*, charge=0, **kwargs)[source]

Create a new Formula object from keyword arguments representing the elements in the compound.

Parameters: charge (int) – Default 0.
Return type: ~F

classmethod from_mass_fractions(fractions, charge=0, maxcount=10, precision=0.0001)[source]

Create a new Formula object from elemental mass fractions by parsing a string.

Note

Isotopes cannot (currently) be parsed using this method

Parameters

fractions (Dict[str, float]) – A dictionary of elements and mass fractions
charge (int) – Default 0.
maxcount (int) – Default 10.
precision (float) – Default 0.0001.

Examples:

>>> Formula.from_mass_fractions({'H': 0.112, 'O': 0.888})
'H2O'
>>> Formula.from_mass_fractions({'D': 0.2, 'O': 0.8})
'O[2H]2'
>>> Formula.from_mass_fractions({'H': 8.97, 'C': 59.39, 'O': 31.64})
'C5H9O2'
>>> Formula.from_mass_fractions({'O': 0.26, '30Si': 0.74})
'O2[30Si]3'

Return type: Formula

classmethod from_string(formula, charge=0)[source]

Create a new Formula object by parsing a string.

Note

Isotopes cannot (currently) be parsed using this method

Parameters

formula (str) – A string with a chemical formula
charge (int) – Default 0.

Return type: ~F

get_mz(average=True, charge=None)[source]

Calculate the average mass:charge ratio (m/z) of a Formula.

Parameters

average (bool) – If True then the average m/z is calculated. Note that the mass is not averaged for elements with specified isotopes. Default True.
charge (Optional[int]) – The charge of the compound. If None then the existing charge of the Formula is used. Default None.

Return type

float

property hill_formula

Returns the formula in Hill notation.

Example:

>>> Formula.from_string('BrC2H5').hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').hill_formula
'C6H18NNaSi4'

Return type: str

isotope_distribution()[source]

Returns an IsotopeDistribution object representing the distribution of the isotopologues of the formula.

Return type: IsotopeDistribution

property isotopic_composition_abundance

Calculate the relative abundance of the current isotopic composition of this molecule.

Return type: float
Returns: The relative abundance of the current isotopic composition.

iter_isotopologues(report_abundance=False, elements_with_isotopes=None, isotope_threshold=0.0005, overall_threshold=0)[source]

Iterate over possible isotopic states of the molecule.

The space of possible isotopic compositions is restrained by parameters elements_with_isotopes, isotope_threshold, overall_threshold.

Parameters

report_abundance (bool) – If True, the output will contain 2-tuples: (composition, abundance). Otherwise, only compositions are yielded. Default False.
elements_with_isotopes (Optional[Sequence[str]]) – A set of elements to be considered in isotopic distributions (by default, every element has an isotopic distribution). Default None.
isotope_threshold (float) – The threshold abundance of a specific isotope to be considered. Default 0.0005.
overall_threshold (float) – The threshold abundance of the calculated isotopic composition. Default 0.

Return type

Iterator

Returns

Iterator over possible isotopic compositions.

property mass

Calculate the average mass of a Formula.

Note that mass is not averaged for elements with specified isotopes.

Return type: float

property monoisotopic_mass

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Return type: float

most_probable_isotopic_composition(elements_with_isotopes=None)[source]

Calculate the most probable isotopic composition of a molecule/ion.

For each element, only two most abundant isotopes are considered. Any isotopes already in the Formula will be changed to the most abundant isotope

Parameters: elements_with_isotopes (Optional[Sequence[str]]) – A set of elements to be considered in isotopic distribution (by default, every element has an isotopic distribution). Default None.
Return type: Tuple[Formula, float]
Returns: A tuple with the most probable isotopic composition and its relative abundance.

property mz

The mass to charge ratio of the formula.

Return type: float

property n_atoms

Return the number of atoms in the formula.

Example:

>>> Formula.from_string('CH3COOH').n_atoms
8

Return type: int

property n_elements

Return the number of elements in the formula.

Return type: int

Example:

>>> Formula.from_string('CH3COOH').n_elements
3

property no_isotope_hill_formula

Returns formula in Hill notation, without any isotopes specified.

Example:

>>> Formula.from_string('BrC2H5').no_isotope_hill_formula
'C2H5Br'
>>> Formula.from_string('HBr').no_isotope_hill_formula
'BrH'
>>> Formula.from_string('[(CH3)3Si2]2NNa').no_isotope_hill_formula
'C6H18NNaSi4'

Return type: str

property nominal_mass

Calculate the monoisotopic mass of a Formula. If any isotopes are already present in the formula, the mass of these will be preserved

Return type: float

chemistry_tools.formulae.formula

`chemistry_tools.formulae.formula`