Type:	Package
Title:	Interpreting High Resolution Mass Spectra
Version:	1.4.5
Date:	2024-01-31
Maintainer:	Jan Lisec <jan.lisec@bam.de>
Description:	High resolution mass spectrometry yields often large data sets of spectra from compounds which are not present in available libraries. These spectra need to be annotated and interpreted. 'InterpretMSSpectrum' provides a set of functions to perform such tasks for Electrospray-Ionization and Atmospheric-Pressure-Chemical-Ionization derived data in positive and negative ionization mode.
License:	GPL-3
URL:	https://github.com/janlisec/InterpretMSSpectrum
Depends:	R (≥ 2.10.0)
Imports:	enviPat, plyr
Suggests:	DBI, doParallel, foreach, parallel, Rdisop, RSQLite, testthat (≥ 3.0.0), vdiffr
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2024-01-31 11:57:51 UTC; jlisec
Author:	Jan Lisec [aut, cre], Jaeger Carsten [aut]
Repository:	CRAN
Date/Publication:	2024-01-31 13:10:05 UTC

Default adduct lists used by findMAIN.

Description

Default adduct lists used by findMAIN.

Usage

data(Adducts)

Format

A list of two character vectors:

Positive

default adducts used in ESI(+) mode

Negative

default adducts used in ESI(-) mode

Source

A reasonable selection of frequent adducts based on the list in R-package CAMERA

CountChemicalElements.

Description

CountChemicalElements will split a character (chemical formula) into its elements and count their occurrence.

Usage

CountChemicalElements(x = NULL, ele = NULL)

Arguments

Details

No testing for any chemical alphabet is performed. Elements may occur several times and will be summed up in this case without a warning.

Value

A named numeric with counts for all contained or specified elements.

GenerateMetaboliteSQLiteDB.

Description

GenerateMetaboliteSQLiteDB will set up a SQLite data base containing potential metabolite formulas, their masses and isotopic distribution for use with InterpretMSSpectrum.

Usage

GenerateMetaboliteSQLiteDB(
  dbfile = "SQLite_APCI.db",
  ionization = c("APCI", "ESI")[1],
  mass_range = c(100, 105),
  ncores = 1,
  silent = TRUE
)

Arguments

Details

The process takes a long time for larger masses (>400 Da). Parallel processing with 8 cores is highly recommended. Alternatively pre-processed versions can be downloaded on request to jan.lisec@bam.de. To process a 1 Da range (from 900 to 901) for ESI does take approximately 5 minutes on 8 cores.

Value

Returns the resulting data frame invisible. Will write an SQL_DB if 'dbfile' provides a valid path and file name.

Examples

# using the default values will compute be relatively fast, but for higher masses it 
# is getting much slower
db <- GenerateMetaboliteSQLiteDB(dbfile = NULL)

GetGroupFactor.

Description

GetGroupFactor will split a numeric vector according to a specified gap value. This is often a useful tool and therefore exported to the namespace.

Usage

GetGroupFactor(x, gap)

Arguments

Value

A factor vector of length(x) indicating the different groups in x.

Examples

x <- c(1:3,14:12,6:9)
GetGroupFactor(x=x, gap=2)
split(x, GetGroupFactor(x=x, gap=2))

IMS_parallel.

Description

IMS_parallel is a parallel implementation of InterpretMSSpectrum.

Usage

IMS_parallel(
  spectra = NULL,
  ncores = 8,
  precursor = NULL,
  correct_peak = NULL,
  ...
)

Arguments

Details

For mass processing and testing it may be sufficient to use InterpretMSSpectrum without plotting functionality. However, function is likely to be deprecated or integrated as an option into the main function in the future.

Value

A list of InterpretMSSpectrum result objects which can be systematically evaluated. However, note that plotting is unfortunately not enabled for parallel processing.

See Also

InterpretMSSpectrum

Interpreting High-Res-MS spectra.

Description

InterpretMSSpectrum will read, evaluate and plot a deconvoluted mass spectrum (mass*intensity pairs) from either TMS-derivatized GC-APCI-MS data or ESI+/- data. The main purpose is to identify the causal metabolite or more precisely the sum formula of the molecular peak by annotating and interpreting all visible fragments and isotopes.

Usage

InterpretMSSpectrum(
  spec = NULL,
  precursor = NULL,
  correct_peak = NULL,
  met_db = NULL,
  typical_losses_definition = NULL,
  silent = FALSE,
  dppm = 3,
  param = "APCIpos",
  formula_db = NULL
)

Arguments

Details

For further details refer to and if using please cite Jaeger et al. (2016, <doi:10.1021/acs.analchem.6b02743>) in case of GC-APCI and Jaeger et al. (2017, <doi:10.1002/rcm.7905>) for ESI data. The Interpretation is extremely speed up if 'formula_db' (a predetermined database of potential sum formulas) is provided within the function call. Within the package you may use GenerateMetaboliteSQLiteDB to prepare one for yourself or request a download link from jan.lisec@bam.de as de-novo calculation for a wide mass range may take several days.

Value

An annotated plot of the mass spectrum and detailed information within the console. Main result, list of final candidate formulas and their putative fragments, will be returned invisibly.

Examples

# load APCI test data
apci_spectrum <- InterpretMSSpectrum::apci_spectrum

# (otional) provide information of a correct peak as a character containing
# name, formula and ion mass -- separated by ',' as shown below
cp <- "Glutamic acid (3TMS), C14H33NO4Si3, 364.1790"

# (otional) provide a database of known peaks
mdb <- data.frame(
  "Name" = c("Glutamic acid (3TMS)", "other peak with same sum formula"),
  "Formula" = c("C14H33NO4Si3", "C14H33NO4Si3"),
  "M+H" = c(364.179, 364.179), stringsAsFactors = FALSE, check.names = FALSE
)

# (otional) provide a database of precalculated formulas to speed up the process
fdb <- system.file("extdata", "APCI_min.db", package = "InterpretMSSpectrum")

# apply function providing above arguments which will print to the console
# and open a new plot
InterpretMSSpectrum(spec = apci_spectrum, correct_peak = cp, met_db = mdb, formula_db = fdb)

InterpretTP.

Description

InterpretTP is a wrapper function around InterpretMSSpectrum which will read, evaluate and plot a deconvoluted mass spectrum (mass*intensity pairs) from either TMS-derivatized GC-APCI-MS data or ESI+/- data. It allows to provide a chemical formula as a potential precursor of the spectrum. This formula will be used to set the parameters 'allowed_elements' and 'maxElements' during de-novo formula generation.

Usage

InterpretTP(fml = NULL, param = "APCIpos", ...)

Arguments

Details

For further details refer to InterpretMSSpectrum.

Value

An annotated plot of the mass spectrum and detailed information within the console. Main result, list of final candidate formulas and their putative fragments, will be returned invisibly.

Examples

# load test data
utils::data(apci_spectrum)

# provide information of a correct peak (if you know) as character
cp <- "Glutamic acid (3TMS), C14H33NO4Si3, 364.1790"

# provide database of known peaks and correct peak
mdb <- data.frame(
  "Name" = c("Glutamic acid (3TMS)", "other peak with same sum formula"),
  "Formula" = c("C14H33NO4Si3", "C14H33NO4Si3"),
  "M+H" = c(364.179, 364.179), stringsAsFactors = FALSE, check.names = FALSE
)

# provide a database of precalculated formulas to speed up the process
fdb <- system.file("extdata", "APCI_min.db", package = "InterpretMSSpectrum")

# apply function providing above arguments (dppm is set to 0.5 to reduce run time)
InterpretTP(fml = "C14H33NO4Si3", spec=apci_spectrum, param="APCIpos")

Orbitrap spectra

Description

A set of 550 MS1 pseudo-spectra of metabolite standards, acquired on an Orbitrap-type mass analyzer (Q Exactive, Thermo-Fisher) in electrospray ionization (ESI) positive mode. Spectra were generated from Thermo raw files using xcms/CAMERA.

Usage

data(OrbiMS1)

Format

A list with 550 matrices (spectra). Two attributes are attached to each spectrum:

Formula

sum formula of (neutral) compound

ExactMass

exact mass of (neutral) compound

Plot Mass Spectrum.

Description

PlotSpec will read, evaluate and plot a deconvoluted mass spectrum (mass*intensity pairs) from TMS-derivatized GC-APCI-MS data. The main purpose is to visualize the relation between deconvoluted masses.

Usage

PlotSpec(
  x = NULL,
  masslab = 0.1,
  rellab = FALSE,
  cutoff = 0.01,
  cols = NULL,
  txt = NULL,
  mz_prec = 4,
  ionization = NULL,
  neutral_losses = NULL,
  neutral_loss_cutoff = NULL,
  substitutions = NULL,
  precursor = NULL,
  xlim = NULL,
  ylim = NULL
)

Arguments

Value

An annotated plot of the mass spectrum.

Examples

#load test data and apply function
utils::data(apci_spectrum, package = "InterpretMSSpectrum")
PlotSpec(x=apci_spectrum, ionization="APCI")

# normalize test data by intensity
s <- apci_spectrum
s[,2] <- s[,2]/max(s[,2])
PlotSpec(x=s)

# use relative labelling
PlotSpec(x=s, rellab=364.1789)

# avoid annotation of masses and fragments
PlotSpec(x=s, masslab=NULL, neutral_losses=NA)

# provide individual neutral loss set
tmp <- data.frame("Name"=c("Loss1","Loss2"),"Formula"=c("",""),"Mass"=c(90.05,27.995))
PlotSpec(x=s, neutral_losses=tmp)

# provide additional color and annotation information per peak
PlotSpec(x=s, cols=1+(s[,2]>0.1), txt=data.frame("x"=s[s[,2]>0.1,1],"txt"="txt"))

# annotate a sum formula
PlotSpec(x=s, txt=data.frame("x"=s[which.max(s[,2]),1],"txt"="C[6]~H[12]~O[6]","expr"=TRUE))

# simulate a Sodium adduct to the spectrum (and annotate using substitutions)
p <- which.max(s[,2])
s <- rbind(s, c(21.98194+s[p,1], 0.6*s[p,2]))
PlotSpec(x=s, substitutions=matrix(c("H","Na"),ncol=2,byrow=TRUE))

#load ESI test data and apply function
utils::data(esi_spectrum)
PlotSpec(x=esi_spectrum, ionization="ESI")

ReadSpecClipboard.

Description

Read a mass spectrum from the windows clipboard.

Usage

ReadSpecClipboard(con = "clipboard")

Arguments

Value

A spectrum as two-column matrix.

Examples

## Not run: 
  if (length(grep("Windows", utils::sessionInfo()$running))==1) {
    x <- InterpretMSSpectrum::apci_spectrum
    write.table(x, "clipboard", sep="\t", row.names=FALSE)
    InterpretMSSpectrum::ReadSpecClipboard()
  }

## End(Not run)

APCI spectrum

Description

Example spectrum of Glutamic acid (3TMS) measured on a Bruker impact II.

Usage

data(apci_spectrum)

Format

A data frame with 47 observations on the following 2 variables:

mz

a numeric vector ion masses

int

a numeric vector of intensities

List of chemical elements.

Description

List of chemical elements.

Usage

data(chemical_elements)

Format

A data frame with 103 observations on the following 2 variables:

name

a character vector of elemental abbreviations

mass

a numeric vector of exact masses of the elements main isotope

ESI spectrum

Description

Example spectrum of Sedoheptulose 7-phosphate measured on a Bruker impact II.

Usage

data(esi_spectrum)

Format

A data frame with 42 observations on the following 2 variables:

mz

a numeric vector ion masses

int

a numeric vector of intensities

findMAIN.

Description

findMAIN will evaluate an ESI spectrum for the potential main adducts, rank obtained suggestions and allow the deduction of the neutral mass of the measured molecule.

Usage

findMAIN(
  spec,
  adductmz = NULL,
  ionmode = c("positive", "negative")[1],
  adducthyp = NULL,
  ms2spec = NULL,
  rules = NULL,
  mzabs = 0.01,
  ppm = 5,
  mainpkthr = 0.005,
  collapseResults = TRUE
)

## S3 method for class 'findMAIN'
plot(x, rank = 1, correct_mass = NULL, ...)

## S3 method for class 'findMAIN'
print(x, ...)

Arguments

Details

Electrospray ionization (ESI) mass spectra frequently contain a number of different adduct ions, multimers and in-source fragments [M+H]+, [M+Na]+, [2M+H]+, [M+H-H2O]+, making it difficult to decide on the compound's neutral mass. This functions aims at determining the main adduct ion and its type (protonated, sodiated etc.) of a spectrum, allowing subsequent database searches e.g. using MS-FINDER, SIRIUS or similar.

Value

A list-like 'findMAIN' object for which 'print', 'summary' and 'plot' methods are available. Each list element represents a potential spectra annotation, ranked according to a combined score. The spectrum is annotated with columns indicating the determined isotopic groups (isogr) and their likely charge. Further, information on the potential set of adducts and their ppm error is attached. The score aims to integrate all this information using formula S=sum(w_i x s_i). In short, we sum up i weighted score components (currently i=4). Currently these components are calculated based on the explained intensity (adduct sets which annotate a higher amount of the total spectrum intensity are better), the mass error (adduct sets with lower mass error are better), the support by isotopic peaks (adduct sets with fitting isotopes are better) and the number of adducts (adduct sets with a larger number of adducts are better). The individual scores for each adduct set are attached as an attribute to the respective list element and can be easily observed by applying the 'summary' or the 'plot' function on the 'findMAIN' object.

References

Jaeger C, Meret M, Schmitt CA, Lisec J (2017), <doi:10.1002/rcm.7905>.

Examples

utils::data(esi_spectrum, package = "InterpretMSSpectrum")
fmr <- InterpretMSSpectrum::findMAIN(esi_spectrum)
plot(fmr)
head(summary(fmr))
InterpretMSSpectrum::InterpretMSSpectrum(fmr[[1]], precursor=263, param="ESIpos")
fmr <- InterpretMSSpectrum::findMAIN(esi_spectrum[6:9,], adducthyp = "[M+H]+")
plot(fmr)

# set up a spectrum containing a double charged peak
spec <- data.frame(mz = c(372.1894, 372.6907, 373.1931, 380), int = c(100, 40, 8, 2))
InterpretMSSpectrum:::findiso(spec)
# allow a double charged adduct hypothesis (not standard)
fmr <- InterpretMSSpectrum::findMAIN(spec, adducthyp = c("[M+H]+", "[M+2H]2+"))
summary(fmr)
attr(fmr[[1]],"scores")
plot(fmr, rank = 1:4)
plot(fmr, rank = 2)

# add the correct M+H to this spectrum as a minor peak
spec <- rbind(spec, c(742.3648+1.007, 10))
(fmr <- InterpretMSSpectrum::findMAIN(spec, adducthyp = c("[M+H]+", "[M+2H]2+")))
summary(fmr)
plot(fmr, rank = 1)
plot(fmr, rank = 2)

# compare specific hypotheses manually
# get correct result
InterpretMSSpectrum::findMAIN(spec, adductmz = 743.3718, adducthyp = "[M+H]+")
# enforce wrong result
InterpretMSSpectrum::findMAIN(spec, adductmz = 743.3718, adducthyp = "[M+2H]2+")

get_exactmass.

Description

Get the exact mass for chemical formulas.

Usage

get_exactmass(x)

Arguments

Value

A named vector of exact masses.

Examples

InterpretMSSpectrum::get_exactmass(c("C6H12O6", "Na", "H1"))

mScore.

Description

mScore will calculate a mass defect weighted score for an mz/int values measure for an isotopic cluster in comparison to the theoretically expected pattern.

Usage

mScore(
  obs = NULL,
  the = NULL,
  dabs = 5e-04,
  dppm = 2,
  int_prec = 0.02,
  limit = 0,
  rnd_prec = 0
)

Arguments

Details

The maximum expected average mass error should be specified in ppm. A observed pattern deviating that much from the theoretical pattern would still receive a reasonable (average) mScore while observations deviating stronger or less strong will reach lower or higher mScores respectively. Likewise the intensity precision should specify the average quality of your device to maintain stable isotopic ratios.

Value

Scalar mScore giving the quality of the observed data if theoretical data are true.

Examples

# get theoretical isotopic pattern of Glucose
glc <- c(180.063388, 0.920845, 181.066845, 0.065214, 182.068041, 0.013043)
glc <- matrix(glc, nrow=2)
mScore(obs=glc, the=glc)
# modify pattern by maximum allowable error (2ppm mass error, 2% int error)
glc_theoretic <- glc
glc[1,] <- glc[1,]+2*glc[1,]/10^6
glc[2,1:2] <- c(-0.02,0.02)+glc[2,1:2]
mScore(obs=glc, the=glc_theoretic)

# simulate mass and int defects
ef <- function(x, e) {runif(1,x-x*e,x+x*e)}
glc_obs <- glc
glc_obs[1,] <- sapply(glc[1,], ef, e=2*10^-6)
glc_obs[2,] <- sapply(glc[2,], ef, e=0.02)
mScore(obs=glc_obs, the=glc)
# simulate mass and int defects systematically
ef <- function(x, e) {runif(1,x-x*e,x+x*e)}
n <- 11
mz_err <- round(seq(0,5,length.out=n),3)
int_err <- round(seq(0,0.1,length.out=n),3)
mat <- matrix(NA, ncol=n, nrow=n, dimnames=list(mz_err, 100*int_err))
glc_obs <- glc
for (i in 1:n) {
 glc_obs[1,] <- sapply(glc[1,], ef, e=mz_err[i]*10^-6)
 for (j in 1:n) {
   glc_obs[2,] <- sapply(glc[2,], ef, e=int_err[j])
   mat[i,j] <- mScore(obs=glc_obs, the=glc)
 }
}
plot(x=1:n, y=1:n, type="n",axes=FALSE, xlab="mass error [ppm]", ylab="isoratio error [%]")
axis(3,at=1:n,rownames(mat),las=2); axis(4,at=1:n,colnames(mat),las=2); box()
cols <- grDevices::colorRampPalette(colors=c(2,6,3))(diff(range(mat))+1)
cols <- cols[mat-min(mat)+1]
text(x=rep(1:n,each=n), y=rep(1:n,times=n), labels=as.vector(mat), col=cols)

A data table defining typical neutral losses in GC-APCI-MS for silylated compounds.

Description

A data table defining typical neutral losses in GC-APCI-MS for silylated compounds.

Usage

data(neutral_losses_ESI)

Format

A data frame with 22 observations on the following 3 variables:

Name

a character vector containing the fragment name used for plot annnotation

Formula

a character vector containing chemical formulas

Mass

a numeric vector containing the mass according to Formula

Details

The data frame consists of two character columns ('Name' and 'Formula') and the numeric column 'Mass'. In a mass spectrum peak pairs are analyzed for mass differences similar to the ones defined in neutral_losses. If such a mass difference is observed, we can assume that the according 'Formula' is the true neutral loss observed in this spectrum. In a plot this peak pair would be connected by a grey line and annotated with the information from 'Name'. In formula evaluation this peak pair would be used to limit formula suggestions with respect to plausibility, i.e. if mass fragments A and B exist with mass difference 16.0313 than we can assume that the respective sum formulas have to be different by CH4. In consequence we can exclude sum formula suggestions for B which do not have a valid corresponding sum formula in A and vice versa.

Source

This list has been put together manually by Jan Lisec analyzing multiple GC-APCI-MS data sets.

A data table defining neutral losses in LC-ESI-MS (positive mode).

Description

A data table defining neutral losses in LC-ESI-MS (positive mode).

Usage

data(neutral_losses_ESI)

Format

A data frame with 45 observations on the following 3 variables:

Name

a character vector containing the fragment name used for plot annnotation

Formula

a character vector containing chemical formulas

Mass

a numeric vector containing the mass according to Formula

Details

The data frame consists of two character columns ('Name' and 'Formula') and the numeric column 'Mass'. In a mass spectrum peak pairs are analyzed for mass differences similar to the ones defined in neutral_losses. If such a mass difference is observed, we can assume that the according 'Formula' is the true neutral loss observed in this spectrum. In a plot this peak pair would be connected by a grey line and annotated with the information from 'Name'. In formula evaluation this peak pair would be used to limit formula suggestions with respect to plausibility, i.e. if mass fragments A and B exist with mass difference 16.0313 than we can assume that the respective sum formulas have to be different by CH4. In consequence we can exclude sum formula suggestions for B which do not have a valid corresponding sum formula in A and vice versa.

Source

This list has been put together manually by Jan Lisec analyzing multiple LC-ESI-MS (positive mode) data sets.

Default parameter list for InterpretMSSpectrum.

Description

Default parameter list for InterpretMSSpectrum.

Usage

data(param.default)

Format

A data frame with 22 observations on the following 3 variables:

ionization

ESI or APCI – will influence expected peak width and precision as well as adducts.

ionmode

positive or negative – will influence expected adducts.

allowed_elements

Passed to Rdisop in formula generation.

maxElements

Passed to Rdisop in formula generation.

minElements

Passed to Rdisop in formula generation.

substitutions

Will be deprecated in the future.

quick_isos

TRUE = via Rdisop, FALSE = via enviPat (often more correct)

score_cutoff

Specifies initial filtering step threshold per fragment. Sum Formulas with score_i < score_cutoff*max(score) will be removed.

neutral_loss_cutoff

Specifies the allowed deviation in mDa for neutral losses to be accepted from the provided neutral loss list.

Details

Default parameter list used by InterpretMSSpectrum, serving also as a template for custom lists. Basically every option which needs to be modified rarely went in here. Specific parameter set modifications (i.e. for 'APCIpos') are provided and can be called using the character string as a shortcut. Alternatively, a named list can be provided where all contained parameters will receive the new specified values.

Exporting spectra to MSFinder.

Description

Send spectrum to MSFinder.

Usage

sendToMSF(x, ...)

## Default S3 method:
sendToMSF(
  x,
  precursormz,
  precursortype = "[M+H]+",
  outfile = NULL,
  MSFexe = NULL,
  ...
)

## S3 method for class 'findMAIN'
sendToMSF(x, rank = 1, ms2spec = NULL, outfile = NULL, MSFexe = NULL, ...)

Arguments

Details

In the default case 'x' can be a matrix or data frame, where the first two columns are assumed to contain the 'mz' and 'intensity' values, respectively. Further arguments 'precursormz' and 'precursortype' are required in this case. Otherwise 'x' can be of class findMAIN.

Value

Full path of generated MAT file (invisibly).

References

H.Tsugawa et al (2016) Hydrogen rearrangement rules: computational MS/MS fragmentation and structure elucidation using MS-FINDER software. Analytical Chemistry, 88, 7946-7958

Examples

## Not run: 
utils::data(esi_spectrum, package = "InterpretMSSpectrum")
fmr <- findMAIN(esi_spectrum)
sendToMSF(fmr, outfile="tmp.mat")
sendToMSF(fmr, outfile="tmp.mat", rank=1:3)

## End(Not run)

writeMSF.

Description

Write a spectrum file in MSFinder format.

Usage

writeMSF(x, ...)

## Default S3 method:
writeMSF(
  x,
  precursormz,
  precursortype = "[M+H]+",
  name = "unknown",
  ionmode = "Positive",
  ms1spec = NULL,
  retentiontime = NULL,
  outfile = NULL,
  ...
)

## S3 method for class 'findMAIN'
writeMSF(x, rank = 1, ms2spec = NULL, outfile = NULL, ...)

Arguments

Details

In the default case 'x' can be a matrix or data frame, where the first two columns are assumed to contain the 'mz' and 'intensity' values, respectively. Further arguments 'precursormz' and 'precursortype' are required in this case. Otherwise 'x' can be of class findMAIN.

Value

Write spectrum to MAT file for evaluation in MSFinder