---
title: "LC Observations - Retention Time Stability"
author:
- name: Tobias Kockmann
  affiliation:
    - &fgcz Functional Genomics Center Zurich - Swiss Federal Institute of Technology in Zurich
- name: Christian Trachsel
  affiliation:
    - *fgcz
- name: Christian Panse
  affiliation:
    - *fgcz
    - &sib Swiss Institute of Bioinformatics
  email: cp@fgcz.ethz.ch
- name: Bernd Roschitzki 
  affiliation:
    - *fgcz
  email: bernd.roschitzki@fgcz.uzh.ch
package: "`r pkg_ver('msqc1')`"
date: "`r Sys.Date()`"
bibliography:
  - msqc1.bib
abstract: |
  This document extends the work concerning the HPLC systems presented
  in [-@msqc1]. We refer to the original manuscript for a
  description of the theory behind applications.
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{LC Observations - Retention Time Stability}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    toc_float: true
---

<!--
%\VignetteIndexEntry{LC Observations - Retention Time Stability}
%\VignetteEngine{knitr::rmarkdown}
-->


# Introduction 

This vignette file is thought to demonstrate the retention time stability of the `msqc1_8rep` and `msqc1_dil` data contained in the `r BiocStyle::Biocpkg('msqc1')` R package.

```{r, echo = FALSE, message = FALSE}
if (!require(msqc1)){
  ## try http:// if https:// URLs are not supported
  if (!requireNamespace("BiocManager", quietly=TRUE))
      install.packages("BiocManager")
  BiocManager::install("msqc1")
}
```

## Problem: 

**Retention Time (RT) form different LC-MS platforms are often not comparable (duration, offset).**

## Solution: Normalization 

The iRT concept [proposed in pmid22577012 for the RT normalization is used.
Instead of using the iRT-peptides 
MSQC1-peptides are used as reference peptides between the different chromatographic settings and systems.

The normalization is done by applying the following steps:

- define a reference platform (QTRAP)
- for each platform a linear model is build (in the following we use the `stats::lm` function) which maps the RT space of the corresponding platform into reference platform RT space (by using the `stats::predict.lm` method)
- scale the normalized RT values into [0, 1]
- visualize the normalized RT values

The code below shows the used R functions for the applied RT normalization.


```{r}
msqc1:::.normalize_rt
```

The `reshape_rt` method is used for reshaping the data from long to wide format which ease the the model building in the `msqc1:::.normalize_rt` method above.

```{r}
msqc1:::.reshape_rt
```

The following R code listings displays some helper functions designed to ease the visualization of the `msqc1_8rep` and `msqc1_dil` RT values.

```{r}
msqc1:::.plot_rt_8rep

msqc1:::.plot_rt_dil
```


# RT plot

## 8 Technical Replicates RT plot

Prepare the training data for the linear model.
```{r echo=TRUE, fig.width=8, fig.height=8, fig.retina=3, warning=FALSE, cache=FALSE, fig.asp=1, fig.cap=''}
S.training.8rep <- msqc1:::.reshape_rt(msqc1_8rep, peptides=peptides, cex=2)
```

**8 rep Scatterplot Matrices Plot** - Color and icon type indicates the differnet peptides. On an idea plot all values would be on one line.

```{r echo=TRUE, fig.width=15, fig.height=9, fig.retina=3, warning=FALSE, fig.cap='', cache=FALSE}
msqc1:::.plot_rt_8rep(msqc1_8rep, peptides=peptides, xlab='Replicate Id')
```

**8 replicate retention time** - The graph displays the raw retention time (in minutes) versus the replicate Id of each sample. Each panel displays one LC-MS platform. On some platforms the loading phase was recorded (TRIPLETOF, QTRAP) while on the other platforms not.


The following code will apply the retention time normalization for the `msqc_8rep` data:

```{r echo=TRUE, fig.width=15, fig.height=9, fig.retina=3, warning=FALSE, cache=FALSE}
msqc1_8rep.norm <- msqc1:::.normalize_rt(msqc1_8rep, S.training.8rep, 
                                reference_instrument = 'Retention.Time.QTRAP')

msqc1:::.plot_rt_8rep(msqc1_8rep.norm,
             peptides=peptides,
             xlab='Replicate Id',
             ylab='Normalized Retention Time')
```

**Normalized 8 replicate retention time** - The graphics displays the normalized retention time for each peptide (heavy and light) across all platforms. Apart from the *TAENFR* peptide all peptides show excellent elution time stability.


## Dilution Series RT plot

```{r echo=TRUE, fig.width=8, fig.height=8, fig.retina=3, warning=FALSE, cache=FALSE, fig.asp=1, fig.cap=''}
S.training.dil <- msqc1:::.reshape_rt(msqc1_dil, peptides=peptides, cex=2)
```

**Dilution Scatterplot Matrices Plot** - Color and icon type indicates the differnet peptides. On an idea plot all values would be on one line.


The graph in  displays the raw RT (in minutes) 
versus the relative amount (x-axis in log scale) of each sample. 
Each panel displays one LC-MS platform for each isotope label typ. 
The graph on the bottom  displays the normalized RT for each peptide (heavy and light).
*Note*: Since we have used different LC settings for the dilution data as we have used for the 8 rep data, we had to rebuild the linear models for the normalization.

```{r echo=TRUE, fig.width=15, fig.height=9, fig.retina=3, warning=FALSE, cache=FALSE}
msqc1:::.plot_rt_dil(msqc1_dil, peptides, xlab='Replicate Id', ylab='Raw Retention Time')
msqc1_dil.norm <- msqc1:::.normalize_rt(msqc1_dil, 
                                        S.training.dil, 
                                        reference_instrument = 'Retention.Time.QTRAP')

msqc1:::.plot_rt_dil(msqc1_dil.norm, peptides=peptides, ylab="Normalized Retention Time")
```


## LC Gradient Comparison

The graphs compare the LC gradient of each platform by plotting the normalized RT values again the raw RT values for the `msqc1_8rep` (left) and `msqc1_dil` (right) data.

```{r echo=FALSE, fig.width=10, fig.height=5, fig.retina=3, warning=FALSE, cache=FALSE}
op <- par(mfrow=c(1,2), mar=c(4,4,1,1))


plot(msqc1_8rep.norm$Retention.Time ~ msqc1_8rep$Retention.Time, 
     pch=as.integer(msqc1_8rep.norm$Peptide.Sequence),
     col=msqc1_8rep.norm$instrument,
     xlim=c(0,100))

legend("bottomright", 
       as.character(unique(msqc1_8rep.norm$instrument)),
       col= unique(msqc1_8rep.norm$instrument), 
       pch=as.integer(unique(msqc1_8rep.norm$instrument)))

plot(msqc1_dil.norm$Retention.Time ~ msqc1_dil$Retention.Time, 
     pch=as.integer(msqc1_dil.norm$Peptide.Sequence),
     col=msqc1_dil.norm$instrument,
     xlim=c(0,100))

legend("bottomright", 
       as.character(unique(msqc1_dil.norm$instrument)),
       col= unique(msqc1_dil.norm$instrument), 
       pch=as.integer(unique(msqc1_dil.norm$instrument)))

```

# Session information

```{r, cache=FALSE}
sessionInfo()
```

# References

