Mass and isotopes — Pyteomics documentation v4.7.2 (2024)

Basic mass calculations¶

The most common task in mass spectrometry data analysis is to calculate themass of an organic molecule or peptide or m/z ratio of an ion.The tasks of this kind can be performed with thepyteomics.mass.calculate_mass() function. It works withchemical formulas, polypeptide sequences in modX notation, pre-parsed sequencesand dictionaries of chemical compositions:

>>> from pyteomics import mass>>> mass.calculate_mass(formula='H2O')18.0105646837036>>> mass.calculate_mass(formula='C2H5OH')46.0418648119876>>> mass.calculate_mass(composition={'H':2, 'O':1})18.0105646837036>>> mass.calculate_mass(sequence='PEPTIDE')799.359964027207>>> from pyteomics import parser>>> ps = parser.parse('PEPTIDE', show_unmodified_termini=True)>>> mass.calculate_mass(parsed_sequence=ps)799.359964027207

Mass-to-charge ratio of ions¶

pyteomics.mass.calculate_mass() can be used to calculate the mass/chargeratio of peptide ions and ionized fragments. To do that, simply supply the typeof the peptide ionized fragment and its charge:

>>> from pyteomics import mass>>> mass.calculate_mass(sequence='PEPTIDE', ion_type='M', charge=2)400.6872584803735>>> mass.calculate_mass(sequence='PEP', ion_type='b', charge=1)324.15539725264904>>> mass.calculate_mass(sequence='TIDE', ion_type='y', charge=1)477.219119708098

Mass of modified peptides¶

With pyteomics.mass.calculate_mass() you can calculate masses ofmodified peptides as well. For the function to recognize the modified residue,you need to add the information about its elemental composition to thepyteomics.mass.std_aa_comp dictionary used in the calculations bydefault.

>>> from pyteomics import mass>>> mass.std_aa_comp['pT'] = mass.Composition(...  {'C': 4, 'H': 8, 'N': 1, 'O': 5, 'P': 1})>>> mass.calculate_mass(sequence='PEPpTIDE')879.3262945499629

To add information about modified amino acids to a user-defined aa_comp dictone can either add the composition info for a specific modified residue or justfor a modification:

>>> from pyteomics import mass>>> aa_comp = dict(mass.std_aa_comp)>>> aa_comp['p'] = mass.Composition('HPO3')>>> mass.calculate_mass('pT', aa_comp=aa_comp)199.02457367493957

In this example we call calculate_mass() with a positional(non-keyword) argument (‘pT’). This feature was added in version1.2.4. When you provide a non-keyword argument, it will be treated as a sequence;if it fails, it will be treated as a formula; in case it fails as well, aPyteomicsError will be raised.Note that ‘pT’ is treated as a sequence here, so default terminal groups areimplied when calculating the composition and mass:

>>> mass.calculate_mass('pT', aa_comp=aa_comp) == mass.calculate_mass(aa_comp['p']) + mass.calculate_mass(aa_comp['T']) + mass.calculate_mass('H2O')True

You can create a specific entry for a modified amino acid to override themodification on a specific residue:

>>> aa_comp['pT'] = mass.Composition({'N': 2})>>> mass.Composition('pT', aa_comp=aa_comp){'H': 2, 'O': 1, 'N': 2}>>> mass.Composition('pS', aa_comp=aa_comp){'H': 8, 'C': 3, 'N': 1, 'O': 6, 'P': 1}

Unimod database is an excellent resource for theinformation on the chemical compositions of known protein modifications.Version 2.0.3 introduces pyteomics.mass.Unimod class that can serveas a Python interface to Unimod:

>>> db = mass.Unimod()>>> aa_comp = dict(mass.std_aa_comp)>>> aa_comp['p'] = db.by_title('Phospho')['composition']>>> mass.calculate_mass('PEpTIDE', aa_comp=aa_comp)782.2735307010443

Chemical compositions¶

Some problems in organic mass spectrometry deal with molecules made byaddition or subtraction of standard chemical ‘building blocks’.In pyteomics.mass there are two ways to approach these problems.

• There is a pyteomics.mass.Composition class intended to storechemical formulas. pyteomics.mass.Composition objects are dictsthat can be added or subtracted from one another or multiplied by integers.

  >>> from pyteomics import mass>>> p = mass.Composition(formula='HO3P') # Phosphate groupComposition({'H': 1, 'O': 3, 'P': 1})>>> mass.std_aa_comp['T']Composition{'C': 4, 'H': 7, 'N': 1, 'O': 2})>>> p + mass.std_aa_comp['T']Composition({'C': 4, 'H': 8, 'N': 1, 'O': 5, 'P': 1})

  The values of pyteomics.mass.std_aa_comp arepyteomics.mass.Composition objects.

• All functions that accept a formula keyword argument sum andsubtract numbers following the same atom in the formula:

  >>> from pyteomics import mass>>> mass.calculate_mass(formula='C2H6') # Ethane30.046950192426>>> mass.calculate_mass(formula='C2H6H-2') # Ethylene28.031300128284002

Faster mass calculations¶

While pyteomics.mass.calculate_mass() has a flexible and convenientinterface, it may be too slow for large-scale calculations. There is anoptimized and simplified version of this function namedpyteomics.mass.fast_mass(). It works only with unmodified sequences instandard one-letter IUPAC notation. Like pyteomics.mass.calculate_mass(),pyteomics.mass.fast_mass() can calculate m/z when provided with iontype and charge. Amino acid masses can be specified via the aa_mass argument.

>>> from pyteomicss import mass>>> mass.fast_mass('PEPTIDE')799.3599446837036

If you need to calculate the mass or m/z for a peptide with modificationsand/or non-standard terminal groups, but don’t want to specify all compositions,you can also use the pyteomics.mass.fast_mass2() function. It usesaa_mass the same way as fast_mass(), but has full modX support:

>>> mass.fast_mass2('H-PEPTIDE-OH')799.3599446837036

Isotopes¶

If not specified, pyteomics.mass assumes that the substances are inthe pure isotopic state. However, you may specify particular isotopic state inbrackets (e.g. O[18], N[15]) in a chemical formula. An element with unspecifiedisotopic state is assumed to have the mass of the most stable isotope andabundance of 100%.

>>> mass.calculate_mass(formula='H[2]2O') # Heavy water20.0231181752416>>> mass.calculate_mass(formula='H[2]HO') # Semiheavy water19.0168414294726

pyteomics.mass.isotopic_composition_abundance() function calculates therelative abundance of a given isotopic state of a molecule. The input can beprovided as a formula or as a Composition/dict.

>>> from pyteomics import mass>>> mass.isotopic_composition_abundance(formula='H2O') # Water with an unspecified isotopic state1.0>>> mass.isotopic_composition_abundance(formula='H[2]2O') # Heavy water1.3386489999999999e-08>>> mass.isotopic_composition_abundance(formula='H[2]H[1]O') # Semiheavy water0.0002313727050147582>>> mass.isotopic_composition_abundance(composition={'H[2]’: 1, ‘H[1]’: 1, ‘O': 1}) # Semiheavy water0.0002313727050147582>>> mass.isotopic_composition_abundance(formula='H[2]2O[18]') # Heavy-hydrogen heavy-oxygen water2.7461045585999998e-11

>>> mass.isotopic_composition_abundance(formula='H[2]HO')...PyteomicsError: Pyteomics error, message: 'Please specify the isotopic states of all atoms of H or do not specify them at all.'

Finally, you can find the most probable isotopic composition for a substancewith pyteomics.mass.most_probable_isotopic_composition() function. Thesubstance is specified as a formula, a pyteomics.mass.Compositionobject or a modX sequence string.

>>> from pyteomics import mass>>> mass.most_probable_isotopic_composition(formula='H2SO4')Composition({'H[1]': 2.0, 'H[2]': 0.0, 'O[16]': 4.0, 'O[17]': 0.0, 'S[32]': 1.0, 'S[33]': 0.0})>>> mass.most_probable_isotopic_composition(formula='C300H602')Composition({'C[12]': 297.0, 'C[13]': 3.0, 'H[1]': 602.0, 'H[2]': 0.0})>>> mass.most_probable_isotopic_composition(sequence='PEPTIDE'*100)Composition({'C[12]': 3364.0, 'C[13]': 36.0, 'H[1]': 5102.0, 'H[2]': 0.0, 'N[14]': 698.0, 'N[15]': 2.0, 'O[16]': 398.0, 'O[17]': 3.0})

The information about chemical elements, their isotopes and relative abundancesis stored in the pyteomics.mass.nist_mass dictionary.

>>> from pyteomics import mass>>> print mass.nist_mass['C']{0: (12.0, 1.0), 12: (12.0, 0.98938), 13: (13.0033548378, 0.01078), 14: (14.0032419894, 0.0)}

The zero key stands for the unspecified isotopic state. The data about isotopesare stored as tuples (accurate mass, relative abundance).