---
title: "An introduction to biodbLipidmaps"
author: "Pierrick Roger"
date: "`r BiocStyle::doc_date()`"
package: "`r BiocStyle::pkg_ver('biodbLipidmaps')`"
vignette: |
    %\VignetteIndexEntry{An introduction to biodbLipidmaps}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
output:
    BiocStyle::html_document:
        toc: yes
        toc_depth: 4
        toc_float:
            collapsed: false
    BiocStyle::pdf_document: default
bibliography: references.bib
---

# Introduction

biodbLipidmaps is a *biodb* extension package that implements a connector to
Lipidmaps Structure [@sud2007_LipidMaps_LMSD].

# Installation

```{r, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install('biodbLipidmaps')
```

# Initialization

The first step in using *biodbLipidmaps*, is to create an instance of the biodb
class `BiodbMain` from the main *biodb* package. This is done by calling the
constructor of the class:
```{r, results='hide'}
mybiodb <- biodb::newInst()
```
During this step the configuration is set up, the cache system is initialized
and extension packages are loaded.

We will see at the end of this vignette that the *biodb* instance needs to be
terminated with a call to the `terminate()` method.

# Creating a connector to Lipidmaps Structure

In *biodb* connections to databases are handled by connector instances that
you can get from the factory.
Here is the code to instantiate a connector to Lipidmaps Structure database:
```{r}
conn <- mybiodb$getFactory()$createConn('lipidmaps.structure')
```

# Accessing entries

To get the number of entries stored inside the database, run:
```{r}
conn$getNbEntries()
```

To get some of the first entry IDs (accession numbers) from the database, run:
```{r}
ids <- conn$getEntryIds(2)
ids
```

To retrieve entries, use:
```{r}
entries <- conn$getEntry(ids)
entries
```

To convert a list of entries into a data frame, run:
```{r}
x <- mybiodb$entriesToDataframe(entries)
x
```

# Running the "LMSDSearch" web service

You can access the web service "LMSDSearch" directly with the *wsLmsdSearch*
method:
```{r}
ids <- conn$wsLmsdSearch(mode='ProcessStrSearch', name="fatty", retfmt="ids")
ids
```

From this list of identifiers, we can obtain the full entry objects:
```{r}
entries <- conn$getEntry(ids)
```

And then a data frame:
```{r}
entriesDf <- mybiodb$entriesToDataframe(entries)
```
That you can see in table \@ref(tab:entriesTable).

```{r entriesTable, echo=FALSE, results='asis'}
knitr::kable(entriesDf, "pipe", caption="The entries listed in the result of the search.")
```

# Closing biodb instance

When done with your *biodb* instance you have to terminate it, in order to
ensure release of resources (file handles, database connection, etc):
```{r}
mybiodb$terminate()
```

# Session information

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

# References