---
title: "Description and usage of MsBackendTimsTof"
output:
    BiocStyle::html_document:
        toc_float: true
vignette: >
    %\VignetteIndexEntry{Description and usage of MsBackendTimsTof}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
    %\VignettePackage{MsBackendTimsTof}
    %\VignetteDepends{Spectra,BiocStyle,BiocParallel}
---

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

**Package**: `r Biocpkg("MsBackendTimsTof")`<br />
**Authors**: `r packageDescription("MsBackendTimsTof")[["Author"]] `<br />
**Compiled**: `r date()`

```{r, echo = FALSE, message = FALSE}
library(Spectra)
library(BiocStyle)
```

# Introduction

The `r Biocpkg("Spectra")` package provides a central infrastructure for the
handling of Mass Spectrometry (MS) data. The package supports interchangeable
use of different *backends* to import MS data from a variety of sources (such as
mzML files). The `r Biocpkg("MsBackendTimsTof")` package adds support for Bruker
TimsTOF raw data files. This vignette shows how, and which data can be retrieved
from such files.


# Installation

The package depends on the [OpenTIMS](https://github.com/michalsta/opentims) C++
library to access data in timsTOF Pro data format (TDF) which is provided by the
`opentimsr` R package. The `MsBackendTimsTof` package can be installed with:

```{r, eval = FALSE}
BiocManager::install("RforMassSpectrometry/MsBackendTimsTof")
```

To get some variables from the data files an additional library from the
manufacturer is needed. This library can be downloaded with:

```{r, eval = FALSE}
so_folder <- tempdir()
library(opentimsr)
so_file <- download_bruker_proprietary_code(so_folder)
```

This downloads the shared library to a temporary folder. Note however that at
present this shared library is **only available for Windows and Linux** (i.e. no
macOS support). Next, to use this library, it has to be registered with the
`opentimsr` package:

```{r, eval = FALSE}
setup_bruker_so(so_file)
```

These steps would be necessary for every new R session. To avoid that, it is
suggested to copy the downloaded shared library above to a directory on the
computer and to define an environment variable called `TIMSTOF_LIB` that defines
the full path where this file is located (i.e. a character string defining the
full file path with the file name). This variable can either be defined system
wide, or within the *.Rprofile* file. An example entry in a *.Rprofile* could
for example be:

```
options(TIMSTOF_LIB = "/home/jo/lib/libtimsdata.so")
```


# Accessing data from Bruker TimsTOF files

The `r Biocpkg("MsBackendTimsTof")` package adds support for Bruker TimsTOF
files to `Spectra`-based analysis workflows. Below we load the package and in
addition fetch the required shared library and store that to a temporary folder.

```{r, message = FALSE}
library(MsBackendTimsTof)

## Load the opentimsr package and download and register the shared library
library(opentimsr)
so_folder <- tempdir()
so_file <- download_bruker_proprietary_code(so_folder, method = "wget")
setup_bruker_so(so_file)
```

As detailed in the installation section, the code to download the shared library
would only be necessary once, if the path to this file is defined in a
environment variable `TIMSTOF_LIB`.

We next load the TDF test file which is bundled within this package.

```{r}
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")

be <- backendInitialize(MsBackendTimsTof(), fl)
```

In a real use case, we would however directly load the data into a `Spectra`
object:

```{r}
sps <- Spectra(fl, source = MsBackendTimsTof())
sps
```

We thus have access to all spectra variables within the file:

```{r}
spectraVariables(be)
```

And the full data can be retrieved with `spectraData`:

```{r}
all <- spectraData(be)
all
```

The data is organized by individual spectra, all spectra measured within the
same *frame* have the same value in the spectra variable `"frameId"`. Spectra
variable `"inv_ion_mobility"` provides the *inverse ion mobility*
information. This variable is available as a spectra variable, but also as a
*peaks variable* along with e.g. `"tof"`. Available peaks variables can be
listed with the `peaksVariables` function.

```{r}
peaksVariables(sps)
```

Below we subset the backend to a range of spectra and extract their `peaksData`.

```{r}
sps_sub <- sps[224:227]
peaksData(sps_sub, columns = c("mz", "intensity", "tof", "inv_ion_mobility",
                               "retention_time")) |> as.list()
```

Note however that both the `"inv_ion_mobility"` and `"retention_time"` have the
same value for all peaks in each spectrum. Thus, these variables should be
accessed not through `peaksData`, but through `spectraData` or using the `$`
operator or the dedicated `rtime` function. Below we extract the inverse ion
mobility values and display the first 6 of them.

```{r}
head(sps$inv_ion_mobility)
```

The `MsBackendTimsTof` is a *on-disk* backend, hence reading peaks and spectra
variables from the original data file(s) upon request. Modifying spectra
variables within the raw data files is not possible (and also not desired), but,
by directly extending the `MsBackendCached` backend from the
`r Biocpkg("Spectra")` package `MsBackendTimsTof` supports changing or adding
spectra variables by *caching* them locally within the object. Below we add a
new spectra variable to the object.

```{r}
sps$new_variable <- seq_along(sps)
```

This new variable is now available within the object and can be extract like
any other spectra variable.

```{r}
spectraVariables(sps)
sps$new_variable |> head()
```

Analogously it is also possible to change existing spectra variables. Below we
add a value to each retention time.

```{r}
rtime(sps) |> head()
sps$rtime <- rtime(sps) + 10
rtime(sps) |> head()
```


# Session information

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