---
title: "Introduction to MetaboAnnotatoR"
author: "Gonçalo Graça"
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
    number_sections: true
vignette: >
  %\VignetteIndexEntry{Introduction to MetaboAnnotatoR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

MetaboAnnotatoR is designed to perform metabolite annotation of features from
LC-MS All-ion fragmentation (AIF) datasets, using ion fragment databases.
It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode.

# Installation

To install this package, start R (version "4.5.0" or higher) and enter:
```{r installation, eval=FALSE, echo=TRUE, message=FALSE}
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("MetaboAnnotatoR")
```


# Example session

An example of feature annotation using LC-MS AIF chromatograms processed 
using xcms and RamClustR packages is illustrated here.
The details of how the example dataset was obtained check MetaboAnnotatoR
original paper for the full details: 
https://pubs.acs.org/doi/10.1021/acs.analchem.1c03032.

For more details on RAMClustR object, check the original publication:
https://pubs.acs.org/doi/10.1021/ac501530d.  

Firstly load library and dependencies:

```{r load_package, eval=TRUE, echo=TRUE, message=FALSE}
library(MetaboAnnotatoR)
```

## Feature table and data

As an input, MetaboAnnotatoR requires a data frame containing the features to
be annotated and either a raw AIF LC-MS chromatogram (as .mzML or CDF) or a 
processed dataset composed of two objects: 
RAMClustR (object containing the pseudo-MS/MS spectra) and 
an XCMS object containing the peak-picked data. 
Additionally, the fragment libraries need to be specified.

Firstly a data table (targets) containing one feature to annotate needs to be 
loaded. There is an example feature table in MetaboAnnotatoR 
(*targetTable.csv*) that it will be used in this example.

```{r features, eval=TRUE, echo=TRUE, message=FALSE}
tfile <- system.file("extdata", "targetTable.csv", package="MetaboAnnotatoR")
targets <- read.csv(tfile)
```

This table contains 6 features from a LC-MS Lipidomics (ESI+) chromatogram
to be annotated.

The example in this vignette will use of processed data, included in the 
package. These consist of:
1) an *xcmsSet* object (*xset*) containing the processed data from 100 
AIF LC-MS chromatograms from human serum samples and 
2) the respective pseudo-MS/Ms spectra obtained by processing the 
*xcmsSet* data using RAMClustR (*RC*). 
The data can be loaded as followed:

```{r load_data, eval=TRUE}
data("xset")
data("RC")
```

## Annotations

Since the features come from a ESI+ lipidomics experiment, annotation can be 
performed using the default Lipid Positive mode libraries
"*LipidPos*". For this, the default Lipid Positive libraries must be first 
loaded into the workspace:
```{r libraries, eval=TRUE}
data("LipidPos")
```

Then annotations can be performed using the *annotateRC* function.
The results will be stored in an object (*annotations* ):

```{r lipid_pos_example, eval=TRUE}
annotations <- annotateRC(targets, xcmsObject=xset, ramclustObj=RC, 
                            libs="LipidPos")
```

The most significant annotations (rank 1 annotations) for each feature are 
summarised in the global results object within the *annotations* object:

```{r global, eval=TRUE}
annotations$global
```

Three out of the six features were annotated with to a lipid.

It is also possible to inspect if there were other candidate annotations for
a given feature, for instance feature 3: 468.3095 m/z,  82.92009 s.
This information can be accessed from the *rankedResult* object stored
in the *annotations*. For feature 3, it is accessed as follows:

```{r ranked, eval=TRUE}
annotations$rankedResult[[3]]
```

The rank 1 annotation is LPC(14:0). However, it is also possible to see this
feature could also be annotated (although with lower score and hence 
confidence) to fragments of several PCs that also contain the 14:0 fatty acyl 
chain.

It is possible to visualise the spectra containing the matched ions to each
candidate. The example code below will plot the rank 1 candidate for the
annotation of the 3rd feature of the targets table:

```{r plot_result_spectrum, eval=TRUE}
plotResultSpec(annotations, 3, 1)
```

## Save the annotations

It is possible to save the annotation results to a user-specified directory.
By default, the global annotations are saved specified directory. 
The annotation options can be also saved, as well as the pseudo-MS/MS spectra
of each matched candidate will be saved (as .pdf) and any pseudo-MS/MS spectra
as (.mgf file). 
For this examples we'll make use of a temporary directory. 

```{r save_results, eval=TRUE}
exampleDir <- tempdir()
saveAnnotations(annotations, DirPath=exampleDir, saveOptions=TRUE, 
                saveXCMSoptions=FALSE, saveRanked=TRUE,
                saveRankedSpec=TRUE, savePseudoMSMS=TRUE)

```

# Session Info

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