---
title: "miRBaseVersions.db-vignette"
author: "Stefan Haunsberger"
date: "`r Sys.Date()`"
output: 
  pdf_document:
    toc: yes
bibliography: references.bib
csl: "apa.csl"
vignette: >
  %\VignetteIndexEntry{miRBaseVersions.db-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- output:
  pdf_document:
    toc: yes --> 

```{r highlight = FALSE, echo=FALSE, results='hide'}
suppressPackageStartupMessages(require(AnnotationDbi))
```

The [miRBase](http://www.mirbase.org) database [@Griffiths-Jones01012004; 
@Griffiths-Jones01012006; @Griffiths-Jones01012008; @Kozomara01012011; 
@Kozomara01012014] is the official repository for miRNAs and includes a miRNA 
naming convention [@AMBROS01032003; @meyers2008criteria].
Over the years of development miRNAs have been added to, or deleted from the 
database, while some miRNA names have been changed. As a result, each version 
of the miRBase database can differ substantially from previous versions. 

The _miRBaseVersions.db_ R package has been developed to provide an easy 
accessible repository for several different miRBase release versions.
  
## 1. Introduction

The _miRBaseVersions.db_ package is an annotation package which includes 
mature miRNA names from 21 miRBase release versions. Due to ongoing growth and 
changes with each release miRNA names can have different names in different 
versions or even are not listed as valid miRNAs anymore. This annotation package
serves as a repository and can be used for quick lookup for mature miRNA names. 
The _miRBaseVersions.db_ package has implemented the AnnotationDbi-select 
interface. By implementing this `select` interface the user is able to use 
the same methods as for any other annotation package.

The main four implemented methods are 

- `columns`, presents the values one can retrieve in the final result,
- `keytypes`, which presents the tables that can be used in this package,
- `keys`, is used to get viable keys of a particular `keytype` and
- `select`, which is used to extract data from the annotation package by using 
values provided by the other three methods.

To load the package and gain access to the functions just run the 
following command:

```{r highlight = TRUE}
library(miRBaseVersions.db)
```

### Vignette Info

This vignette has been generated using an R Markdown file with 
`knitr:rmarkdown` as vignette engine [@bibtex; @knitr1; @knitr2; @knitr3; 
@knitcitations].

### Database information

The data is the 
_miRNAmeConverter_ package is stored in an SQLite database. All entries 
contained in the database were downloaded from the 
[miRBase ftp-site](ftp://mirbase.org/pub/mirbase/). The following versions 
are available:


|miRBase Version | # Mature Entries|Release Date |
|---------------:|----------------:|------------:|
|6.0             |        1591     |04/05        |
|7.1             |        3101     |10/05        |
|8.0             |        3228     |02/06        |
|8.1             |        3684     |05/06        |
|8.2             |        3834     |07/06        |
|9.0             |        4167     |10/06        |
|9.1             |        4274     |02/07        |
|9.2             |        4430     |05/07        |
|10.0            |        5395     |08/07        |
|10.1            |        5718     |12/07        |
|11.0            |        6703     |04/08        |
|12.0            |        9110     |09/08        |
|13.0            |        10097    |03/09        |
|14.0            |        11663    |09/09        |
|15.0            |        15632    |04/10        |
|16.0            |        17341    |08/10        |
|17.0            |        19724    |04/11        |
|18.0            |        21643    |11/11        |
|19.0            |        25141    |08/12        |
|20.0            |        30424    |06/13        |
|21.0            |        35828    |06/14        |

from 228 organisms.


## 2. Use Cases

### 2.1 Function `keytypes`

Use this function to receive table names from where data can be retrieved:
```{r highlight=TRUE}
keytypes(miRBaseVersions.db);
```
The output lists `r length(keytypes(miRBaseVersions.db))` tables where each one
of them can be queried. The keytype "MIMAT" is the main table containing all
records from all supported miRBase release versions. Keytypes starting with 
the prefix "VW-MIMAT" are so called SQL views. For example the keytype
"VW-MIMAT-21.0" is an SQL view from the "MIMAT" table which only holds records
from miRBase version 21.0.

### 2.2 Function `columns`

Use the `columns` function to retreive information about the kind of variables
you can retrieve in the final output:
```{r highlight=TRUE}
columns(miRBaseVersions.db);
```
All `r length(columns(miRBaseVersions.db))` columns are available for all 
`r length(keytypes(miRBaseVersions.db))` keytypes.

### 2.3 Function `keys`

The `keys` function returns all viable keys of a praticular `keytype`. The 
following example retrieves all possible keys for miRBase release version 6.0.
```{r highlight=TRUE}
k = head(keys(miRBaseVersions.db, keytype = "VW-MIMAT-6.0"));
k;
```

### 2.4 Function `select`

The `select` function is used to extract data. As input values the function
takes outputs received from the other three functions `keys`, 
`columns` and `keytypes`.  
For exmaple to extract all information about the mature 
accession 'MIMAT0000092' we can run the following command:
```{r highlight=TRUE}
result = select(miRBaseVersions.db, 
                keys = "MIMAT0000092", 
                keytype = "MIMAT", 
                columns = "*")
result;
```
As we can see the result returns all miRNA names the accession had among the
different miRBase releases.
If we for example only want to extract the fields for 'accession', 'name' and 
'version' we simply run the following command:
```{r highlight=TRUE}
result = select(miRBaseVersions.db, 
                keys = "MIMAT0000092", 
                keytype = "MIMAT", 
                columns = c("ACCESSION", "NAME", "VERSION"))
result;
```
In comparison to the previous output with parameter `columns = "*"` this time
only the selected columns were returned.


## Additional information

### Packages loaded via namespace
The following packages are used in the `miRBaseVersions.db` package: 

* AnnotationDbi_1.32.3 [@annotationdbicite]
* DBI_0.3.1 [@dbicite]
* RSQLite_1.0.0 [@rsqlitecite]
* gtools_3.5.0 [@gtoolscite]

### Future Aspects
This database can only be of good use if it will be kept up to date.
Therefore we plan to include new miRBase releases as soon as possible.

## References {-}



