---
title: "Intro to AutoTuner"
author: Craig McLean
date: August 1, 2019
output:
  html_document:
    toc: yes
  pdf_document:
    toc: yes
  prettydoc::html_pretty:
    highlight: github
    theme: lumen
    toc: yes
vignette: >
  %\VignetteIndexEntry{Autotuner}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

AutoTuner is a parameter tuning algorithm for XCMS, MZmine2, and other 
metabolomics data processing softwares. Using statistical inference, AutoTuner
quickly finds estimates for nine distinct parameters. This guide provides
an interactive example of how to use AutoTuner.

# Installation

## Dev Version

Currently, AutoTuner is being distributed through my github acount [here]:
github.com/crmclean/Autotuner

The easiest way to download that package is by using the install_github command
from the devtools package as illustrated below.

```{r dev installation, eval=FALSE}
devtools::install_github("crmclean/Autotuner")
```

## Bioconductor Release

Hopefully the package will be available through bioconductor in the near future.
Once this occurs, the package may be downloaded by running the following code.

```{r BioC installation, eval=FALSE}
if(!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("Autotuner")
```

# Autotuner

This tutorial uses additional data from the package, mtbls2 This second
package contains raw untargeted metabolomics data, and may be downloaded from
bioconductor in a manner as the BioC installation for Autotuner.

```{r setup, warning=FALSE}
library(Autotuner)
library(mtbls2)  
```



## Set Up

### Input - Raw Data

AutoTuner is designed to work directly with raw mass spectral data that has 
been processed by using MSconvert. So far file types .mzML, .mzXML, .msData, 
and .netCDF have been tested and confirmed to work. 

```{r loading mass spec data}
rawPaths <- c(
    system.file("mzData/MSpos-Ex2-cyp79-48h-Ag-1_1-B,3_01_9828.mzData", 
                             package = "mtbls2"),
system.file("mzData/MSpos-Ex2-cyp79-48h-Ag-2_1-B,4_01_9830.mzData", 
            package = "mtbls2"),
system.file("mzData/MSpos-Ex2-cyp79-48h-Ag-4_1-B,4_01_9834.mzData", 
            package = "mtbls2"))

if(!all(file.exists(rawPaths))) {
    stop("Not all files matched here exist.")
}
```

Here are the filetypes that will be used within this tutorial:

```{r filetype}
print(basename(rawPaths))
```

Here are what the paths look like that I am entering into AutoTuner directly:

```{r}
print(rawPaths)
```


### Input - Metadata

AutoTuner also requires a metadata file that has at least two columns 
in order to derive estimates. One column should contain string matches to all
the raw data files that will be processed (see above for an example). The 
second should contain information on the experimental factor each sample belongs
to. 

```{r loading in metadata}
metadata <- read.table(system.file(
    "a_mtbl2_metabolite_profiling_mass_spectrometry.txt", 
    package = "mtbls2"), header = TRUE, stringsAsFactors = FALSE)

metadata <- metadata[sub("mzData/", "", metadata$Raw.Spectral.Data.File) %in% 
                         basename(rawPaths),]
```

This is what the metadata file should look like. In our case, the column 
matching the raw data files is called "File.Name", while the one with 
experimental factor information is called "Sample.Type".

```{r}
print(metadata)
```

## Creating AutoTuner Object

AutoTuner first requires that user create an AutoTuner object. All future
computations will be contained within this object. 

The file_col argument corresponds to the string column of the metadata that 
matches raw data samples by name. The factorCol argument corresponds to the 
metadata column containing information about which experimental factor each
sample belongs to. 

```{r}
Autotuner <- createAutotuner(rawPaths,
                             metadata,
                             file_col = "Raw.Spectral.Data.File",
                             factorCol = "Factor.Value.genotype.")
```

## Part 1: 

**Total Ion Current Peak Identification**

The first part of AutoTuner involves the identification of peaks within the
total ion current (TIC) of the samples loaded up into AutoTuner. These regions 
will be important later to estimate parameters 
from the raw data since AutoTuner assumes that they contain 
a greater number of real chemical measurements. 

### Sliding Window Analysis

To do this, the user peforms a sliding window analysis. A sliding window
analysis is a simple time series analysis algorithm used to identify peaks 
within a time trace. The window is essentially using a moving average. From
this, the algorithm asks whether the next observation to the 
right of the average is a peak. More on sliding window 
analyses can be found [here](https://en.wikipedia.org/wiki/Moving_average).

The aim here is to identify TIC peaks. The user should 
prioritize finding where peaks *start* rather than caturing the entire peak 
bound. Downstream steps actually do a better job of estimating what the proper
peak bounds should be. 

The user should play with the lag, threshold, and influence parameters to 
perform the sliding window analysis. Here is what they represent relative to
chromatography:

Lag - The number of chromatographic scan points used to test if next point is
significance (ie the size number of points making up the moving average). 

Threshold - A numerical constant representing how many times greater the 
intensity of an adjacent scan has to be from the scans in the sliding window
to be considered significant. 

Influence - A numerical factor used to scale the magnitude of a significant scan
once it has been added to the sliding window. 

```{r}
lag <- 25
threshold<- 3.1
influence <- 0.1
signals <- lapply(getAutoIntensity(Autotuner), 
                 ThresholdingAlgo, lag, threshold, influence)
```

The output of the sliding window can be displayed with the plot_signals
function:

```{r plotting TIC, ig.width=6, fig.height=4}
plot_signals(Autotuner, 
             threshold, 
             ## index for which data files should be displayed
             sample_index = 1:3, 
             signals = signals)
rm(lag, influence, threshold)
```

#### Interpreting Sliding Window Results

The figure above has two components:

1) Top Plot: The chromatotgraphic trace for each sample (solid line) along
with the noise associated with each sample (dashed line). 
2) Bottom Plot: A signal plot used to indicate which chromatographic 
regions have peaks.

The user should look for combinations of the three sliding window parameters 
that returns many narrow peaks within the signal plot. See the example above.

Autotuner will expand each of these regions to obtain improved estimates on the
bounds within the isolatePeaks function below. The return_peaks arguement there
represents the number of peaks to return from all detected TIC peaks for 
parameter estimation. This number is bounded by the total number of detected 
peaks by the sliding windown analysis above, so seeing more narrow peaks within 
the signal plot is recommended. 

```{r}
Autotuner <- isolatePeaks(Autotuner = Autotuner, 
                          returned_peaks = 10, 
                          signals = signals)
```

### Checking Peak Estimates

The peaks with expanded bounds returned from the isolatePeaks function can be 
rapidly checked visually using the plot_peaks function as shown below. 
The bounds should capture the correct ascention and descention points of each 
peak. If peak bounds are not satisfactory, the user should return to the 
sliding window analysis, and try a different conbination of the three 
parameters.

Remember, this whole process is only designed to isolate regions enriched in 
real features rather than find true peaks. The bounds don't need to be
completely perfect. Its much more important that the bounds contain some kind 
of chromatographic peaks rather than less dynamic regions of the chromatographic
trace.

```{r}
for(i in 1:5) {
    plot_peaks(Autotuner = Autotuner, 
           boundary = 100, 
           peak = i)    
}
```

## Part 2: 

**Parameter Extraction from Individual Extracted Ion Chromatograms**

In order to estimate parameters from the raw data, the user should run the 
EICparams function as below. The massThreshold is an absolute mass error that
should be greater than the expected analytical capabilities of the mass 
analyzer. This part of the analysis might take a 
few minutes if the data used is large (~ 100 Mb per sample).

If returnPpmPlots is True, AutoTuner will return plots showing how the ppm 
threshold was estimated within the current working directory running Autotuner. 
This can be used to evaluate the magnitude of the massThreshold parameter.

```{r}
## error with peak width estimation
## idea - filter things by mass. smaler masses are more likely to be 
## random assosications
eicParamEsts <- EICparams(Autotuner = Autotuner, 
                          massThresh = .005, 
                          verbose = FALSE,
                          returnPpmPlots = FALSE,
                          useGap = TRUE)
```

## Part 3: 

**Returning Estimates**

All that remains now is to get what the dataset estimates are.

```{r}
returnParams(eicParamEsts, Autotuner)
```

There you have it! Running AutoTuner is now complete, and the estimates may be
entered directly into XCMS to processes raw untargeted metabolomics data.

# Session Info

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

