---
title: "1 Gathering everything you need"
author: "Adriano Rutz"
creative_commons: CC BY-SA
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
opengraph:
    image:
      src: https://github.com/taxonomicallyinformedannotation/tima/blob/main/man/figures/logo.svg
      alt: "Taxonomically Informed Metabolite Annotation"
    twitter:
      creator: "@adafede"
vignette: >
  %\VignetteIndexEntry{1 Gathering everything you need}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::opts_knit$set(root.dir = system.file(package = "tima"))
```

```{r tima, include = FALSE}
library("tima")
tima:::copy_backbone()
```
This vignette describes...

* All parameters you need
* All inputs you need

```{r change-tests, include = FALSE}
source(file = "scripts/change_tests.R")
```

## Parameters

All steps require parameters.
Some default parameters are available and can be accessed in the `params/default` directory.
If you prefer accessing them through the GUI, you can do so.
Each parameter contains a small help menu, you can click on, as illustrated below.

![Screenshot showing where the help menu is](./figures/screenshot-1.svg)\

![Screenshot showing how the help menu looks like when opened](./figures/screenshot-2.svg)\

For example, if you want to have an output compatible with Cytoscape, with multiple annotations per features:

![Screenshot showing an example box ticked](./figures/screenshot-3.svg)\

All parameters will be saved and reported at the end of your analysis.

## Inputs

### Your own files

You should provide your own files in the main menu.
For this tutorial, we will use some example files you can get running:

```{r unlink-spectra, include = FALSE}
unlink("data/source/example_spectra.mgf")
```

```{r get-files, eval=FALSE, include=TRUE}
tima::get_example_files()
```

```{r get-files-no-cache, results="hide", message=FALSE, warning=FALSE, include = FALSE}
tima::get_example_files(in_cache = FALSE)
```

### Libraries

The following paragraph describes the libraries available by default.

#### Spectra

As a first step, you need spectral libraries to perform MS^2^-based annotation.

##### Experimental

You can of course use your own experimental spectral library to perform MS^2^ annotation.
We currently support spectral libraries in MSP or MGF format.

To get a small example:

```{r spectra-rt, results="hide", message=FALSE, warning=FALSE}
tima::get_example_files("spectral_lib_with_rt")
```

###### MassBank

MassBank is downloaded and used by default.

```{r spectra-mb, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_spe_exp_mb_raw"))
```

We are currently working to get all MONA and GNPS experimental spectra easily available.

However, programmatic download of MONA is currently not supported, and GNPS spectra require some pre-processing.

So for now, either use your GNPS job ID and download MONA manually, helpers to use them later on are already available. (see `scripts/prepare_libraries_spectra_exp_mona.R`).

In case you want to format your own spectral library to use it for spectral matching, adapt the steps in `params/user/prepare_libraries_spectra.yaml` and `params/user/annotate_spectra.yaml`.

##### *In silico*

As the availability of experimental spectra is limited, we can take advantage of *in silico* generated spectra.

#### LOTUS

We generated an *in silico* spectral library of the structures found in LOTUS using [CFM4](https://doi.org/10.1021/acs.analchem.1c01465).
For more info, see <https://doi.org/10.5281/zenodo.5607185>.
It is made available in both polarities.

```{r get-isdb-lotus, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_spe_is_lot"))
```

```{r prepare-isdb-lotus-1, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_spe_is_lot_pre"))
```

You can also complement with the in silico spectra from HMDB (not running by default as quite long):

#### HMDB

```{r get-isdb-hmdb, eval=FALSE, include=TRUE}
tima::get_example_files("hmdb_is")
```

#### Retention times

This library is **optional**.
As no standard LC method is shared (for now) among laboratories, this library
will be heavily laboratory-dependent.
It could also be a library of in silico predicted retention times.
If you want to prepare you own library, have a look at `params/user/prepare_libraries_rt.yaml`.

#### Structure-Organism Pairs

##### LOTUS

As we developed [LOTUS](https://lotusnprod.github.io/lotus-manuscript)^[For more informations, see <https://doi.org/10.7554/eLife.70780>] with
**T**axonomically
**I**nformed
**M**etabolite
**A**nnotation in mind,
we provide it here as a starting point for your structure-organism pairs library.

```{r get-lotus, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_sop_lot$"))
```

```{r prepare-lotus-2, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_sop_lot_pre"))
```

The process to download LOTUS looks like this:

```{r prepare-lotus-3, echo=FALSE, message=FALSE, warning=FALSE, out.width="100%"}
targets::tar_visnetwork(
  names = tidyselect::matches("lib_sop_lot"),
  exclude = c(
    tidyselect::contains("benchmark"),
  ),
  targets_only = TRUE,
  degree_from = 8
)
```

As you can see, one target seems outdated.
In reality, we force it to search if a new version of LOTUS exists each time.
If a newer version exists, it will fetch it and re-run needed steps accordingly.

##### ECMDB

By default, we also complement LOTUS pairs with the ones coming from [ECMDB](https://ecmdb.ca/).

```{r prepare-ecmdb-1, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_sop_ecm_pre"))
```

##### HMDB

And we do the same with the ones coming from [HMDB](https://hmdb.ca/).

```{r prepare-hmdb, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_sop_hmd_pre"))
```

For these first steps, you do not need to change any parameters as they are implemented *by default*.

##### Other libraries

As we want our tool to be flexible, you can also add your own library to LOTUS.
You just need to format it in order to be compatible.
As example, we prepared some ways too format closed, *in house* libraries.
If you need help formatting your library or would like to share it with us for it to be implemented, feel free to contact us.
Before running the corresponding code, do not forget to modify `params/user/prepare_libraries_sop_closed.yaml`.

##### Merging

Once all sub-libraries are ready, they are then merged in a single file that will be used for the next steps.

```{r libraries-sop-1, results="hide", message=FALSE, warning=FALSE, include = FALSE}
targets::tar_make(names = tidyselect::matches("lib_sop_mer"))
```

```{r libraries-sop-2, echo=FALSE, message=FALSE, warning=FALSE, out.width="100%"}
targets::tar_visnetwork(
  names = starts_with("lib_sop"),
  exclude = c(
    tidyselect::contains("benchmark"),
    tidyselect::contains("par_"),
    tidyselect::contains("paths")
  ),
  targets_only = TRUE,
  degree_from = 8
)
```

We now recommend you to read the [next vignette](https://taxonomicallyinformedannotation.github.io/tima/articles/II-preparing.html).
