---
title: "Core Utils for Metabolomics Data"
package: MetaboCoreUtils
output:
  BiocStyle::html_document:
    toc_float: true
vignette: >
  %\VignetteIndexEntry{Core Utils for Metabolomics Data}
  %\VignetteEngine{knitr::rmarkdown}
  %%\VignetteKeywords{Mass Spectrometry, MS, MSMS, Metabolomics, Infrastructure, Quantitative }
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
---

```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown()
```

**Package**: `r BiocStyle::Biocpkg("MetaboCoreUtils")`<br />
**Authors**: `r packageDescription("MetaboCoreUtils")[["Author"]] `<br />
**Last modified:** `r file.info("MetaboCoreUtils.Rmd")$mtime`<br />
**Compiled**: `r date()`

# Introduction

The `MetaboCoreUtils` defines metabolomics-related core functionality provided
as low-level functions to allow a data structure-independent usage across
various R packages [@rainer_modular_2022]. This includes functions to calculate between ion (adduct)
and compound mass-to-charge ratios and masses or functions to work with chemical
formulas. The package provides also a set of adduct definitions and information
on some commercially available internal standard mixes commonly used in MS
experiments.

For a full list of function, see

```{r, message = FALSE}
library("MetaboCoreUtils")
ls(pos = "package:MetaboCoreUtils")
```

or the [reference
page](https://rformassspectrometry.github.io/MetaboCoreUtils/reference/index.html)
on the package webpage.


# Installation

The package can be installed with the `BiocManager` package. To
install `BiocManager` use `install.packages("BiocManager")` and, after that,
`BiocManager::install("MetaboCoreUtils")` to install this package.


# Examples

The functions defined in this package utilise basic classes with the
aim of being reused in packages that provide a more formal, high-level
interface.

The examples below demonstrate the basic usage of the functions from the
package.

```{r}
library(MetaboCoreUtils)
```


## Conversion between ion m/z and compound masses

The `mass2mz` and `mz2mass` functions allow to convert between compound masses
and ion (adduct) mass-to-charge ratios (m/z). The `MetaboCoreUtils` package
provides definitions of common ion adducts generated by electrospray ionization
(ESI). These can be listed with the `adductNames` function.

```{r}
adductNames()
```

With that we can use the `mass2mz` function to calculate the m/z for a set of
compounds assuming the generation of certain ions. In the example below we
define masses for some theoretical compounds and calculate their expected m/z
assuming that ions `"[M+H]+"` and `"[M+Na]+"` are generated.

```{r}
masses <- c(123, 842, 324)
mass2mz(masses, adduct = c("[M+H]+", "[M+Na]+"))
```

As a result we get a `matrix` with each row representing one compound and each
column the m/z for one of the defined adducts. With the `mz2mass` we could
perform the reverse calculation, i.e. from m/z to compound masses.

In addition, it is possible to calculate m/z values from chemical formulas with
the `formula2mz` function. Below we calculate the m/z values for `[M+H]+` and
`[M+Na]+` adducts from the chemical formulas of glucose and caffeine.

```{r}
formula2mz(c("C6H12O6", "C8H10N4O2"), adduct = c("[M+H]+", "[M+Na]+"))
```


## Working with chemical formulas

The lack of consistency in the format in which chemical formulas are written
poses a big problem comparing formulas coming from different resources. The
`MetaboCoreUtils` package provides functions to *standardize* formulas as well
as combine formulas or substract elements from formulas. Below we use an
artificial example to show this functionality. First we standardize a chemical
formula with the `standardizeFormula` function.

```{r}
frml <- "Na3C4"
frml <- standardizeFormula(frml)
frml
```

Next we add `"H2O"` to the formula using the `addElements` function.

```{r}
frml <- addElements(frml, "H2O")
frml
```

We can also substract elements with the `subtractElements` function:

```{r}
frml <- subtractElements(frml, "H")
frml
```

Chemical formulas could also be multiplied with a scalar using the
`multiplyElements` function. The counts for individual elements in a chemical
formula can be calculated with the `countElements` function.

```{r}
countElements(frml)
```

The function `adductFormula` allows in addition to create chemical formulas of
specific adducts of compounds. Below we create chemical formulas for `[M+H]+`
and `[M+Na]+` adducts for glucose and caffeine.

```{r}
adductFormula(c("C6H12O6", "C8H10N4O2"), adduct = c("[M+H]+", "[M+Na]+"))
```


## Kendrick mass defect calculation

Lipids and other homologous series based on fatty acyls can be found in data by
using Kendrick mass defects (KMD) or referenced kendrick mass defects
(RKMD). The `MetaboCoreUtils` package provides functions to calculate everything
around Kendrick mass defects. The following example calculates the KMD and RKMD
for three lipids (PC(16:0/18:1(9Z)), PC(16:0/18:0), PS(16:0/18:1(9Z))) and
checks, if they fit the RKMD of PCs detected as [M+H]+ adducts.

```{r}
lipid_masses <- c(760.5851, 762.6007, 762.5280)
calculateKmd(lipid_masses)
```

Next the RKMD is calculated and checked if it fits to a specific range. RKMDs
are either 0 or negative integers according to the number of double bonds in the
lipids, e.g. -2 if two double bonds are present in the lipids.

```{r}
lipid_rkmd <- calculateRkmd(lipid_masses)
isRkmd(lipid_rkmd)
```


## Retention time indexing

Retention times are often not directly comparable between two LC-MS systems,
even if nominally the same separation method is used. Conversion of retention
times to retetion indices can overcome this issue. The `MetaboCoreUtils` package
provides a function to perform this conversion. Below we use an example based on
indexing with a homologoues series af N-Alkyl-pyridinium sulfonates (NAPS).

```{r}
rti <- read.table(system.file("retentionIndex",
                              "rti.txt",
                              package = "MetaboCoreUtils"),
                  header = TRUE,
                  sep = "\t")

rtime <- read.table(system.file("retentionIndex",
                                "metabolites.txt",
                                package = "MetaboCoreUtils"),
                    header = TRUE,
                    sep = "\t")
```

A `data.frame` with the retetion times of the NAPS and their respective index
value is required.

```{r}
head(rti)
```


The indexing is peformed using the function `indexRtime`.

```{r}
rtime$rindex_r <- indexRtime(rtime$rtime, rti)
```

For comparison the manual calculated retention indices are included.

```{r}
head(rtime)
```

Conditions that shall be compared by the retention index might not perfectly
match. In case the deviation is linear a simple two-point correction can be
applied to the data. This is performed by the function `correctRindex`. The
correction requires two reference standards and their measured RIs and reference
RIs.

```{r}
ref <- data.frame(rindex = c(1709.8765, 553.7975),
                  refindex = c(1700, 550))

rtime$rindex_cor <- correctRindex(rtime$rindex_r, ref)
```



# Contributions

If you would like to contribute any low-level functionality, please
[open a GitHub
issue](https://github.com/RforMassSpectrometry/MetaboCoreUtils/issues) to
discuss it. Please note that any
[contributions](https://rformassspectrometry.github.io/RforMassSpectrometry/articles/RforMassSpectrometry.html#contributions)
should follow the [style
guide](https://rformassspectrometry.github.io/RforMassSpectrometry/articles/RforMassSpectrometry.html#coding-style)
and will require an appropriate unit test.


If you wish to reuse any functions in this package, please just go
ahead. If you would like any advice or seek help, please either [open
a GitHub
issue](https://github.com/RforMassSpectrometry/MetaboCoreUtils/issues).


# Session information {-}

```{r sessioninfo, echo=FALSE}
sessionInfo()
```

# References