Class containing MS Peak Lists

Source: R/generics.R, R/mspeaklists.R, R/mspeaklists-set.R, and 1 more

Contains all MS (and MS/MS where available) peak lists for a featureGroups object.

peakLists(obj, ...)

averagedPeakLists(obj, ...)

spectrumSimilarity(obj, ...)

# S4 method for class 'MSPeakLists'
peakLists(obj)

# S4 method for class 'MSPeakLists'
averagedPeakLists(obj)

# S4 method for class 'MSPeakLists'
analyses(obj)

# S4 method for class 'MSPeakLists'
groupNames(obj)

# S4 method for class 'MSPeakLists'
length(x)

# S4 method for class 'MSPeakLists'
show(object)

# S4 method for class 'MSPeakLists,ANY,ANY,missing'
x[i, j, ..., reAverage = FALSE, drop = TRUE]

# S4 method for class 'MSPeakLists,ANY,ANY'
x[[i, j]]

# S4 method for class 'MSPeakLists'
x$name

# S4 method for class 'MSPeakLists'
as.data.table(x, fGroups = NULL, averaged = TRUE)

# S4 method for class 'MSPeakLists'
delete(obj, i = NULL, j = NULL, k = NULL, reAverage = FALSE, ...)

# S4 method for class 'MSPeakLists'
filter(
  obj,
  absMSIntThr = NULL,
  absMSMSIntThr = NULL,
  relMSIntThr = NULL,
  relMSMSIntThr = NULL,
  topMSPeaks = NULL,
  topMSMSPeaks = NULL,
  minMSMSPeaks = NULL,
  isolatePrec = NULL,
  deIsotopeMS = FALSE,
  deIsotopeMSMS = FALSE,
  withMSMS = FALSE,
  annotatedBy = NULL,
  retainPrecursorMSMS = TRUE,
  reAverage = FALSE,
  negate = FALSE
)

# S4 method for class 'MSPeakLists'
plotSpectrum(
  obj,
  groupName,
  analysis = NULL,
  MSLevel = 1,
  title = NULL,
  specSimParams = getDefSpecSimParams(),
  xlim = NULL,
  ylim = NULL,
  ...
)

# S4 method for class 'MSPeakLists'
spectrumSimilarity(
  obj,
  groupName1,
  groupName2 = NULL,
  analysis1 = NULL,
  analysis2 = NULL,
  MSLevel = 1,
  specSimParams = getDefSpecSimParams(),
  NAToZero = FALSE,
  drop = TRUE
)

# S4 method for class 'MSPeakListsSet'
analysisInfo(obj)

# S4 method for class 'MSPeakListsSet'
show(object)

# S4 method for class 'MSPeakListsSet,ANY,ANY,missing'
x[i, j, ..., reAverage = FALSE, sets = NULL, drop = TRUE]

# S4 method for class 'MSPeakListsSet'
as.data.table(x, fGroups = NULL, averaged = TRUE)

# S4 method for class 'MSPeakListsSet'
delete(obj, ...)

# S4 method for class 'MSPeakListsSet'
filter(
  obj,
  ...,
  annotatedBy = NULL,
  retainPrecursorMSMS = TRUE,
  reAverage = FALSE,
  negate = FALSE,
  sets = NULL
)

# S4 method for class 'MSPeakListsSet'
plotSpectrum(
  obj,
  groupName,
  analysis = NULL,
  MSLevel = 1,
  title = NULL,
  specSimParams = getDefSpecSimParams(),
  xlim = NULL,
  ylim = NULL,
  perSet = TRUE,
  mirror = TRUE,
  ...
)

# S4 method for class 'MSPeakListsSet'
spectrumSimilarity(
  obj,
  groupName1,
  groupName2 = NULL,
  analysis1 = NULL,
  analysis2 = NULL,
  MSLevel = 1,
  specSimParams = getDefSpecSimParams(),
  NAToZero = FALSE,
  drop = TRUE
)

# S4 method for class 'MSPeakListsSet'
unset(obj, set)

getDefIsolatePrecParams(...)

Arguments

obj, x, object

The MSPeakLists object to access.

...

Further arguments passed to plot.

1MSPeakLists

i, j

For [/[[: A numeric or character value which is used to select analyses/feature groups by their index or name, respectively (for the order/names see analyses()/groupNames()).

For [: Can also be logical to perform logical selection (similar to regular vectors). If missing all analyses/feature groups are selected.

For [[: should be a scalar value. If j is not specified, i selects by feature groups instead.

For delete: The data to remove from. i are the feature groups as numeric index, logical or character, j the MS peaks as numeric indices (rows). If either is NULL then data for all is removed. j may also be a function: it will be called for each feature group, with the peak list table (a data.table), feature group name, analysis (NULL if averaged peak list), type ("MS" or "MSMS") and any other arguments passed as ... to delete. The return value of this function specifies the peak list indices (rows) to be removed (specified as an integer or logical vector).

reAverage

Set to TRUE to regenerate group averaged MS peak lists. NOTE it is very important that any annotation data relying on MS peak lists (formulae/compounds) are regenerated afterwards! Otherwise it is likely that e.g. plotting methods will use wrong MS/MS data.

drop

If set to TRUE and if the comparison is made between two spectra then drop is used to reduce the matrix return value to a numeric vector.

name

The feature group name (partially matched).

fGroups

The featureGroups object that was used to generate this object. If not NULL it is used to add feature group information (retention and m/z values).

averaged

If TRUE then feature group averaged peak list data is used.

k

A vector with analyses (character with names or integer with indices) for which the data should be deleted. If k!=NULL then deletions will not occur on group averaged peak lists. Otherwise, if k=NULL then deltion occurs on both group averaged and analysis specific peak lists.

absMSIntThr, absMSMSIntThr, relMSIntThr, relMSMSIntThr

Absolute/relative intensity threshold for MS or MS/MS peak lists. NULL for none.

topMSPeaks, topMSMSPeaks

Only consider this amount of MS or MS/MS peaks with highest intensity. NULL to consider all.

minMSMSPeaks

If the number of peaks in an MS/MS peak list (excluding the precursor peak) is lower than this it will be completely removed. Set to NULL to ignore.

isolatePrec

If not NULL then value should be a list with parameters used for isolating the precursor and its isotopes in MS peak lists (see Isolating precursor data). Alternatively, TRUE to apply the filter with default settings (as given with getDefIsolatePrecParams).

deIsotopeMS, deIsotopeMSMS

Remove any isotopic peaks in MS or MS/MS peak lists. This may improve data processing steps which do not assume the presence of isotopic peaks (e.g. MetFrag for MS/MS). Note that getMzRPeakLists does not (yet) support flagging of isotopes.

withMSMS

If set to TRUE then only results will be retained for which MS/MS data is available. if negate=TRUE then only results without MS/MS data will be retained.

annotatedBy

Either a formulas or compounds object, or a list with both. Any MS/MS peaks that are not annotated by any of the candidates in the specified objects are removed.

retainPrecursorMSMS

If TRUE then precursor peaks will never be filtered out from MS/MS peak lists (note that precursors are never removed from MS peak lists). The negate argument does not affect this setting.

negate

If TRUE then filters are applied in opposite manner.

groupName

The name of the feature group for which a plot should be made. To compare spectra, two group names can be specified.

analysis

The name of the analysis for which a plot should be made. If NULL then data from the feature group averaged peak list is used. When comparing spectra, either NULL or the analyses for both spectra should be specified.

MSLevel

The MS level: 1 for regular MS, 2 for MSMS.

title

The title of the plot. If NULL a title will be automatically made.

specSimParams

A named list with parameters that influence the calculation of MS spectra similarities. See the spectral similarity parameters documentation for more details.

xlim, ylim

Sets the plot size limits used by plot. Set to NULL for automatic plot sizing.

groupName1, groupName2

The names of the feature groups for which the comparison should be made. If both arguments are specified then a comparison is made with the spectra specified by groupName1 vs those specified by groupName2. The length of either can be >1 to generate a comparison matrix. Alternatively, if groupName2 is NULL then all the spectra specified in groupName1 will be compared with eachother, i.e. resulting in a square similarity matrix.

analysis1, analysis2

The name of the analysis (analyses) for the comparison. If NULL then data from the feature group averaged peak list is used. Otherwise, should be the same length as groupName1/groupName2.

NAToZero

Set to TRUE to convert NA similarities (i.e. when no similarity could be calculated) to zero values.

sets

A character with name(s) of the sets to keep (or remove if negate=TRUE).

perSet, mirror

If perSet=TRUE then the set specific mass peaks are annotated separately. Furthermore, if mirror=TRUE (and there are two sets in the object) then a mirror plot is generated.

set

The name of the set.

Value

peakLists returns a nested list containing MS (and MS/MS where available) peak lists per feature group and per analysis. The format is: [[analysis]][[featureGroupName]][[MSType]][[PeakLists]] where MSType is either "MS" or "MSMS" and PeakLists a data.table containing all m/z values (mz column) and their intensities (intensity column). In addition, the peak list tables may contain a cmp column which contains an unique alphabetical identifier to which isotopic cluster (or "compound") a mass belongs (only supported by MS peak lists generated by Bruker tools at the moment).

averagedPeakLists returns a nested list of feature group averaged peak lists in a similar format as peakLists.

delete returns the object for which the specified data was removed.

Details

Objects for this class are returned by generateMSPeakLists.

The getDefIsolatePrecParams is used to create a parameter list for isolating the precursor and its isotopes (see Isolating precursor data).

Methods (by generic)

  • peakLists(MSPeakLists): Accessor method to obtain the MS peak lists.

  • averagedPeakLists(MSPeakLists): Accessor method to obtain the feature group averaged MS peak lists.

  • analyses(MSPeakLists): returns a character vector with the names of the analyses for which data is present in this object.

  • groupNames(MSPeakLists): returns a character vector with the names of the feature groups for which data is present in this object.

  • length(MSPeakLists): Obtain total number of m/z values.

  • show(MSPeakLists): Shows summary information for this object.

  • x[i: Subset on analyses/feature groups.

  • x[[i: Extract a list with MS and MS/MS (if available) peak lists. If the second argument (j) is not specified the averaged peak lists for the group specified by the first argument (i) will be returned.

  • $: Extract group averaged MS peaklists for a feature group.

  • as.data.table(MSPeakLists): Returns all MS peak list data in a table.

  • delete(MSPeakLists): Completely deletes specified peaks from MS peak lists.

  • filter(MSPeakLists): provides post filtering of generated MS peak lists, which may further enhance quality of subsequent workflow steps (e.g. formulae calculation and compounds identification) and/or speed up these processes. The filters are applied to all peak lists for each analysis. These peak lists are subsequently averaged to update group averaged peak lists. However, since version 1.1, the resulting feature group lists are not filtered afterwards.

  • plotSpectrum(MSPeakLists): Plots a spectrum using MS or MS/MS peak lists for a given feature group. Two spectra can be compared when two feature groups are specified.

  • spectrumSimilarity(MSPeakLists): Calculates the spectral similarity between two or more spectra.

Slots

peakLists

Contains a list of all MS (and MS/MS) peak lists. Use the peakLists method for access.

metadata

Metadata for all spectra used to generate peak lists. Follows the format of the peakLists slot.

averagedPeakLists

A list with averaged MS (and MS/MS) peak lists for each feature group.

avgPeakListArgs

A list with arguments used to generate feature group averaged MS(/MS) peak lists.

origFGNames

A character with the original input feature group names.

analysisInfo

Analysis information. Use the analysisInfo method for access.

Isolating precursor data

Formula calculation typically relies on evaluating the measured isotopic pattern from the precursor to score candidates. Some algorithms (currently only GenForm) penalize candidates if mass peaks are present in MS1 spectra that do not contribute to the isotopic pattern. Since these spectra are typically very 'noisy' due to background and co-eluting ions, an additional filtering step may be recommended prior to formula calculation. During this precursor isolation step all mass peaks are removed that are (1) not the precursor and (2) not likely to be an isotopologue of the precursor. To determine potential isotopic peaks the following parameters are used:

  • maxIsotopes The maximum number of isotopes to consider. For instance, a value of 5 means that M+0 (i.e. the monoisotopic peak) till M+5 is considered. All mass peaks outside this range are removed.

  • mzDefectRange A two-sized vector specifying the minimum (can be negative) and maximum m/z defect deviation compared to the precursor m/z defect. When chlorinated, brominated or other compounds with strong m/z defect in their isotopologues are to be considered a higher range may be desired. On the other hand, for natural compounds this range may be tightened. Note that the search range is propegated with increasing distance from the precursor, e.g. the search range is doubled for M+2, tripled for M+3 etc.

  • intRange A two-sized vector specifying the minimum and maximum relative intensity range compared to the precursor. For instance, c(0.001, 2) removes all peaks that have an intensity below 0.1% or above 200% of that of the precursor.

  • z The z value (i.e. absolute charge) to be considerd. For instance, a value of 2 would look for M+0.5, M+1 etc. Note that the mzDefectRange is adjusted accordingly (e.g. halved if z=2).

  • maxGap The maximum number of missing adjacent isotopic peaks ('gaps'). If the (rounded) m/z difference to the previous peak exceeds this value then this and all next peaks will be removed. Similar to z, the maximum gap is automatically adjusted for charge.

These parameters should be in a list that is passed to the isolatePrec argument to filter. The default values can be obtained with the getDefIsolatePrecParams function:

maxIsotopes=5; mzDefectRange=c(-0.01, 0.01); intRange=c(0.001, 2); z=1; maxGap=2

S4 class hierarchy

Source

spectrumSimilarity: The principles of spectral binning and cosine similarity calculations were loosely was based on the code from SpectrumSimilarity() function of OrgMassSpecR.

Sets workflows

MSPeakListsSetMSPeakLists

MSPeakListsUnsetOnly the MS peaks that are present in the specified set are kept. analysisInfo Returns the analysis info for this object.

filter and the subset operator ([) Can be used to select data that is only present for selected sets. The filter method is applied for each set individually, and afterwards the results are combined again (see generateMSPeakLists). Note that this has important implications for e.g. relative intensity filters (relMSIntThr/relMSMSIntThr), topMSPeaks/topMSMSPeaks and minMSMSPeaks. Similarly, when the annotatedBy filter is applied, each set specific MS peak list is filtered by the annotation results from only that set. plotSpectrum Is able to highlight set specific mass peaks (perSet and mirror arguments). spectrumSimilarity First calculates similarities for each spectral pair per set (e.g. all positive mode spectra are compared and then all negative mode spectra are compared). This data is then combined into an overall similarity value. How this combination is performed depends on the setCombineMethod field of the specSimParams argument.

Author

For spectrumSimilarity: major contributions by Bas van de Velde for spectral binning and similarity calculation.