tidyms.chem.formula

Tools for working with chemical formulas

Objects

• Formula

Exceptions

• InvalidFormula

class Formula(*args)

Represents a chemical formula as a mapping from isotopes to formula coefficients.

Examples

>>> Formula("H2O")
Formula(H2O)
>>> Formula("(13C)O2")
Formula((13C)O2)
>>> Formula("[Cr(H2O)6]3+")
Formula([H12CrO6]3+)
>>> Formula("CH3CH2CH3")
Formula(C3H8)
>>> Formula({"C": 1, "17O": 2})
Formula(C(17O)2)

Attributes:

composition: Counter

A mapping of Isotopes to formula coefficients.

charge: int

The numerical charge of the formula.

Methods

get_exact_mass()
get_nominal_mass()
get_formula_str()
get_isotopic_envelope()

get_exact_mass() → float

Computes the exact mass of the formula.

Returns:

exact_mass: float

Examples

>>> import tidyms as ms
>>> f = ms.chem.Formula("H2O")
>>> f.get_exact_mass()
18.010564684

get_isotopic_envelope(n: int = 10, p: Dict[str, ndarray] | None = None, min_p: float = 1e-10) → Tuple[ndarray, ndarray]

Computes the isotopic envelope of the formula.

The natural abundance is assumed for each monoisotope, i.e., the most abundant isotope. If others isotopes are present in the formula, they are assumed to have abundance equal to 1. See the examples for a clarification of this.

Parameters:

n: int

the number of isotopes to include in the results.

p: Dict[str, array] or None, default=None

used to pass custom abundances for elements. each key, value pair is composed of an element symbol str and a numpy array with the abundances. The sum of the abundances must be 1 and the size of the array must be the same as the number of stable isotopes for the given element.

min_p: float

Isotopes are included until the abundance is lower than this value

Returns:

Mnumpy.ndarray

Exact mass of the envelope

pnumpy.ndarray

Abundance of the envelope

Examples

If no isotopes are specified in the formula, the natural abundance is asumed:

>>> import tidyms as ms
>>> f = ms.chem.Formula("C6H6")
>>> print(f)
C6H6
>>> f.get_isotopic_envelope(n=3)
(array([78.04695019, 79.05033578, 80.05373322]),
 array([0.93686877, 0.06144402, 0.00168606]))

Using isotopes other than the monoisotope are treated as if they have an abundance equal to one.

>>> f = ms.chem.Formula("(13C)6(2H)6")
>>> print(f)
(13C)6(2H)6
>>> f.get_isotopic_envelope()
(array([90.10473971]), array([1.]))

get_nominal_mass() → int

Computes the nominal mass of the formula.

Returns:

int

Examples

>>> import tidyms as ms
>>> f = ms.chem.Formula("H2O")
>>> f.get_nominal_mass()
18

exception InvalidFormula