---
title: "Using the MassSpecWavelet package"
author:
- name: Pan Du
  affiliation:
  - &id Robert H. Lurie Comprehensive Cancer Center. Northwestern University, Chicago, IL, 60611, USA
- name:  Warren A. Kibbe
  affiliation: *id
- name:  Simon Lin
  affiliation: *id
package: MassSpecWavelet
output:
  BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Using the MassSpecWavelet package}
  %\VignetteKeywords{Mass Spectrometry}
  %\VignetteKeywords{Wavelet}
  %\VignetteKeywords{MassSpecWavelet}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Version Info

```{r, echo=FALSE, results="hide", warning=FALSE}
suppressPackageStartupMessages({
library('MassSpecWavelet')
})
```
<p>
**R version**: `r R.version.string`
<br />
**Bioconductor version**: `r BiocManager::version()`
<br />
**Package version**: `r packageVersion("MassSpecWavelet")`
</p>

# Overview of MassSpecWavelet 

MassSpecWavelet R package is aimed to process Mass Spectrometry (MS) data mainly based on Wavelet Transforms. The current version supports the peak detection based on Continuous Wavelet Transform (CWT). The algorithms have been evaluated with low resolution mass spectra (SELDI and MALDI data), we believe some of the algorithms can also be applied to other kind of spectra. 


If you use MassSpecWavelet, please consider citing our work:

```{r echo=FALSE, results='asis'}
print(citation("MassSpecWavelet"), style = "html")
```


# Peak detection by using CWT-based pattern matching

Motivation: A major problem for current peak detection algorithms is that noise in Mass Spectrometry (MS) spectrum gives rise to a high rate of false positives. The false positive rate is especially problematic in detecting peaks with low amplitudes. Usually, various baseline correction algorithms and smoothing methods are applied before attempting peak detection. This approach is very sensitive to the amount of smoothing and aggressiveness of the baseline correction, which contribute to making peak detection results inconsistent between runs, instrumentation and analysis methods.

Results: Most peak detection algorithms simply identify peaks based on amplitude, ignoring the additional information present in the shape of the peaks in a spectrum. In our experience, 'true' peaks have characteristic shapes, and providing a shape-matching function that provides a 'goodness of fit' coefficient should provide a more robust peak identification method. Based on these observations, a Continuous Wavelet Transform (CWT)-based peak detection algorithm has been devised that identifies peaks with different scales and amplitudes. By transforming the spectrum into wavelet space, the pattern-matching problem is simplified and additionally provides a powerful technique for identifying and separating signal from spike noise and colored noise. This transformation, with the additional information provided by the 2-D CWT coefficients can greatly enhance the effective Signal-to-Noise Ratio (SNR). Furthermore, with this technique no baseline removal or peak smoothing preprocessing steps are required before peak detection, and this improves the robustness of peak detection under a variety of conditions. The algorithm was evaluated with real MS spectra with known polypeptide positions. Comparisons with two other popular algorithms were performed. The results show the CWT-based algorithm can identify both strong and weak peaks while keeping false positive rate low.

## Continuous wavelet transform with Mexican Hat wavelet

Load the example data

```{r}
data(exampleMS)
```


```{r}
plotRange <- c(5000, 11000)
plot(exampleMS, xlim = plotRange, type = "l")
```


Continuous wavelet transform with Mexican Hat wavelet. The 2-D CWT coefficients image of MS spectrum in [5000, 11000] is shown in Figure \@ref(fig:cwt)

```{r}
scales <- seq(1, 64, 2)
 wCoefs <- cwt(exampleMS, scales = scales, wavelet = "mexh")
```

```{r cwt,fig.align='center', fig.cap="2-D CWT coefficient image", height=10, width=20}
## Plot the 2-D CWT coefficients as image (It may take a while!)
xTickInterval <- 1000
plotRange <- c(5000, 11000)
image(
  plotRange[1]:plotRange[2],
  scales,
  wCoefs[plotRange[1]:plotRange[2],],
  col=terrain.colors(256),
  axes=FALSE,
  xlab='m/z index',
  ylab='CWT coefficient scale',
  main='CWT coefficients'
)
axis(1, at=seq(plotRange[1], plotRange[2], by=xTickInterval))
axis(2, at=c(1, seq(10, 64, by=10)))
box()
```

The smallest scales can be used for noise estimation, smaller scales are then
useful for peaks with smaller width. Larger scales can detect wider peaks, at the
expense of merging narrower peaks together.

```{r}
plot(exampleMS, xlim = c(8000, 9000), type = "l")
```


```{r}
matplot(
    wCoefs[,ncol(wCoefs):1], 
    type = "l",
    col = rev(rainbow(max(scales), start = 0.7, end = 0.1, alpha = 0.5)[scales]),
    lty = 1,
    xlim = c(8000, 9000),
    xlab = "m/z index",
    ylab = "CWT coefficients"
)
legend(
    x = "topright",
    legend = sprintf("scales = %d", scales[seq(1, length(scales), length.out = 4)]),
    lty = 1,
    col = rainbow(max(scales), start = 0.7, end = 0.1)[scales[seq(1, length(scales), length.out = 4)]]
)

```


## Peak identification process

Identify the ridges by linking the local maxima. The identified local maxima is shown in Figure \@ref(fig:localMax)

```{r }
## Attach the raw spectrum as the first column
wCoefs <- cbind(as.vector(exampleMS), wCoefs)
colnames(wCoefs) <- c(0, scales)
localMax <- getLocalMaximumCWT(wCoefs)

```

```{r localMax, width=10, height=5,fig.align='center',fig.cap="Identified local maxima of CWT coefficients at each scale"}
plotLocalMax(localMax, wCoefs, range=plotRange)
```


Identify the ridge lines by connecting local maxima of CWT coefficient at adjacent scales

```{r }
ridgeList <- getRidge(localMax)
```

```{r ridge, width=10, height=5,fig.align='center',fig.cap="Identified ridge lines based on 2-D CWT coefficients"}
plotRidgeList(ridgeList,  wCoefs, range=plotRange)
```

Identify the identified ridges lines and SNR using `identifyMajorPeaks()`. The returns of `identifyMajorPeaks()` include the `peakIndex`, `peakSNR`, etc. All these elements carry peak names, which are the same as the corresponding peak ridges. See function `getRidge()` for details.

```{r }
SNR.Th <- 3
nearbyPeak <- TRUE
majorPeakInfo <- identifyMajorPeaks(
  exampleMS,
  ridgeList,
  wCoefs,
  SNR.Th = SNR.Th,
  nearbyPeak=nearbyPeak
)
## Plot the identified peaks
peakIndex <- majorPeakInfo$peakIndex
```

Plot the spectra with identified peaks marked with red circles.

```{r peak, width=10, height=5,fig.align='center',fig.cap='Identified peaks'}
plotPeak(
  exampleMS,
  peakIndex,
  range=plotRange,
  main=paste('Identified peaks with SNR >', SNR.Th)
)
```


All of the above steps are encapsulated as a main function of peak detection main:

```{r }
data(exampleMS)
SNR.Th <- 3
nearbyPeak <- TRUE
peakInfo <- peakDetectionCWT(exampleMS, SNR.Th=SNR.Th, nearbyPeak=nearbyPeak)
majorPeakInfo = peakInfo$majorPeakInfo
peakIndex <- majorPeakInfo$peakIndex
plotRange <- c(5000, length(exampleMS))
```

```{r peak1, width=10, height=5, fig.cap='Identified peaks', fig.align='center'}
plotPeak(
  exampleMS,
  peakIndex,
  range=plotRange,
  log='x',
  main=paste('Identified peaks with SNR >', SNR.Th)
)
```

Plot Signal to Noise Ration (SNR) of the peaks

```{r}
peakSNR <- majorPeakInfo$peakSNR
allPeakIndex <- majorPeakInfo$allPeakIndex
```

```{r SNR, width=10, height=5,fig.align='center',fig.cap='Estimated Signal to Noise Ration (SNR) of the peaks'}
plotRange <- c(5000, 36000)
selInd <- which(allPeakIndex >= plotRange[1] & allPeakIndex < plotRange[2])
plot(
  allPeakIndex[selInd],
  peakSNR[selInd],
  type='h',
  xlab='m/z Index',
  ylab='Signal to Noise Ratio (SNR)',
  log='x'
)
points(peakIndex, peakSNR[names(peakIndex)], type='h', col='red')
title('Signal to Noise Ratio (SNR) of the peaks (CWT method)')
```


## Refine the peak parameter estimation
The above peak detection process can identify the peaks, however, it can only approximately estimate the peak parameters, like peak strength (proportional to Area Under Curve), peak center position and peak width. In order to get better estimation of these parameter, an estimation refine step can be added.

```{r }
betterPeakInfo <- tuneInPeakInfo(exampleMS, majorPeakInfo)
```

```{r peak2, width=10, height=5,fig.align='center',fig.cap='Identified peaks with refined peak center position'}
plotRange <- c(5000, 11000)
plot(
  plotRange[1]:plotRange[2],
  exampleMS[plotRange[1]:plotRange[2]],
  type='l',
  log='x',
  xlab='m/z Index',
  ylab='Intensity'
)
abline(v=betterPeakInfo$peakCenterIndex, col='red')
```

# Future Extension

More MS data analysis and wavelet related functions will be implemented in MassSpecWavelet package.


# Acknowledgments
We would like to thanks the users and researchers around the world contribute to the MassSpecWavelet package, provide great comments and suggestions and report bugs. Especially, we would like to thanks Steffen Neumann and Ralf Tautenhahn fixing some bugs for the package.


# Session Information

```{r}
sessionInfo()
```