Skip to content

Chemistry And Adducts

This page highlights the most often used API functionalities and is not complete. It covers molecular formula parsing (mf), exact masses (mass), isotope abundance (abundance), and adduct definitions (adducts). For complete coverage, see the API Reference.

Chemistry Basics

emzed exposes chemistry APIs in four common entry points:

  • mf(...): parse molecular formulas into formula objects
  • mass: exact masses (for formulas/elements/isotopes)
  • abundance: natural isotope abundances
  • adducts: predefined adduct tables for annotation workflows

Usage Pattern

import emzed

glucose = emzed.mf("C6H12O6")
water_mass = emzed.mass.of("H2O")
carbon13_abundance = emzed.abundance.C13

pos_adducts = emzed.adducts.positive
single_charged = emzed.adducts.single_charged

print(glucose, glucose.mass())
print(water_mass)
print(carbon13_abundance)
print(len(pos_adducts), len(single_charged))

C6H12O6 180.0633903828
18.0105650638
0.010700000000000001
35 39

mf

Parse molecular formulas and create formula objects that support arithmetic and mass calculation. Return type: emzed.chemistry.molecular_formula.MolecularFormula.

Supported methods/operators on the returned object:

  • string representation: str(mf) (__str__)
  • conversion helpers: as_dict(), as_string()
  • mass calculation: mass(...)
  • algebra operators: +, -, * (and int * mf via __rmul__)

Represent a molecular formula as both string and element-count mapping.

Example:

import emzed

mf = emzed.mf("C6H12O6")
protonated = mf + emzed.mf("H")
# print(...) converts MolecularFormula objects to strings
print(mf, protonated, mf.mass())
print(2 * mf)

C6H12O6 C6H13O6 180.0633903828
C12H24O12

Common formula-object methods:

import emzed

mf = emzed.mf("C6H12O6")
print(mf.as_dict())
print(mf.as_string())

{'C': 6, 'H': 12, 'O': 6}
C6H12O6

MolecularFormula Methods

as_dict

Return the molecular formula as a plain dict mapping atoms to counts.

as_string

Return the normalized molecular-formula string or None if invalid.

MolecularFormula.mass

Calculate the exact mass of the formula.

Parameters:

Name Type Description Default
specialisations

optional isotope overrides such as C=12.0 or C=mass.C12 for unresolved elements.

 {}

Returns:

Type Description

exact mass as float or None if an element/isotope is unknown.

mass

Exact-mass namespace. Common usage is emzed.mass.of(...). It also exposes particle masses (e, n, p) and element/isotope accessors such as mass.O and mass.O17.

Exact-mass data is loaded from bundled OpenMS element data (chemistry/Elements.xml) and extended with the bundled PubChem export (chemistry/elements_pubchem.json).

Exact-mass utilities for formulas, particles, and isotopes.

of

Calculate the exact mass for a molecular formula.

Parameters:

Name Type Description Default
mf

molecular formula string.

 required
specialisation

optional isotope specialisations forwarded to emzed.chemistry.MolecularFormula.mass.

 {}

Returns:

Type Description

exact mass as float.

Example:

import emzed

print(emzed.mass.e)
print(emzed.mass.n)
print(emzed.mass.p)
print(emzed.mass.O)    # dict of all isotope mass numbers for O (unlike mass.O16, etc.)
print(emzed.mass.O17)
print(emzed.mass.of("H2O"))
print(emzed.mass.of("[13]C"))

0.00054857990946
1.008664916
1.007276466812
{16: 15.994915, 17: 16.999132, 18: 17.999169}
16.999132
18.010565
13.003355

abundance

Isotope-abundance namespace (for example C13, O18, ...).

Natural isotope abundances.

Provides isotope abundance values such as C12 and element abundance maps such as C.

Example:

import emzed

print(emzed.abundance.C13)
print(emzed.abundance.O18)

adducts

Predefined adduct tables used for candidate generation and targeted annotation. Common subsets include all, positive, negative, and single_charged.

Predefined adduct tables and convenience subsets for targeted annotation.

The module exposes:

  • all: every predefined adduct
  • charge-based subsets such as positive and negative
  • single-adduct tables addressable as Python identifiers such as M_plus_H

Example:

import emzed

adducts = emzed.adducts.single_charged
print(adducts[:5])
print()
print(emzed.adducts.M_plus_H)

id   adduct_name  m_multiplier  adduct_add  adduct_sub  z    sign_z
int  str          int           str         str         int  int
---  -----------  ------------  ----------  ----------  ---  ------
  2  M-                      1                            1      -1
  3  M-H                     1              H             1      -1
  4  M-H2O-H                 1              H2OH          1      -1
  5  M+Na-2H                 1  Na          H2            1      -1
  6  M+Cl                    1  Cl                        1      -1

id   adduct_name  m_multiplier  adduct_add  adduct_sub  z    sign_z
int  str          int           str         str         int  int
---  -----------  ------------  ----------  ----------  ---  ------
 20  M+H                     1  H                         1       1