---
title: "MS2 chromatograms based alignment of targeted mass-spectrometry runs"
author: "Shubham Gupta and Hannes Röst"
package: DIAlignR
date: "`r Sys.Date()`"
output:
    BiocStyle::html_document:
        toc: true
        toc_float: true 
bibliography: DIAlignR.bib
vignette: >
  %\VignetteIndexEntry{MS2 chromatograms based alignment of targeted mass-spectrometry runs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteKeywords{Retention time alignment, DIA, Targeted MS, mass spectrometry, proteomics, metabolomics}
  %\VignettePackage{DIAlignR}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

In this document we are presenting a workflow of retention-time alignment across multiple Targeted-MS (e.g. DIA, SWATH-MS, PRM, SRM) runs using DIAlignR. This tool requires MS2 chromatograms and provides a hybrid approach of global and local alignment to establish correspondence between peaks.

## Install DIAlignR
```{r installDIAlignR, eval=FALSE}
if(!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("DIAlignR")
```

```{r loadDIAlignR}
library(DIAlignR)
```

## Prepare input files for alignment
Mass-spectrometry files mostly contains spectra. Targeted proteomics workflow identifyies analytes from their chromatographic elution profile. DIAlignR extends the same concept for retention-time (RT) alignment and, therefore, relies on MS2 chromatograms. DIAlignR expects raw chromatogram file (.chrom.mzML) and FDR-scored features (.osw) file.   
Example files are available with this package and can be located with this command:
```{r getDataPath}
dataPath <- system.file("extdata", package = "DIAlignR")
```

|     (Optional) To obtain files for alignment, following three steps are needed:  

* Step 1 Convert spectra files from vendor-specific format to standard mzMl format using [ProteoWizard-MSConvert](http://proteowizard.sourceforge.net/tools.shtml).    
* Step 2 Extract features and raw extracted-ion chromatograms(XICs) for library analytes. A detailed tutorial using [OpenSWATH](http://openswath.org/en/latest/docs/openswath.html) is available for this steps. In short, following `bash` command can be used:  
    
```{bash, eval=FALSE}
OpenSwathWorkflow -in Filename.mzML.gz -tr library.pqp -tr_irt
iRTassays.TraML -out_osw Filename.osw -out_chrom Filename.chrom.mzML
```

|     Output files **Filename.osw** and **Filename.chrom.mzML** are required to next steps. Some chromatograms are stored in compressed form and currently inaccesible by `mzR`. In such cases `mzR` would throw an error indicating `Invalid cvParam accession "1002746"`. To avoid this issue, uncompress chromatograms using OpenMS.

```{bash, eval=FALSE}
FileConverter -in Filename.chrom.mzML -in_type 'mzML' -out Filename.chrom.mzML
```

* Step 3: Score features and calculate their q-values. A machine-learning based workflow is available with [PyProphet](http://openswath.org/en/latest/docs/pyprophet.html). For multiplt-runs experiment-wide FDR is recommended. An example of running pyprophet on OpenSWATH results is given below:

```{bash, eval=FALSE}
pyprophet merge --template=library.pqp --out=merged.osw *.osw
pyprophet score --in=merged.osw --classifier=XGBoost --level=ms2 --xeval_num_iter=3 \
--ss_initial_fdr=0.05 --ss_iteration_fdr=0.01
pyprophet peptide --in=merged.osw --context=experiment-wide
```

|   Congrats! Now we have raw chromatogram files and associated scored features in merged.osw files. Move all .chrom.mzML files in `xics` directory and merged.osw file in `osw` directory. The parent folder is given as `dataPath` to DIAlignR functions.

## Performing alignment on DIA runs
`alignTargetedRuns` function aligns Proteomics or Metabolomics DIA runs. It expects two directories "osw" and "xics" at `dataPath`. It outputs an intensity table where rows specify each analyte and columns specify runs. Use parameter `saveFiles = TRUE` to have aligned retetion time and intensities saved in the current directory.

```{r, results=FALSE, message=FALSE, warning=FALSE}
runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
          "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
params <- paramsDIAlignR()
params[["context"]] <- "experiment-wide"
# For specific runs provide their names.
alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = runs, oswMerged = TRUE, params = params)
# For all the analytes in all runs, keep them as NULL.
alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = NULL, oswMerged = TRUE, params = params)
```

## Investigating alignment of analytes

For getting alignment object which has aligned indices of XICs `getAlignObjs` function can be used. Like previous function, it expects two directories "osw" and "xics" at `dataPath`. It performs alignment for exactly two runs. In case of `refRun` is not provided, m-score from osw files is used to select reference run.
```{r, message=FALSE}
runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
          "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
AlignObjLight <- getAlignObjs(analytes = 4618L, runs = runs, dataPath = dataPath, objType	= "light", params = params)
# First element contains names of runs, spectra files, chromatogram files and feature files.
AlignObjLight[[1]][, c("runName", "spectraFile")]
obj <- AlignObjLight[[2]][["4618"]][[1]][["AlignObj"]]
slotNames(obj)
names(as.list(obj))
AlignObjMedium <- getAlignObjs(analytes = 4618L, runs = runs, dataPath = dataPath, objType	= "medium", params = params)
obj <- AlignObjMedium[[2]][["4618"]][[1]][["AlignObj"]]
slotNames(obj)
```

Alignment object has slots 
 * indexA_aligned aligned indices of reference chromatogram.
 * indexB_aligned aligned indices of experiment chromatogram
 * score cumulative score of the alignment till an index.
 * s similarity score matrix.
 * path path of the alignment through similarity score matrix.

## Visualizing the aligned chromatograms

We can visualize aligned chromatograms using `plotAlignedAnalytes`. The top figure is experiment unaligned-XICs, middle one is reference XICs, last figure is experiment run aligned to reference.
```{r, fig.width=6, fig.align='center', fig.height=6, message=FALSE}
runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
 "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
AlignObj <- getAlignObjs(analytes = 4618L, runs = runs, dataPath = dataPath, params = params)
plotAlignedAnalytes(AlignObj, annotatePeak = TRUE)
```

## Visualizing the alignment path

We can also visualize the alignment path using `plotAlignemntPath` function.
```{r, fig.width=5, fig.align='center', fig.height=5, message=FALSE}
library(lattice)
runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
 "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
AlignObjOutput <- getAlignObjs(analytes = 4618L, runs = runs, params = params, dataPath = dataPath, objType = "medium")
plotAlignmentPath(AlignObjOutput)
```


## Citation
Gupta S, Ahadi S, Zhou W, Röst H. "DIAlignR Provides Precise Retention Time Alignment Across Distant Runs in DIA and Targeted Proteomics." Mol Cell Proteomics. 2019 Apr;18(4):806-817. doi: https://doi.org/10.1074/mcp.TIR118.001132 

## Session Info
```{r}
sessionInfo()
```