---
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}
knitr::opts_chunk$set(echo = TRUE, message = FALSE)
library(BiocStyle)
BiocStyle::markdown()
```

# Introduction

The `r Biocpkg("Spectra")` package provides a central infrastructure for Mass
Spectrometry (MS) data in R. The package supports interchangeable use of
different *backends* to represent or import MS data from a variety of formats
and sources (such as mzML files). The *MsBackendTimsTof"* package adds support
for MS data from 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). This support is
provided by the *opentimsr* R package, which gets installed as a dependency when
installing *MsBackendTimsTof*:

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

Some variables in the data files can only be accessed after setting up a
converter library. Two options are available.
The first is to use the open-source library built into *opentimsr*:

```{r setup-opensource, eval = FALSE}
library(MsBackendTimsTof)

setup_converter_library()
```

The `setup_converter_library()` function is also run on package startup hence,
to use the default, no manual call to `setup_converter_library()` is needed.

Alternatively it is possible to use the proprietary Bruker converter library,
which can be downloaded and cached through *BiocFileCache* or downloaded to a
personal folder. Note that this library is currently **only available for
Windows and Linux** (no macOS support).

```{r setup-bruker, eval = FALSE}
setup_converter_library(opensource = FALSE)
```

# 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 which
will also automatically setup the use of the open-source converter library.

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

We next load the TDF test file which is bundled within this package using the
`Spectra()` constructor function specifying to use a `MsBackendTimsTof` as data
backend with parameter `source`.

```{r initialize}
## Get the path/file name of the example file
fl <- system.file("ddaPASEF.d", package = "MsBackendTimsTof")

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

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

```{r spectra-variables}
spectraVariables(sps)
```

And the full data for spectra variables can be retrieved with `spectraData`:

```{r full-spectra-data}
all <- spectraData(sps)
all
```

The data is organized by individual spectra, all spectra measured within the
same *frame* have the same value in the spectra variable `"frameId"`. This also
means that the `scanIndex` is **not** unique within a file, only within one
*frame*:

```{r duplicated-scan}
sps$scanIndex |> anyDuplicated()
```

The combination of `frameId` and `scanIndex` identifies each spectrum uniquely
within the same file:

```{r frame-scan}
spectraData(sps, c("frameId", "scanIndex", "file"))
```

The *inverse ion mobility* data is provided by the `"inv_ion_mobility"`
variable. This information can be extracted as a *spectra variable* (i.e.,
one value per spectrum):

```{r ion-mobility-spectra-variable}
## Get the ion mobility information
sps$inv_ion_mobility |> head()
```

But can also be requested to be added to the `peaksData()`. Below we extract the
full peaks data (i.e., all *peaks variables* for all spectra) and show the
information of one selected spectrum:

```{r peaks-data}
## Request all supported peaks variables
pd <- peaksData(sps, peaksVariables(sps))
## Show the data for the spectrum number 10
pd[[10L]]
```

In addition to the default `"mz"` and `"intensity"` columns with the individual
peaks' m/z and intensity values many more columns are reported.

Note however that `"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.

Each of the `Spectra` object represents the signal from a single *scan* within a
TimsTOF *frame*. Thus, in TimsTOF data we have multiple spectra for the same
retention time (frame). Below we plot the first 4 spectra from the first frame.

```{r plot-spectra-frame}
plotSpectra(sps[1:4])
```

The first 3 spectra contain only a single peak, the spectrum number 4 2
peaks. All of them are recorded in the same *frame*, with the same retention
time, but a different inverse ion mobility time:

```{r spectra-data-first-four}
spectraData(sps[1:4], columns = c("frameId", "scanIndex",
                                  "rtime", "inv_ion_mobility"))
```

This first frame has `r sum(sps$frameId == 1L)` spectra, all with the same
retention time, but different inverse ion mobility time.

We can also *collapse* the ion mobility time dimension of the `Spectra` object
to simulate and generate a *classical* LC-MS data with one spectrum per
retention time. This can be done using the `combineSpectra()` from the *Spectra*
package. Below we first define a factor to assign all spectra from the same
frame (and original data file) to one *spectra group* that should be combined
into a single spectrum.

```{r combine-spectra-factor}
## Define a factor assigning all spectra from the same frame to one group
f <- paste0(sps$frameId, sps$dataOrigin)
```

We can now combine the spectra within each such defined group using
`combineSpectra()`. With parameter `peaks = "union"` we merge all mass (or
fragment) peaks of all spectra per group into the representative spectrum. Peaks
with a difference in their *m/z* smaller than 10 ppm (parameter `ppm = 10`) are
reported as a single peak, with the median *m/z* reported as its *m/z* (`mzFun =
median`) and the largest intensity as the peak's intensity (`intensityFun =
max`; see also the help pages for `combineSpectra()` and `combinePeaksData()`
for other options and parameters).

```{r combine-spectra}
## Combine all spectra per frame into a single spectrum
sps_merged <- combineSpectra(sps, f = f, peaks = "union", ppm = 10,
                             mzFun = median, intensityFun = max)
sps_merged
```

There is now one spectrum per frame. Below we plot the (MS1) spectrum from the
first frame.

```{r combine-spectra-plot}
plotSpectra(sps_merged[1L])
grid()
```

Importantly, for each such combined spectrum the metadata of its **first**
spectrum is reported (in this case the first spectrum per frame).

```{r spectra-data-combined}
spectraData(sps_merged)
```

Also, `combineSpectra` returns a `Spectra` object with an *in-memory* backend,
hence all data is loaded into memory. The original `MsBackendTimsTof` however is
an *on-disk* backend, which reads 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 add-variable}
## Add a new spectra variable
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 show-variables}
spectraVariables(sps)
sps$new_variable |> head()
```

Analogously it is also possible to change existing spectra variables. Below we
shift each retention time by 10 seconds.

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


# Session information

```{r session-information}
sessionInfo()
```