spectralMatching: Spectral matching for LC-MS/MS datasets

In Viant-Metabolomics/msPurity: Automated Evaluation of Precursor Ion Purity for Mass Spectrometry Based Fragmentation in Metabolomics

Spectral matching for LC-MS/MS datasets

Description

General

Perform spectral matching to spectral libraries for an LC-MS/MS dataset.

The spectral matching is performed from a Query SQLite spectral-database against a Library SQLite spectral-database.

The SQLite schema of the spectral database can be detailed Schema details can be found here.

The query spectral-database in most cases should contain be the "unknown" spectra database generated the msPurity function createDatabase as part of a msPurity-XCMS data processing workflow.

The library spectral-database in most cases should contain the "known" spectra from either public or user generated resources. The library SQLite database by default contains data from MoNA including Massbank, HMDB, LipidBlast and GNPS. A larger database can be downloaded from here. To create a user generated library SQLite database the following tool can be used to generate a SQLite database from a collection of MSP files: msp2db. It should be noted though, that as long as the schema of the spectral-database is as described here , then any database can be used for either the library or query - even allowing for the same database to be used.

The spectral matching functionality has four main components, spectral filtering, spectral alignment, spectral matching, and summarising the results.

Spectral filtering is simply filtering both the library and query spectra to be search against (e.g. choosing the library source, instrument, retention time, precursor PPM tolerance etc).

The spectral alignment stage involves aligning the query peaks to the library peaks. The approach used is similar to modified pMatch algorithm described in Zhou et al 2015.

The spectral matching of the aligned spectra is performed against a combined intensity and m/z weighted vector - created for both the query and library spectra (wq and wl). See below:

w=intensity^x * mz^y

Where x and y represent weight factors, defaults to x=0.5 and y=2 as per MassBank. These can be adjusted by the user though.

The aligned weighted vectors are then matched using dot product cosine, reverse dot product cosine and the composite dot product. See below for dot product cosine equation.

dpc = wq * wl / \sqrt{\sum wq^2} * \sqrt{\sum wl^2}

See the vigenttes for more details regarding matching algorithms used.

Example LC-MS/MS processing workflow

• Purity assessments

  • (mzML files) -> purityA -> (pa)

• XCMS processing

  • (mzML files) -> xcms.findChromPeaks -> (optionally) xcms.adjustRtime -> xcms.groupChromPeaks -> (xcmsObj)

  • — Older versions of XCMS — (mzML files) -> xcms.xcmsSet -> xcms.group -> xcms.retcor -> xcms.group -> (xcmsObj)

• Fragmentation processing

  • (xcmsObj, pa) -> frag4feature -> filterFragSpectra -> averageAllFragSpectra -> createDatabase -> spectralMatching -> (sqlite spectral database)

Usage

spectralMatching(
  q_dbPth,
  l_dbPth = NA,
  q_purity = NA,
  q_ppmProd = 10,
  q_ppmPrec = 5,
  q_raThres = NA,
  q_pol = NA,
  q_instrumentTypes = NA,
  q_instruments = NA,
  q_sources = NA,
  q_spectraTypes = c("av_all", "inter"),
  q_pids = NA,
  q_rtrange = c(NA, NA),
  q_spectraFilter = TRUE,
  q_xcmsGroups = NA,
  q_accessions = NA,
  l_purity = NA,
  l_ppmProd = 10,
  l_ppmPrec = 5,
  l_raThres = NA,
  l_pol = "positive",
  l_instrumentTypes = NA,
  l_instruments = NA,
  l_sources = NA,
  l_spectraTypes = NA,
  l_pids = NA,
  l_rtrange = c(NA, NA),
  l_spectraFilter = FALSE,
  l_xcmsGroups = NA,
  l_accessions = NA,
  usePrecursors = TRUE,
  raW = 0.5,
  mzW = 2,
  rttol = NA,
  q_dbType = "sqlite",
  q_dbName = NA,
  q_dbHost = NA,
  q_dbUser = NA,
  q_dbPass = NA,
  q_dbPort = NA,
  l_dbType = "sqlite",
  l_dbName = NA,
  l_dbHost = NA,
  l_dbUser = NA,
  l_dbPass = NA,
  l_dbPort = NA,
  cores = 1,
  updateDb = FALSE,
  copyDb = FALSE,
  outPth = "sm_result.sqlite"
)

Arguments

q_dbPth	character; Path of the database of queries that will be searched against the library spectra. Generated from createDatabase
l_dbPth	character; path to library spectral SQLite database. Defaults to msPurityData package data.
q_purity	character; Precursor ion purity threshold for the query spectra
q_ppmProd	numeric; ppm tolerance for query product
q_ppmPrec	numeric; ppm tolerance for query precursor
q_raThres	numeric; Relative abundance threshold for query spectra
q_pol	character; Polarity of query spectra ('positive', 'negative', NA).
q_instrumentTypes	vector; Instrument types for query spectra.
q_instruments	vector; Instruments for query spectra (note that this is used in combination with q_instrumentTypes - any spectra matching either q_instrumentTypes or q_instruments will be used).
q_sources	vector; Sources of query spectra (e.g. massbank, hmdb).
q_spectraTypes	character; Spectra types of query spectra to perfrom spectral matching e.g. ('scan', 'av_all', 'intra', 'inter')
q_pids	vector; pids for query spectra (correspond to column 'pid; in s_peak_meta)
q_rtrange	vector; retention time range (in secs) of query spectra, first value mininum time and second value max e.g. c(0, 10) is between 0 and 10 seconds
q_spectraFilter	boolean; For query spectra, if prior filtering performed with msPurity, flag peaks will be removed from spectral matching
q_xcmsGroups	vector; XCMS group ids for query spectra
q_accessions	vector; accession ids to filter query spectra
l_purity	character; Precursor ion purity threshold for the library spectra (uses interpolated purity - inPurity)
l_ppmProd	numeric; ppm tolerance for library product
l_ppmPrec	numeric; ppm tolerance for library precursor
l_raThres	numeric; Relative abundance threshold for library spectra
l_pol	character; Polarity of library spectra ('positive', 'negative', NA)
l_instrumentTypes	vector; Instrument types for library spectra.
l_instruments	vector; Instruments for library spectra (note that this is used in combination with q_instrumentTypes - any spectra matching either q_instrumentTypes or q_instruments will be used).
l_sources	vector; Sources of library spectra (e.g. massbank, hmdb).
l_spectraTypes	vector; Spectra type of library spectra to perfrom spectral matching with e.g. ('scan', 'av_all', 'intra', 'inter')
l_pids	vector; pids for library spectra (correspond to column 'pid; in s_peak_meta)
l_rtrange	vector; retention time range (in secs) of library spectra, first value mininum time and second value max e.g. c(0, 10) is between 0 and 10 seconds
l_spectraFilter	boolean; For library spectra, if prior filtering performed with msPurity, flag peaks will be removed from spectral matching
l_xcmsGroups	vector; XCMS group ids for library spectra
l_accessions	vector; accession ids to filter library spectra
usePrecursors	boolean; If TRUE spectra will be filtered by similarity of precursors based on ppm range defined by l_ppmPrec and q_ppmPrec
raW	numeric; Relative abundance weight for spectra (default to 0.5 as determined by massbank for ESI data)
mzW	numeric; mz weight for spectra (default to 2 as determined by massbank for ESI data)
rttol	numeric ; Tolerance in time range between the library and query spectra retention time
q_dbType	character; Query database type for compound database can be either (sqlite, postgres or mysql)
q_dbName	character; Query database name (only applicable for postgres and mysql)
q_dbHost	character; Query database host (only applicable for postgres and mysql)
q_dbUser	character; Query database user (only applicable for postgres and mysql)
q_dbPass	character; Query database pass - Note this is not secure! use with caution (only applicable for postgres and mysql)
q_dbPort	character; Query database port (only applicable for postgres and mysql)
l_dbType	character; Library database type for compound database can be either (sqlite, postgres or mysql)
l_dbName	character; Library database name (only applicable for postgres and mysql)
l_dbHost	character; Library database host (only applicable for postgres and mysql)
l_dbUser	character; Library database user (only applicable for postgres and mysql)
l_dbPass	character; Library database pass - Note this is not secure! use with caution (only applicable for postgres and mysql)
l_dbPort	character; Library database port (only applicable for postgres and mysql)
cores	numeric; Number of cores to use
updateDb	boolean; Update the Query SQLite database with the results
copyDb	boolean; If updating the database - perform on a copy rather thatn the original query database
outPth	character; If copying the database - the path of the new database file

Value

Returns a list containing the following elements

q_dbPth

Path of the query database (this will have been updated with the annotation results if updateDb argument used)

xcmsMatchedResults

If the qeury spectra had XCMS based chromotographic peaks tables (e.g c_peak_groups, c_peaks) in the sqlite database - it will be possible to summarise the matches for each XCMS grouped feature. The dataframe contains the following columns

• lpid - id in database of library spectra

• qpid - id in database of query spectra

• dpc - dot product cosine of the match

• rdpc - reverse dot product cosine of the match

• cdpc - composite dot product cosine of the match

• mcount - number of matching peaks

• allcount - total number of peaks across both query and library spectra

• mpercent - percentage of matching peaks across both query and library spectra

• library_rt - retention time of library spectra

• query_rt - retention time of query spectra

• rtdiff - difference between library and query retention time

• library_precursor_mz - library precursor mz

• query_precursor_mz - query precursor mz

• library_precursor_ion_purity - library precursor ion purity

• query_precursor_ion_purity - query precursor ion purity

• library_accession - library accession value (unique string or number given to eith MoNA or Massbank data entires)

• library_precursor_type - library precursor type (i.e. adduct)

• library_entry_name - Name given to the library spectra

• inchikey - inchikey of the matched library spectra

• library_source_name - source of the spectra (e.g. massbank, gnps)

• library_compound_name - name of compound spectra was obtained from

matchedResults

All matched results from the query spectra to the library spectra. Contains the same columns as above but without the XCMS details. This table is useful to observe spectral matching results for all MS/MS spectra irrespective of if they are linked to XCMS MS1 features.

list of database details and dataframe summarising the results for the xcms features

Examples

#====== XCMS =================================
## Read in MS data
#msmsPths <- list.files(system.file("extdata", "lcms", "mzML",
#           package="msPurityData"), full.names = TRUE, pattern = "MSMS")
#ms_data = readMSData(msmsPths, mode = 'onDisk', msLevel. = 1)

## Find peaks in each file
#cwp <- CentWaveParam(snthresh = 5, noise = 100, ppm = 10, peakwidth = c(3, 30))
#xcmsObj  <- xcms::findChromPeaks(ms_data, param = cwp)

## Optionally adjust retention time
#xcmsObj  <- adjustRtime(xcmsObj , param = ObiwarpParam(binSize = 0.6))

## Group features across samples
#pdp <- PeakDensityParam(sampleGroups = c(1, 1), minFraction = 0, bw = 30)
#xcmsObj <- groupChromPeaks(xcmsObj , param = pdp)

#====== msPurity ============================
#pa  <- purityA(msmsPths)
#pa <- frag4feature(pa = pa, xcmsObj = xcmsObj)
#pa <- filterFragSpectra(pa, allfrag=TRUE)
#pa <- averageAllFragSpectra(pa)
#q_dbPth <- createDatabase(pa, xcmsObj, metadata=list('polarity'='positive','instrument'='Q-Exactive'))
#sm_result <- spectralMatching(q_dbPth, cores=4, l_pol='positive')

td <- tempdir()
q_dbPth <- system.file("extdata", "tests", "db", "createDatabase_example.sqlite", package="msPurity")

rid <- paste0(paste0(sample(LETTERS, 5, TRUE), collapse=""),  paste0(sample(9999, 1, TRUE), collapse=""), ".sqlite")
sm_out_pth <- file.path(td, rid)

result <- spectralMatching(q_dbPth, q_xcmsGroups = c(53, 89, 410), cores=1, l_accessions = c('PR100407', 'ML005101', 'CCMSLIB00003740024'),
                          q_spectraTypes = 'av_all',
                          updateDb = TRUE,
                          copyDb = TRUE,
                          outPth = sm_out_pth)

Viant-Metabolomics/msPurity documentation built on May 13, 2024, 8:23 a.m.