corems.encapsulation.constant

  1from corems.encapsulation import nist_atoms
  2
  3# Default gzip level for HDF5 datasets on the mass spectrum and LC-MS
  4# export path. Callers pass it as the compression argument of
  5# hdf5_dataset_kwargs and to_hdf().
  6DEFAULT_HDF5_COMPRESSION = 4
  7
  8
  9class Labels:  # pragma: no cover
 10    """Class for Labels used in CoreMS
 11
 12    These labels are used to define:
 13    * types of columns in plaintext data inputs,
 14    * types of data/mass spectra
 15    * types of assignment for ions
 16
 17    """
 18
 19    mz = "m/z"
 20    abundance = "Peak Height"
 21    rp = "Resolving Power"
 22    s2n = "S/N"
 23
 24    label = "label"
 25    bruker_profile = "Bruker_Profile"
 26    thermo_profile = "Thermo_Profile"
 27    simulated_profile = "Simulated Profile"
 28    booster_profile = "Booster Profile"
 29    bruker_frequency = "Bruker_Frequency"
 30    midas_frequency = "Midas_Frequency"
 31    thermo_centroid = "Thermo_Centroid"
 32    corems_centroid = "CoreMS_Centroid"
 33    gcms_centroid = "Thermo_Centroid"
 34
 35    unassigned = "unassigned"
 36
 37    radical_ion = "RADICAL"
 38    protonated_de_ion = "DE_OR_PROTONATED"
 39    protonated = "protonated"
 40    de_protonated = "de-protonated"
 41    adduct_ion = "ADDUCT"
 42    neutral = "neutral"
 43    ion_type = "IonType"
 44
 45    ion_type_translate = {
 46        "protonated": "DE_OR_PROTONATED",
 47        "de-protonated": "DE_OR_PROTONATED",
 48        "radical": "RADICAL",
 49        "adduct": "ADDUCT",
 50        "ADDUCT": "ADDUCT",
 51    }
 52
 53
 54class Atoms:  # pragma: no cover
 55    """Class for Atoms in CoreMS
 56
 57    Public API for exact masses, isotopic abundances, rare-isotope lists,
 58    formula-string order, English names, and covalence. Do not use
 59    ``nist_atoms.isotopes`` as ``Atoms.isotopes``: the generated module stores
 60    a list of rare keys (or ``[None]``); this class stores
 61    ``[English name, rare keys]``.
 62
 63    IUPAC monoisotopic mass uses the most abundant isotope of each element.
 64    Bare element symbols are the most abundant isotope (C, Cl). Rare isotopes
 65    use mass-number keys (13C, 37Cl). Hydrogen uses H and D. Masses and
 66    abundances may also be looked up by nuclide key (12C, 1H). Formula strings
 67    and mass-list columns use ``atoms_order`` (canonical keys only).
 68
 69    Masses, abundances, rare lists, and ``atoms_order`` come from a pinned NIST
 70    snapshot (``corems.encapsulation.nist_atoms``). English names and covalence
 71    are hand-maintained. ``Atoms.isotopes`` membership is not enough to search
 72    an element: ``usedAtoms`` still needs a valence in
 73    ``used_atom_valences`` (usually from ``atoms_covalence``). Pin deltas
 74    and breaking notes are in ``tools/nist_atoms/CHANGES.md``.
 75
 76    References
 77    ----------
 78
 79    1. NIST Atomic Weights and Isotopic Compositions (Coursey et al., version 4.1)
 80    https://www.nist.gov/pml/atomic-weights-and-isotopic-compositions-relative-atomic-masses
 81
 82    """
 83
 84    electron_mass = 0.0005_485_799_090_65  # NIST value
 85
 86    atomic_masses = nist_atoms.atomic_masses
 87    isotopic_abundance = nist_atoms.isotopic_abundance
 88    atoms_order = nist_atoms.atoms_order
 89
 90    # Not a NIST field (the dump has no name column).
 91    element_names = {
 92        "H": "Hydrogen",
 93        "He": "Helium",
 94        "Li": "Lithium",
 95        "Be": "Beryllium",
 96        "B": "Boron",
 97        "C": "Carbon",
 98        "N": "Nitrogen",
 99        "O": "Oxygen",
100        "F": "Fluorine",
101        "Ne": "Neon",
102        "Na": "Sodium",
103        "Mg": "Magnesium",
104        "Al": "Aluminum",
105        "Si": "Silicon",
106        "P": "Phosphorus",
107        "S": "Sulfur",
108        "Cl": "Chlorine",
109        "Ar": "Argon",
110        "K": "Potassium",
111        "Ca": "Calcium",
112        "Sc": "Scandium",
113        "Ti": "Titanium",
114        "V": "Vanadium",
115        "Cr": "Chromium",
116        "Mn": "Manganese",
117        "Fe": "Iron",
118        "Co": "Cobalt",
119        "Ni": "Nickel",
120        "Cu": "Copper",
121        "Zn": "Zinc",
122        "Ga": "Gallium",
123        "Ge": "Germanium",
124        "As": "Arsenic",
125        "Se": "Selenium",
126        "Br": "Bromine",
127        "Kr": "Krypton",
128        "Rb": "Rubidium",
129        "Sr": "Strontium",
130        "Y": "Yttrium",
131        "Zr": "Zirconium",
132        "Nb": "Niobium",
133        "Mo": "Molybdenum",
134        "Ru": "Ruthenium",
135        "Rh": "Rhodium",
136        "Pd": "Palladium",
137        "Ag": "Silver",
138        "Cd": "Cadmium",
139        "In": "Indium",
140        "Sn": "Tin",
141        "Sb": "Antimony",
142        "Te": "Tellurium",
143        "I": "Iodine",
144        "Xe": "Xenon",
145        "Cs": "Cesium",
146        "Ba": "Barium",
147        "La": "Lanthanum",
148        "Ce": "Cerium",
149        "Pr": "Praseodymium",
150        "Nd": "Neodymium",
151        "Sm": "Samarium",
152        "Eu": "Europium",
153        "Gd": "Gadolinium",
154        "Tb": "Terbium",
155        "Dy": "Dysprosium",
156        "Ho": "Holmium",
157        "Er": "Erbium",
158        "Tm": "Thulium",
159        "Yb": "Ytterbium",
160        "Lu": "Lutetium",
161        "Hf": "Hafnium",
162        "Ta": "Tantalum",
163        "W": "Tungsten",
164        "Re": "Rhenium",
165        "Os": "Osmium",
166        "Ir": "Iridium",
167        "Pt": "Platinum",
168        "Au": "Gold",
169        "Hg": "Mercury",
170        "Tl": "Thallium",
171        "Pb": "Lead",
172        "Bi": "Bismuth",
173        "Th": "Thorium",
174        "Pa": "Protactinium",
175        "U": "Uranium",
176    }
177
178    isotopes = {}
179    for symbol, rares in nist_atoms.isotopes.items():
180        isotopes[symbol] = [element_names.get(symbol, symbol), list(rares)]
181    del symbol, rares
182
183    atoms_covalence = {
184        "C": (4),
185        "13C": (4),
186        "N": (3),
187        "O": (2),
188        "S": (2),
189        "H": (1),
190        "F": (1, 0),
191        "Cl": (1, 0),
192        "Br": (1, 0),
193        "I": (1, 0),
194        "Li": (1, 0),
195        "Na": (1, 0),
196        "K": (1, 0),
197        "Rb": (1),
198        "Cs": (1),
199        "B": (4, 3, 2, 1),
200        "In": (3, 2, 1),
201        "Al": (3, 1, 2),
202        "P": (3, 5, 4, 2, 1),
203        "Ga": (3, 1, 2),
204        "Mg": (2, 1),
205        "Be": (2, 1),
206        "Ca": (2, 1),
207        "Sr": (2, 1),
208        "Ba": (2),
209        "V": (5, 4, 3, 2, 1),
210        "Fe": (3, 2, 4, 5, 6),
211        "Si": (4, 3, 2),
212        "Sc": (3, 2, 1),
213        "Ti": (4, 3, 2, 1),
214        "Cr": (1, 2, 3, 4, 5, 6),
215        "Mn": (1, 2, 3, 4, 5, 6, 7),
216        "Co": (1, 2, 3, 4, 5),
217        "Ni": (1, 2, 3, 4),
218        "Cu": (2, 1, 3, 4),
219        "Zn": (2, 1),
220        "Ge": (4, 3, 2, 1),
221        "As": (5, 3, 2, 1),
222        "Se": (6, 4, 2, 1),
223        "Y": (3, 2, 1),
224        "Zr": (4, 3, 2, 1),
225        "Nb": (5, 4, 3, 2, 1),
226        "Mo": (6, 5, 4, 3, 2, 1),
227        "Ru": (8, 7, 6, 5, 4, 3, 2, 1),
228        "Rh": (6, 5, 4, 3, 2, 1),
229        "Pd": (4, 2, 1),
230        "Ag": (0, 1, 2, 3, 4),
231        "Cd": (2, 1),
232        "Sn": (4, 2),
233        "Sb": (5, 3),
234        "Te": (6, 5, 4, 2),
235        "La": (3, 2),
236        "Hf": (4, 3, 2),
237        "Ta": (5, 4, 3, 2),
238        "W": (6, 5, 4, 3, 2, 1),
239        "Re": (4, 7, 6, 5, 3, 2, 1),
240        "Os": (4, 8, 7, 6, 5, 3, 2, 1),
241        "Ir": (4, 8, 6, 5, 3, 2, 1),
242        "Pt": (4, 6, 5, 3, 2, 1),
243        "Au": (3, 5, 2, 1),
244        "Hg": (1, 2, 4),
245        "Tl": (3, 1),
246        "Pb": (4, 2),
247        "Bi": (3, 1, 5),
248    }
249
250
251ION_TYPE_DICT = {
252    "M+": {
253        "add": {},
254        "sub": {},
255        "polarity": "positive",
256    },
257    "[M]+": {
258        "add": {},
259        "sub": {},
260        "polarity": "positive",
261    },
262    "protonated": {
263        "add": {"H": 1},
264        "sub": {},
265        "polarity": "positive",
266    },
267    "[M+H]+": {
268        "add": {"H": 1},
269        "sub": {},
270        "polarity": "positive",
271    },
272    "[M+2H]2+": {
273        "add": {"H": 2},
274        "sub": {},
275        "polarity": "positive",
276    },
277    "[M+3H]3+": {
278        "add": {"H": 3},
279        "sub": {},
280        "polarity": "positive",
281    },
282    "[M+NH4]+": {
283        "add": {"N": 1, "H": 4},
284        "sub": {},
285        "polarity": "positive",
286    },
287    "[M+Na]+": {
288        "add": {"Na": 1},
289        "sub": {},
290        "polarity": "positive",
291    },
292    "[M+K]+": {
293        "add": {"K": 1},
294        "sub": {},
295        "polarity": "positive",
296    },
297    "[M+2Na]2+": {
298        "add": {"Na": 2},
299        "sub": {},
300        "polarity": "positive",
301    },
302    "[M+H+Na]2+": {
303        "add": {"H": 1, "Na": 1},
304        "sub": {},
305        "polarity": "positive",
306    },
307    "[M+H+K]2+": {
308        "add": {"H": 1, "K": 1},
309        "sub": {},
310        "polarity": "positive",
311    },
312    "[M+2Na+Cl]+": {
313        "add": {"Na": 2, "Cl": 1},
314        "sub": {},
315        "polarity": "positive",
316    },
317    "[M+2Na-H]+": {
318        "add": {"Na": 2},
319        "sub": {"H": 1},
320        "polarity": "positive",
321    },
322    "[M-H+2Na]+": {
323        "add": {"Na": 2},
324        "sub": {"H": 1},
325        "polarity": "positive",
326    },
327    "[M+C2H3Na2O2]+": {
328        "add": {"C": 2, "H": 3, "Na": 2, "O": 2},
329        "sub": {},
330        "polarity": "positive",
331    },
332    "[M+C4H10N3]+": {
333        "add": {"C": 4, "H": 10, "N": 3},
334        "sub": {},
335        "polarity": "positive",
336    },
337    "[M+NH4+ACN]+": {
338        "add": {"C": 2, "H": 7, "N": 2},
339        "sub": {},
340        "polarity": "positive",
341    },
342    "[M+H-H2O]+": {
343        "add": {},
344        "sub": {"H": 1, "O": 1},
345        "polarity": "positive",
346    },
347    "[M+H-2H2O]+": {
348        "add": {},
349        "sub": {"H": 3, "O": 2},
350        "polarity": "positive",
351    },
352    "[M+H-NH3]+": {
353        "add": {},
354        "sub": {"N": 1, "H": 2},
355        "polarity": "positive",
356    },
357    "[M+2H-NH3]2+": {
358        "add": {},
359        "sub": {"N": 1, "H": 1},
360        "polarity": "positive",
361    },
362    "[M+2H-H2O]2+": {
363        "add": {},
364        "sub": {"O": 1},
365        "polarity": "positive",
366    },
367    "[M+NH4-H2O]+": {
368        "add": {"N": 1, "H": 2},
369        "sub": {},
370        "polarity": "positive",
371    },
372    "[M+H+H2O]+": {
373        "add": {"H": 3, "O": 1},
374        "sub": {},
375        "polarity": "positive",
376    },
377    "de-protonated": {
378        "add": {},
379        "sub": {"H": 1},
380        "polarity": "negative",
381    },
382    "[M-H]-": {
383        "add": {},
384        "sub": {"H": 1},
385        "polarity": "negative",
386    },
387    "[M-2H]2-": {
388        "add": {},
389        "sub": {"H": 2},
390        "polarity": "negative",
391    },
392    "[M-H-H2O]-": {
393        "add": {},
394        "sub": {"H": 3, "O": 1},
395        "polarity": "negative",
396    },
397    "[M-H+H2O]-": {
398        "add": {"H": 1, "O": 1},
399        "sub": {},
400        "polarity": "negative",
401    },
402    "[M+Cl]-": {
403        "add": {"Cl": 1},
404        "sub": {},
405        "polarity": "negative",
406    },
407    "[M+HCOO]-": {
408        "add": {"C": 1, "H": 1, "O": 2},
409        "sub": {},
410        "polarity": "negative",
411    },
412    "[M+CH3COO]-": {
413        "add": {"C": 2, "H": 3, "O": 2},
414        "sub": {},
415        "polarity": "negative",
416    },
417    "[M+2NaAc+Cl]-": {
418        "add": {"Na": 2, "C": 2, "H": 3, "O": 2, "Cl": 1},
419        "sub": {},
420        "polarity": "negative",
421    },
422    "[M+K-2H]-": {
423        "add": {"K": 1},
424        "sub": {"H": 2},
425        "polarity": "negative",
426    },
427    "[M+Na-2H]-": {
428        "add": {"Na": 1},
429        "sub": {"H": 2},
430        "polarity": "negative",
431    },
432}
433
434ADDUCT_ALIASES = {
435    "[M+HCOOH-H]-": "[M+HCOO]-",
436    "[M+CH3COOH-H]-": "[M+CH3COO]-",
437    "[M+FA-H]-": "[M+HCOO]-",
438    "[M+AcOH-H]-": "[M+CH3COO]-",
439}