---
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,MsDataHub}
---

```{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("MsDataHub")`. 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 <- MsDataHub::TMT_Erwinia_1uLSike_Top10HCD_isol2_45stepped_60min_01.20141210.mzML.gz()
library(Spectra)
sp <- Spectra(spf)
```

Load the identification data:

```{r}
idf <- MsDataHub::TMT_Erwinia_1uLSike_Top10HCD_isol2_45stepped_60min_01.20141210.mzid()
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. By default,
carbamidomethylation of cysteines is applied, but it can be turned off with the
parameter `addCarbamidomethyl = FALSE`.

```{r}
calculateFragments(sp1158$sequence[2], addCarbamidomethyl = FALSE)
```

The function also allows to generate fragment sequences with fixed and/or
variable modifications using the `PTMods::addFixedModifications()` and
`PTMods::addVariableModifications()` functions from the `r
BiocStyle::Biocpkg("PTMods")` package.

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

```{r}
var_seq <- PTMods::addVariableModifications(sp1158$sequence[2],
    variableModifications = c(C = 57.02146, T = 79.966)
)

calculateFragments(var_seq)
```

Additional parameters can alter the type of ions produced or the charge applied
in `calculateFragments`. See `?calculateFragments` for more details on those.
See the `PTMods` functions (`?PTMods::convertAnnotation`,
`?PTMods::getCanonicalSequence`, `?PTMods::combineModifications`) for how to
handle/apply/change the annotation style of modifications on your sequences or
check out the corresponding vignette with `vignette("PTMods", package =
"PTMods")`.

# 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`. Additionally, variable or fixed modifications such as
carbamidomethylation of cysteines can be added using the
`variableModifications` and `fixedModifications` parameters. Remember, by
default, carbamidomethylation is applied on all sequences.

```{r}
dataOrigin(sp1158)[2] <- "TMT_Erwinia" ## Reduces the mzspec text
plotSpectraPTM(sp1158[2],
    fixedModifications = c(C = "Carbamidomethyl")
)
```

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],
    variableModifications = c(C = "Carbamidomethyl"),
    addCarbamidomethyl = FALSE, ## Remove carbamidomethyl by default
    asp = 1/2,
    deltaMz = FALSE,
    main = c("Scan 1158 without carbamidomethyl", "Scan 1158 with carbamidomethyl")
)
```

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

The spectra displayed in this vignette might be overlapping due to the
restricted windows. For a better visualisation, we suggest running the code
locally.

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

# Session information

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