Package {Spec2Annot}

Spec2Annot: Annotation of Mass Spectra

Description

Provides a comprehensive suite of functions to efficiently annotate mass spectra data. Motivated by the need for rapid and accurate chemical identification in high-resolution mass spectrometry, it integrates built-in chemical databases and high-performance C++ algorithms. Users can perform mass-to-charge (m/Z) and retention time searches, determine elemental compositions of molecules using heuristic rules, including specific isotopes, and annotate MS2 spectra with structural metrics using configurable chemistry rules.

Author(s)

Maintainer: Sylvain Dechaumet sylvain.dechaumet@cea.fr

Authors:

• Sylvain Dechaumet sylvain.dechaumet@cea.fr

Other contributors:

• Etienne Thevenot etienne.thevenot@cea.fr [contributor]

• Eric Venot eric.venot@cea.fr [reviewer]

• Annelaure Damont annelaure.damont@cea.fr [contributor]

• Anaïs Legrand anais.legrand@cea.fr [contributor]

See Also

Useful links:

• https://github.com/odisce/Spec2Annot

• Report bugs at https://github.com/odisce/Spec2Annot/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

adduct data

Description

adduct data

Usage

Adduct_db

Format

A data.table with the common adducts in LC-ESI-MS

adduct

Formula

charge

charge

mz_query

Exact mass value

Cross join of two data.table

Description

Cross join of two data.table

Usage

CJ1(DT1, DT2)

Arguments

Value

A data.table corresponding to the cross join of the two tables.

Examples

require(data.table)
CJ1(
 data.table(A = 1:10, B = "A"),
 data.table(
   C = 50:100,
   D = rep(c("C", "D", "E", "F"), length.out = 51)
 )
)

Periodic table as a data.table

Description

Periodic table as a data.table

Usage

Element

Format

A data.table with the Periodic Table Elements fields

atomic_nb

Atomic number

atomic_symb

Atomic symbol

mass_nb

Mass number

atomic_mass

Exact atomic mass

isotopic_compo

Relative isotopic abundance

References

https://physics.nist.gov/cgi-bin/Compositions/stand_alone.pl?ele=&ascii=ascii2&isotype=some

isotopes data

Description

isotopes data

Usage

Isotopes_db

Format

A data.table with the common isotopes found in LC-ESI-MS

isotope

Isotope formula

mass

Exact mass

abundance

Natural abundance (in percent)

mass_diff

Exact mass difference from non-isotopic element

losses data

Description

losses data

Usage

Losses_db

Format

A data.table with the common losses found in LC-ESI-MS

loss

loss formula

mz_query

Exact mass

encod

Character encoding

Add formula to annotate_mz()

Description

Add formula to annotate_mz()

Usage

add_formula_to_annot(mzannot_dt)

Arguments

Value

Return the mzannot_dt table with a new formula column containing a string with the elemental composition.

Convert annotation to html string

Description

Convert annotation to html string

Usage

annot_to_html(annotation, compo = "", compo_replace = "X")

Arguments

Value

An html string of the annotation.

Examples

annot_to_html("[M+H]+_13C2", "C6H12O2", "M")
annot_to_html("[M+H-H2O]+_13C2", "C6H12O2", "M")
annot_to_html("[M+H-H2O]+_13C2_18O", "C6H12O2", "M")
annot_to_html("C6H13O2-H2O+_13C2_18O", "", "M")
annot_to_html("[M+H-(OH•)]+_13C2_18O", "C6H12O2", "M")

Annotate a mass spectrum

Description

This function annotate a full mass spectrum using a full brute force search optionnaly restricted by an elemental composition compo. Since generating the space to research can take some times, the parameter search_space can be pre-calculated in advance.

Usage

annotate_mz(
  input_spectrum,
  ppm = 5,
  polarity = NULL,
  compo = NULL,
  use_golden_ratio = TRUE
)

Arguments

Value

Return a data.table with the annotated spectrum.

Examples

annotate_mz(spectra_ms2, ppm = 3, polarity = 1, compo = "C10H12N5O6P1")

Annotate a matrix and return network edges

Description

This function returns edges of networked ions

Usage

annotate_spectra(mass, debugL = FALSE)

Arguments

Value

Return a numeric vector of network edges

Group m/Z from a vector based on tolerance

Description

This function returns a matrix with m/Z groups based on a tolerance.

Usage

brute_force_const(
  mass = 120,
  ppm = 5,
  mass_vc = 0L,
  maxiter_vc_ = NULL,
  name_vc = 0L,
  debugl = 0L,
  debugit = 0L
)

Arguments

Value

A NumericMatrix containing the count of elements, exact mass mass, ppm deviation and iteration number of solutions found by the brute force algorithm.

Mono charged ions

Description

Mono charged ions

Usage

db_monocharge

Format

A data.table with the common charges in LC-ESI-MS

Formula

Formula

charge

charge

lossL

Does the resulting ion can produce in-source losses ?

mz_query

Exact mass value

Return the mass of an electorn

Description

Return the mass of an electorn

Usage

electron_mass()

Value

Return the mass of an electron as a numeric value

Examples

electron_mass()

Get element count from formula

Description

Get element count from formula

Usage

element_from_formula(formula)

Arguments

Value

Return a data.table with element count

Examples

# Exempl A
formula <- gen_formula_from_compo("C6H2O3Ca2K1")
element_from_formula(formula)

# Exempl B
formula <- gen_formula_from_compo("[C6H12O2+H]+_13C2")
element_from_formula(formula)

Find composition from mass

Description

Find composition from mass

Usage

find_compo_from_mass(
  mass_target,
  ppm = 5,
  use_golden_ratio = TRUE,
  elements_vc = NULL,
  debugl = 0
)

Arguments

Value

A data.table with one proposition by line with it's elemental composition, the theoretical mass and the mass deviation with the query in ppm.

Examples

  find_compo_from_mass(125.215, ppm = 10)
  find_compo_from_mass(528.125, ppm = 3)
  find_compo_from_mass(89.0476, ppm = 3, elements_vc = "C3H7NO2")

Calculate the ions database

Description

Calculate the ions database

Usage

fun_generate_ions_from_mz(
  mass = 252.2534,
  losses = Spec2Annot::Losses_db,
  db_iso = Spec2Annot::Isotopes_db,
  charges = Spec2Annot::db_monocharge,
  adducts = Spec2Annot::Adduct_db,
  polarity = NULL
)

Arguments

Value

A data.table containing the full list of possible ions with the formula to calculate them

Examples

fun_get_ion_list()

Calculate the ions database

Description

Calculate the ions database

Usage

fun_get_ion_list(
  losses = Spec2Annot::Losses_db,
  charges = Spec2Annot::db_monocharge,
  adducts = Spec2Annot::Adduct_db,
  polarity = NULL
)

Arguments

Value

A data.table containing the full list of possible ions with the formula to calculate them

Examples

fun_get_ion_list()

Generate adduct list from mz

Description

Generate adduct list from mz

Usage

gen_adduct(
  mz,
  label = NULL,
  mz_type = c("neutral", "pos", "neg")[[1]],
  adduct_db = Spec2Annot::Adduct_db
)

Arguments

Value

A data.table with adducts mass and labels.

Examples

gen_adduct(125.53658, "Isovalerine", "neutral")
gen_adduct(116.0837, "C6H12O2", "neutral")
gen_adduct(116.0837, "C6H12O2", "pos")

Generate formula from composition

Description

Generate formula from composition

Usage

gen_formula_from_compo(compo)

Arguments

Value

Return a string with an arithmetic formula used to calculate the final mass. This function can be used to check if the string parser behave correctly.

Examples

gen_formula_from_compo("C6H2O3NH4")
gen_formula_from_compo("-(C6H2O)-(H2O)")
gen_formula_from_compo("-C6H2O-H2O+Ca2-")
gen_formula_from_compo("[C6H12O2+H-H2O]+_13C")
gen_formula_from_compo("[2(C6H2O3)+NH4]+_13C3")
gen_formula_from_compo("[C6H12O2+H-H2O]++")
gen_formula_from_compo("[C6H12O2+H-H2O]--_13C1")

Calculate list of targetd ions from neutral mz

Description

Calculate list of targetd ions from neutral mz

Usage

gen_ionlist(
  neutral_mz = 153.5125,
  polarity = c(0, 1)[1],
  iso = c(TRUE, FALSE)[1],
  multi = 0,
  losses = c(TRUE, FALSE)[1],
  adducts = c(TRUE, FALSE)[1],
  mono_db = Spec2Annot::db_monocharge,
  loss_db = Spec2Annot::Losses_db,
  adduct_db = Spec2Annot::Adduct_db,
  db_iso = Spec2Annot::Isotopes_db
)

Arguments

Value

a data.table

Examples

gen_ionlist(153.5125, 1, TRUE, 2, TRUE, TRUE)

Function to generate isotopes from an exact mass

Description

Function to generate isotopes from an exact mass

Usage

gen_isotopes(mz, label = NULL, db_iso = Spec2Annot::Isotopes_db)

Arguments

Value

Generate a data.table with isotopes mass and label based on the mz value. By default, the isotopes are chosen from Spec2Annot::Isotopes_db but it could be specified by the user.

Examples

gen_isotopes(125.53658, "Isovalerine")

Generate losses list from mz

Description

Generate losses list from mz

Usage

gen_losses(
  mz,
  label = NULL,
  mz_type = c("neutral", "pos", "neg")[[1]],
  loss_db = Spec2Annot::Losses_db
)

Arguments

Value

A data.table with losses mass and labels.

Examples

gen_losses(125.53658, "Isovalerine", "neutral")
gen_losses(116.0837, "C6H12O2", "neutral")
gen_losses(116.0837, "C6H12O2", "pos")

Function to generate monocharges from an exact mass

Description

Function to generate monocharges from an exact mass

Usage

gen_monocharge(
  mz,
  label = NULL,
  mz_type = c("neutral", "pos", "neg")[[1]],
  ion_mode = c("pos", "neg")[[1]],
  mono_db = Spec2Annot::db_monocharge
)

Arguments

Value

A data.table with ID, label and mz_query

Examples

gen_monocharge(125.53658, "Isovalerine", "neutral", "neg")
gen_monocharge(116.0837, "C6H12O2", "neutral", "neg")
gen_monocharge(116.0837, "C6H12O2", "neutral", "pos")

Get charge from composition

Description

Get charge from composition

Usage

get_charge_from_compo(compo)

Arguments

Value

Return the number of positive or negative charge

Examples

get_charge_from_compo("C6H2O3NH4")
get_charge_from_compo("C6H2O3NH4+")
get_charge_from_compo("C6H2O3NH4++")
get_charge_from_compo("C6H2O3NH4-")
get_charge_from_compo("C6H2O3NH4---")
get_charge_from_compo("[C6H12O2+H-H2O]+_13C")
get_charge_from_compo("[2(C6H2O3)+NH4]++_13C3")
get_charge_from_compo("[2(C6H2O3)-NH4]--_13C3_15N1")

Calculate DBE from an elemental composition

Description

Calculation is performed as explained in http://ms-textbook.com/chapter-6/answer-6-3/

Usage

get_dbe(element_dt)

Arguments

Value

Return a string from an element table

Examples

get_dbe("C32H25N3O2S")

Get Element from a mass

Description

Get Element from a mass

Usage

get_element_from_mass(mass, use_golden_ratio = FALSE)

Arguments

Value

Return a string with the number maximum number of each element to expect from the mass. get_element_from_mass(125.2535, FALSE) get_element_from_mass(125.2535, TRUE)

Get isotopes from annotation

Description

Get isotopes from annotation

Usage

get_iso_from_annot(annotation)

Arguments

Value

Return a data.table with the following isotopes informations:

• element: element type (13C, 18O, ...)

• text: label to use for the element

• elmt_nb: Element count

• isotope: Isotope number (13, 18, ...)

• mass: Mass of the isotope

• ID: Unique identifier (integer)

Examples

get_iso_from_annot("[M+H]+_13C_18O")
get_iso_from_annot("[M+H]+_13C2")

Check Nitrogen rule

Description

Calculation is performed as explained in https://en.wikipedia.org/wiki/Nitrogen_rule

Usage

get_nrule(n, mass)

Arguments

Value

A logical corresponding to TRUE if the N rule is respected or FALSE if not.

Examples

get_nrule(5, 125.1235)

Get index in range

Description

Get index in range

Usage

get_range(input, valA, valB)

Arguments

Value

An integer vector of closest indexes found

Check Senior theorems

Description

Check the Senior theorems as described in Morikawa and Newbold (2003) with the following: i) the sum of valencies is an even number, or the total number of atoms having odd valencies is even. ii) the sum of valencies is greater than or equal to twice the maximum valency. iii) the sum of valencies is greater than or equal to twice the number of atoms minus 1.

Usage

get_senior(element_dt, global = TRUE)

Arguments

Value

If global is set to TRUE, return a unique logical value corresponding to TRUE if all the theorems pass or FALSE if any of them isn't. If global is set to FALSE, return a named logical vector with the result of each theorem.

References

1. Senior JK (1951) Partitions and Their Representative Graphs. Am J Math 73:663. doi: 10.2307/2372318

2. Morikawa T, Newbold BT (2003) Analogous odd-even parities in mathematics and chemistry. Chemistry 12:445–450

Examples

get_senior("C6H12O3")

ions data

Description

ions data

Usage

ions_database

Format

A data.table with the common ions found in LC-ESI-MS

Attribution

Encoded formula

exact_mass

Exact mass formula as a character string

charge

charge

Type

Molecular form (Monocharge, Loss, Adduct, ...)

Match two table

Description

This function match two table, searching every entries in B which are contained in A mz +- ppmtol and A.rt +- rttol

Usage

match_tables(db_dt, exp_dt, ppmtol, rttol, debugL = FALSE)

Arguments

Value

A data.frame with matched entries between db_dt and exp_dt.

Calculate ion mass using form

Description

Calculate ion mass using form

Usage

mz_calc_ion(mass, form = "-H")

Arguments

Value

A numeric value corresponding to the mass form.

Examples

mz_calc_ion(142.5236, "-H")

Calculate mz from a string with signs

Description

Calculate mz from a string with signs

Usage

mz_from_string(string)

Arguments

Value

Return a numeric value corresponding to the mass of the string input

Examples

mz_from_string("C6H5O3+")
mz_from_string("C6H5O3++")
mz_from_string("[C6H4O3+H]+_13C1")
mz_from_string("[C6H4O3+H]+_13C2")

Get mass deviation in ppm

Description

This function returns a numeric value corresponding to the mass deviation between massa and massb in ppm.

Usage

mz_ppm(massa = 120.1253, massb = 120.1263)

Arguments

Value

ppm as a numeric value between massa and massb.

Get mass range with ppm

Description

Get mass range with ppm

Usage

mz_range(mass = 120.1253, ppm = 10)

Arguments

Value

A ⁠numeric vector⁠ with the mass window.

Group m/Z from a vector based on tolerance

Description

This function returns a matrix with m/Z groups based on a tolerance.

Usage

mz_vec_aggregate(xx, tt)

Arguments

Value

A ⁠numeric vector⁠ with group indexes

Search DB egaint EXP

Description

Search DB egaint EXP

Usage

search_db(db_dt, exp_dt, ppmtol = 5, rttol = 5)

Arguments

Value

Return the exp_dt data.table entries matching the criteria with 2 new columns: dbid (ids in db_dt) and expid (ids in exp_dt).

Search DB egaint EXP using cpp function

Description

Search DB egaint EXP using cpp function

Usage

search_db_cpp(in_db, in_exp, ppmtol = 5, rttol = 5)

Arguments

Value

Return the exp_dt data.table entries matching the criteria with 2 new columns: dbid (ids in db_dt) and expid (ids in exp_dt).

Spectra example

Description

Spectra example

Usage

spectra_full

Format

A data.table with a centroided MS spectra used as example

mz

m/Z value

intensity

Measured intensity

ID

Unique identifier

Spectra example

Description

MS2 spectrum of C10H12N5O6P1 Precursor mass: 330.0597 Mode: ESI + Collision mode: HCD Energy: 30

Usage

spectra_ms2

Format

A data.table with a centroided MS2 spectra used as example

mz

m/Z value

i

Measured intensity

Return a string from an element table

Description

Return a string from an element table

Usage

string_from_element(element_dt)

Arguments

Value

Return a string from an element table

Examples

"C6H12O3" %>%
  gen_formula_from_compo() %>%
  element_from_formula() %>%
  string_from_element()

Valence data

Description

Valence data

Usage

valence_db

Format

A data.table with element valence

atomic_symb

Atomic symbol

valence

valence value