README.Rmd

---
output:
  html_document:
    highlight: tango
    keep_md: yes
    theme: readable
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo=TRUE, message=FALSE,warning=FALSE)
```

# ![CTSgetR](https://github.com/dgrapov/CTSgetR/blob/master/inst/ctsgetR_logo.png?raw=true)

<hr>

## R interface to the [Chemical Translation Service (CTS)](http://cts.fiehnlab.ucdavis.edu/)

<hr>

#### `CTSgetR` provides a consitent interface to translation of chemical names and over 200 database identifiers including `InChIKey`, `HMDB`, `KEGG` and `PubChem`. Translation of chemical names is hard. Use `CTSgetR` to robustly translate chemical names to other identifiers through 1) conversion to `InChIKey` 2) `biological` or `popularity` scoring and 3) translation to over 200 biological database identifiers. `CTSgetR` uses a sqlite database to cache and speed all of your routine translations.

`CTSgetR` adds robust support for translation `to` and `from` `Chemical names` based intermediate translation to `InChIKey`
first. 

### This package supports metabolite identifier translation:

* ### [in R](#in-R)
* ### deployed as an [opencpu](https://www.opencpu.org/) [API](#API)
* ### from a [shiny UI](#shiny) using asynchronous local or API calls

<a name="in-R"></a>

> ### `using R`
#### Installation 
```{r, message=FALSE,warning=FALSE,eval=FALSE}
install_github("dgrapov/CTSgetR")
```

#### Make sure CTS API is available
```{r}
library(CTSgetR)
GET('https://cts.fiehnlab.ucdavis.edu/services') %>%
  http_status(.) %>%
  {if( .$category != 'Success'){stop('Oops looks like https://cts.fiehnlab.ucdavis.edu/services is down!') }} 
```

#### View some of the possible translation options between > 200 databases
```{r}
trans<-unlist(valid_from())
head(trans,10)
```

#### Find a database of interest
```{r}
want<-'CID'
trans[grepl(want,trans,ignore.case=TRUE)]
```


#### Initialize a local database to speed up routine queries
```{r,eval=FALSE}
db_name<-'ctsgetr.sqlite'
init_CTSgetR_db(db_name)
db_stats()
```

#### Translation examples

#### `Chemical Name` to `InChIKey`
```{r,message=FALSE}
db_name<-'ctsgetr.sqlite' # local cache
id<-c("alanine",'lactic acid')
from<-"Chemical Name"
to<-"InChIKey"

CTSgetR(id,from,to,db_name=db_name)
```

#### One identifier to many
##### The example below shows the alternative `data.frame` input format for more complex queries.
```{r}

id<-c("alanine",'lactic acid')
from<-"Chemical Name"
to<- c( "PubChem CID", "KEGG","Human Metabolome Database")

CTSgetR(id,from,to,db_name=db_name)

```



#### Many identifiers to one
##### Build up complex queries by combining  data frames of `id`, `from` to `to` values.
```{r}


 #from many to many
  args <-structure(list(id = structure(c(1L, 2L, 3L, 1L, 2L, 3L, 1L, 2L, 
                                         3L, 4L, 4L), .Label = c("alanine", "foo", "lactic acid", "HMDB0000161"
                                         ), class = "factor"), from = structure(c(1L, 1L, 1L, 1L, 1L, 
                                                                                  1L, 1L, 1L, 1L, 2L, 2L), .Label = c("Chemical Name", "Human Metabolome Database"
                                                                                  ), class = "factor"), to = structure(c(1L, 1L, 1L, 2L, 2L, 2L, 
                                                                                                                         3L, 3L, 3L, 2L, 1L), .Label = c("PubChem CID", "KEGG", "Human Metabolome Database"
                                                                                                                         ), class = "factor")), class = "data.frame", row.names = c(NA, 
                                                                                                                                                                                    -11L))
args  
  
args %>%
  split(.,.$from) %>%
  map(~CTSgetR(.$id,.$from,.$to,db_name=db_name)) %>%
  bind_rows(.)


```

<hr>

<a name="API"></a>

> ## Deploy `CTSgetR` as a `docker`ized `API`

<hr>

### The following [docker](https://hub.docker.com/r/dgrapov/ctsgetr/dockerfile) image and [docker-compose](https://github.com/dgrapov/CTSgetR/blob/master/docker-compose.yml) commands can be used to `build` and run the `CTSgetR` package as an [opencpu](https://hub.docker.com/r/opencpu/ubuntu-18.04) based `API`.

* #### [CTSgetR image](https://hub.docker.com/r/dgrapov/ctsgetr)
* #### [ocpuclient](https://github.com/dgrapov/ocpuclient): client library for accessign `CTSgetR` `API`

### The `CTSgetR` image contains an opencpu and Rstudio server
* #### `localhost/ocpu/`: [opencpu-server](https://www.opencpu.org/)
* #### `localhost/rstudio/` : [rstudio server](https://hub.docker.com/r/opencpu/rstudio) (use user: opencpu and password:<mypassword> )

##  Build docker `image`
#### `build`
```
export rstudio_pass=mypassword # rstudio server password for user opencpu
docker-compose -f docker-compose.yml build --force-rm

```

### Launch API
```
#mount to persist internal sqlite DB between updates 
export ctsgetr_db_mount=<local path to save database e.g. /mypath>
docker-compose -f docker-compose.yml up -d

```

### Test API endpoints

#### `bash`
```bash
curl http://localhost/ocpu/library/CTSgetR/R/heartbeat
```
#### `R`
##### heartbeat
```r
library(ocpuclient)

base_url<-'http://localhost/ocpu/'

endpoint<-'library/CTSgetR/R/heartbeat'
url<-paste0(base_url,endpoint)
post_ocpu(url=url)
```

##### translation
```r
#translate
endpoint<-'library/CTSgetR/R/CTSgetR'
url<-paste0(base_url,endpoint)

id <-
  c("C15973",
    "C00026")
from <- "KEGG"
to <- "PubChem CID"

body<-list(id=id,from=from,to=to,db_name=db_name)


post_ocpu(url=url,body=body)

```

<a name="shiny"></a>

> ## Launch `shiny` UI using asynchronous `opencpu` API 

#### The following example shows a how to use a `shiny` module combined with `futures` and `promises`  `R` packages to connect to an `opencpu` API uisng async calls. 

```r
library(shiny)
library(tippy)
library(CTSgetR) # local calls
library(ocpuclient) # CTSgetR opencpu API calls
```

#### Specify local database or API options
```r
#one of local
Sys.setenv('ctsgetr_DB'='inst/ctsgetr.sqlite') #see section `in R` showing how to initialize a local databse
#or API
Sys.setenv('ctsgetr_DB'='/ctsgetr/inst/ctsgetr.sqlite') # in API docker for mount
Sys.setenv('CTSgetR_API'='http://localhost/ocpu/library/CTSgetR/R/CTSgetR') # url of API endpoint
````

#### User input translations

```r
    library(promises)
    library(future)
    plan(multisession)
    
    
    #module
    ui <- fluidPage(
      
      sidebarLayout(position = "left",
                    sidebarPanel(tagList(mod_CTSgetR_ui("translate"))),
                    mainPanel(verbatimTextOutput("main_out")))
      
    )
    
    server <- function(input, output, session) {
      
      translation <- mod_CTSgetR_server('translate')
      
      output$main_out <- renderPrint({
        translation() %...>% print(.)
        
      })
    }
    
    shinyApp(ui, server)

```

#### Connect to other shiny components
```r 
library(promises)
    library(future)
    plan(multisession)
    
    #make `example` a reactive returning a data frame to update dynamically
    example<-data.frame('chemical_name' = c('alanine','Pyruvic acid'))
    
    #module
    ui <- fluidPage(
      
      sidebarLayout(position = "left",
                    sidebarPanel(tagList(mod_CTSgetR_ui("translate"))),
                    mainPanel(verbatimTextOutput("main_out")))
      
    )
    
    server <- function(input, output, session) {
      
      translation <- mod_CTSgetR_server('translate',data=example)
      
      output$main_out <- renderPrint({
        translation() %...>% print(.)
        
      })
    }
    
    shinyApp(ui, server)
```