---
title: "MS2 fragment ions"
output:
    BiocStyle::html_document:
        toc_float: true
vignette: >
    %\VignetteIndexEntry{MS2 fragment ions}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
    %\VignettePackage{PSMatch}
    %\VignetteDepends{mzR,mzID,BiocStyle,msdata}
---

```{r style, echo = FALSE, results = 'asis', message=FALSE}
BiocStyle::markdown()
```

**Package**: `r Biocpkg("PSMatch")`<br />
**Authors**: `r packageDescription("PSMatch")[["Author"]] `<br />
**Last modified:** `r file.info("Fragments.Rmd")$mtime`<br />
**Compiled**: `r date()`

```{r setup, message = FALSE, echo = FALSE}
library("PSMatch")
```

# Introduction

This vignette is one among several illustrating how to use the
`PSMatch` package, focusing on the calculation and visualisation of
MS2 fragment ions. For a general overview of the package, see the
`PSMatch` package manual page (`?PSMatch`) and references therein.


To illustrate this vignette, we will import and merge raw and
identification data from the `r Biocpkg("msdata")`. For details about
this section, please visit the
[Spectra](https://rformassspectrometry.github.io/Spectra/articles/Spectra.html)
package webpage.

Load the raw MS data:

```{r, message = FALSE}
(spf <- msdata::proteomics(pattern = "2014", full.names = TRUE))
library(Spectra)
sp <- Spectra(spf)
```

Load the identification data:

```{r}
(idf <- msdata::ident(pattern = "2014", full.names = TRUE))
id <- PSM(idf) |> filterPSMs()
id
```

Merge both:

```{r}
sp <- joinSpectraData(sp, id, by.x = "spectrumId", by.y = "spectrumID")
sp
```

In this example, we are going to focus the MS2 scan with index 1158
and its parent MS1 scan (index 1148, selected automatically with the
[filterPrecursorScan()](https://rformassspectrometry.github.io/Spectra/reference/MsBackend.html)
function).

```{r}
sp1158 <- filterPrecursorScan(sp, 1158)
```

```{r}
plotSpectra(sp1158[1], xlim = c(400, 600))
abline(v = precursorMz(sp1158)[2], col = "red", lty = "dotted")
```

# Calculating fragment ions

The MS2 scan was matched to the sequence `SCALITDGR`.

```{r}
sp1158$sequence
```

The `calculateFragments()` simply takes a peptide sequence as input
and returns a `data.frame` with the fragment sequences, M/Z, ion type,
charge, position and the peptide sequence of the parent ion.

```{r}
calculateFragments(sp1158$sequence[2])
```

The function also allows to generate fragment sequences with fixed and/or
variable modifications. By default, `fixed_modifications = c(C = 57.02146)` for
carbamidomethylation of cysteine.

With variable modifications, multiple sets of fragments are generated. The 
fragments can be traced to their parent ion by checking the `peptide` column.
A fragment can have multiple modifications.

```{r}
calculateFragments(sp1158$sequence[2], 
                   fixed_modifications = NULL,
                   variable_modifications = c(C = 57.02146, 
                                              T = 79.966))
```

Additional parameters can limit the maximum number of allowed modifications, 
the type of ions produced or the charge applied. See `?calculateFragments` for
more details on those. 

# Visualising fragment ions

We can now visualise these fragments directly on the MS
spectrum. Let's first visualise the spectrum as is:

```{r}
plotSpectra(sp1158[2])
```

`plotSpectraPTM()` allows a more in depth visualisation of a PSM by providing 
a delta mass plot of matched fragments and a direct visualisation of matched 
b- and y-ion fragment sequences. 

Labels are automatically applied based on the `sequence` defined in the
`spectraVariables` with carbamidomethylation of 
cysteines set as default fixed modification. 

```{r}
dataOrigin(sp1158)[2] <- "TMT_Erwinia" ## Reduces the mzspec text
plotSpectraPTM(sp1158[2],
               main = "Scan 1158 with carbamidomethylation")
```

More importantly, `plotSpectraPTM()` allows to visualise and compare the matches
with different modifications.
For instance, there is a better match when carbamidomethylation of cysteines 
is applied (as above) compared to no modifications at all.

```{r}
plotSpectraPTM(sp1158[2], 
               fixed_modifications = NULL,
               variable_modifications = NULL,
               main = "Scan 1158 without modifications")
```

As glycine has the same mass as carbamidomethylation, the b7 and b8 ions are 
overlapping in both spectra).

Both plots can be created at once using the `variable_modifications` parameter.

```{r, fig.width = 8, fig.height = 8, out.width="1000px"}
plotSpectraPTM(sp1158[2], 
               fixed_modifications = NULL,
               variable_modifications = c(C = 57.02146),
               deltaMz = FALSE)
```


For more details on what `plotSpectraPTM()` can do, run `?plotSpectraPTM`.

# Session information

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