# sevenbridges-r <a href="https://www.sevenbridges.com"><img src="logo.png" align="right" alt="logo" height="128" width="128" /></a>
[](https://travis-ci.org/sbg/sevenbridges-r)
[](https://ci.appveyor.com/project/road2stat/sevenbridges-r)
[](https://bioconductor.org/packages/release/bioc/html/sevenbridges.html#since)
[](https://bioconductor.org/packages/stats/bioc/sevenbridges/)
[](https://hub.docker.com/r/sevenbridges/sevenbridges-r/)
[BioC (Release)](https://www.bioconductor.org/packages/release/bioc/html/sevenbridges.html) · [BioC (Development)](https://www.bioconductor.org/packages/devel/bioc/html/sevenbridges.html) · [GitHub (Latest)](https://github.com/sbg/sevenbridges-r)
## Overview
sevenbridges-r is an [R](https://cran.r-project.org/)/[Bioconductor](https://www.bioconductor.org/) package that provides an interface for the [Seven Bridges Platform](https://www.sbgenomics.com/) and [Cancer Genomics Cloud](https://www.cancergenomicscloud.org/) public APIs.
The Seven Bridges Platform is a cloud-based environment for conducting bioinformatic analyses. It is a central hub for teams to store, analyze, and jointly interpret their bioinformatic data. The Platform co-locates analysis workflows alongside the largest genomic datasets to optimize processing, allocating storage and compute resources on demand.
The Cancer Genomics Cloud (CGC), powered by Seven Bridges, is also a cloud-based computation environment. It was built as one of three pilot systems funded by the [National Cancer Institute](https://www.cancer.gov/) to explore the paradigm of colocalizing massive genomics datasets, like [The Cancer Genome Atlas (TCGA)](https://cancergenome.nih.gov/), alongside secure and scalable computational resources to analyze them. The CGC makes more than a petabyte of multi-dimensional data available immediately to authorized researchers. You can add your own data to analyze alongside TCGA using predefined analytical workflows or your own tools.
## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
- [Bioconductor - Release Version](#bioconductor---release-version)
- [Bioconductor - Development Version](#bioconductor---development-version)
- [Latest Development Version](#latest-development-version)
- [Features](#features)
- [Flexible Authentication Methods](#flexible-authentication-methods)
- [Complete API R Client](#complete-api-r-client)
- [Task Monitoring](#task-monitoring)
- [Batch Tasks Support](#batch-tasks-support)
- [Cross Environment Support](#cross-environment-support)
- [Common Workflow Language Tool Interface](#common-workflow-language-tool-interface)
- [Utilities for Tool and Flow](#utilities-for-tool-and-flow)
- [Tutorials](#tutorials)
- [IDE Docker Image](#ide-docker-image)
- [FAQ](#faq)
- [Events](#events)
- [Contribute](#contribute)
- [Copyright](#copyright)
## Installation
### Bioconductor - Release Version
This installation is recommended for most users as it is the most stable. The current release of Bioconductor is version 3.5, and it works with __R version 3.4.0__. Users of older R and Bioconductor versions should upgrade to take advantage of new features.
If you do not want to update R, please install the `sevenbridges` package directly from GitHub by following the instructions below.
#### Check R version
First, check which version of R you are using with the following:
```r
R.version.string
```
If you are not running the latest release version of R, install it by the following [these instructions](https://www.bioconductor.org/install/#install-R). If you are using RStudio, close and restart RStudio after installing R. RStudio will detect the new installation.
#### Install the package
Install the `sevenbridges` package as shown below:
```r
source("https://bioconductor.org/biocLite.R")
biocLite("sevenbridges")
```
### Bioconductor - Development Version
If you are developing tools in the `devel` branch or if you are a user who uses the development version for R and Bioconductor, install the package from the bioconductor `devel` branch. You need to install R-devel first by following the directions in ["Using the 'Devel' Version of Bioconductor"](https://bioconductor.org/developers/how-to/useDevel/). After upgrading R, this method of installation is harder. To try the latest features, please install directly from GitHub as next shown below:
```r
source("https://bioconductor.org/biocLite.R")
useDevel(devel = TRUE)
biocLite("sevenbridges")
```
To load the package in R, simply call
```r
library("sevenbridges")
```
### Latest Development Version
You can always install the latest development version of the `sevenbridges` package from GitHub. We push to the Bioconductor branch (`release`/`devel`) regularly.
#### If `devtools` was not installed
Installing the `sevenbridges` package requires you have the `devtools` package. If you do not have `devtools`, install it from [CRAN](https://cran.r-project.org/web/packages/devtools/README.html).
```r
install.packages("devtools")
```
You may got an error and need system dependecies for curl and ssl. For example, you probably need to do the following first in order to install `devtools` and in order to build vignettes since you need `pandoc` under Ubuntu.
```
apt-get update
apt-get install libcurl4-gnutls-dev libssl-dev pandoc pandoc-citeproc
```
#### If `devtools` is already installed
Install latest version of `sevenbridges` from GitHub with the following:
```r
source("https://bioconductor.org/biocLite.R")
biocLite("readr")
devtools::install_github(
"sbg/sevenbridges-r",
repos = BiocInstaller::biocinstallRepos(),
build_vignettes = TRUE, dependencies = TRUE)
```
If you have trouble with `pandoc` and do not want to install it, set `build_vignettes = FALSE` to avoid building the vignettes.
## Features
The `sevenbridges` package includes the following features:
### Flexible Authentication Methods
* Multiple authentication methods support.
Direct authentication:
```r
# direct authentication
a <- Auth(token = "your_token", platform = "cgc")
# or use base url
a <- Auth(token = "your_token", url = "https://cgc-api.sbgenomics.com/v2")
```
Authentication via system environment variables:
```r
sbg_set_env(token = "your_token", url = "https://cgc-api.sbgenomics.com/v2")
a <- Auth(from = "env")
```
Authentication via a user configuration file, collect and manage your credentials for multiple accounts across various Seven Bridges environments:
```r
a <- Auth(from = "file", profile_name = "aws-us-tengfei")
```
Please check `vignette("api", package = "sevenbridges")` for technical details about all available authentication methods.
### Complete API R Client
* A complete API R client with a user-friendly, object-oriented API with printing and support operations for API requests relating to users, billing, projects, files, apps, and tasks. Short examples are also included, as shown below:
```r
# Get a project by pattern-matching its name
p <- a$project("demo")
# Get a project by its id
p <- a$project(id = "tengfei/demo")
# Delete files from a project
p$file("sample.tz")$delete()
# Upload fies from a folder to a project and include file metadata
p$upload("folder_path", metadata = list(platform = "Illumina"))
```
### Task Monitoring
* A task monitoring hook which allows you to add a hook function to specific task statuses as you monitor a task. For example, you can opt to receive an email when the task is completed or specify to download all files produced by the task, as shown below:
```r
setTaskHook("completed", function() {
tsk$download("~/Downloads")
})
tsk$monitor()
```
### Batch Tasks Support
* Batch tasks by metadata and by item.
```r
# Batch by item
(tsk <- p$task_add(
name = "RNA DE report new batch 2",
description = "RNA DE analysis report",
app = rna.app$id,
batch = batch(input = "bamfiles"),
inputs = list(bamfiles = bamfiles.in,
design = design.in,
gtffile = gtf.in)))
# Batch by metadata. Note that input files must
# have relevant metadata fields specified.
(tsk <- p$task_add(
name = "RNA DE report new batch 3",
description = "RNA DE analysis report",
app = rna.app$id,
batch = batch(input = "fastq",
c("metadata.sample_id",
"metadata.library_id")),
inputs = list(bamfiles = bamfiles.in,
design = design.in,
gtffile = gtf.in)))
```
### Cross Environment Support
* Cross-platform support for Seven Bridges environments, such as [Cancer Genomics Cloud](https://www.cancergenomicscloud.org/) or [Seven Bridges Platform](https://www.sbgenomics.com/) on either Amazon Web Services or Google Cloud Platform.
### Common Workflow Language Tool Interface
* A [Common Workflow Language (CWL)](http://www.commonwl.org/) Tool interface to directly describe your tool in R, export it to JSON or YAML, or add it to your online project. This package defines a complete set of CWL object, so you can describe tools as follows:
```r
library("readr")
fd <- fileDef(name = "runif.R", content = read_file(fl))
rbx <- Tool(
id = "runif",
label = "runif",
hints = requirements(
docker(pull = "rocker/r-base"),
cpu(1), mem(2000)),
requirements = requirements(fd),
baseCommand = "Rscript runif.R",
stdout = "output.txt",
inputs = list(
input(id = "number", type = "integer", position = 1),
input(id = "min", type = "float", position = 2),
input(id = "max", type = "float", position = 3)),
outputs = output(id = "random", glob = "output.txt"))
# output CWL JSON
rbx$toJSON(pretty = TRUE)
# output CWL YAML
rbx$toYAML()
```
### Utilities for Tool and Flow
* Utilities for Tool and Flow, for example
```r
# converting a SBG CWL JSON file
library("sevenbridges")
t1 <- system.file("extdata/app", "tool_star.json", package = "sevenbridges")
# convert json file into a Tool object
t1 <- convert_app(t1)
# shows all input matrix
t1$input_matrix()
```
## Tutorials
We maintain 3 different sets of documentation: the sevenbridges-r GitHub repository (latest and most up-to-date), Bioconductor release channel, and Bioconductor development channel. Below, only the GitHub version is linked to provide the latest documentation. For the other versions, please visit [Bioconductor Release version](https://www.bioconductor.org/packages/release/bioc/html/sevenbridges.html) or [Bioconductor Development version](https://www.bioconductor.org/packages/devel/bioc/html/sevenbridges.html). The tutorials below are re-generated regularly as we update the package on GitHub.
| Tutorial Title | HTML | Rmd Source |
|:--------------------------------------------------|:-----------|:-------------|
| Complete Reference for the API R Client | [HTML](https://sbg.github.io/sevenbridges-r/articles/api.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/api.Rmd) |
| Use R on the Cancer Genomics Cloud | [HTML](https://sbg.github.io/sevenbridges-r/articles/bioc-workflow.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/bioc-workflow.Rmd) |
| Create a Docker Container and use Command Line Interface for R | [HTML](https://sbg.github.io/sevenbridges-r/articles/docker.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/docker.Rmd) |
| Describe and execute Common Workflow Language (CWL) Tools and Workflows in R | [HTML](https://sbg.github.io/sevenbridges-r/articles/apps.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/apps.Rmd) |
| <a name="ide"/>IDE container: Rstudio and Shiny server and more | [HTML](https://sbg.github.io/sevenbridges-r/articles/rstudio.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/rstudio.Rmd) |
| Browse data on the Cancer Genomics Cloud via the Data Explorer, a SPARQL query, <br />or the Datasets API | [HTML](https://sbg.github.io/sevenbridges-r/articles/cgc-sparql.html) | [Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/cgc-sparql.Rmd) |
## IDE Docker Image
In the tutorial for [IDE container](#tutorials) above, we built a Docker container locally from which we can launch RStudio and Shiny. To launch RStudio and Shiny Server with the Seven Bridges IDE Docker container, do the following:
```shell
docker run -d -p 8787:8787 -p 3838:3838 --name rstudio_shiny_server sevenbridges/sevenbridges-r
```
To mount a file system, you need to use `--privileged` with fuse.
```shell
docker run --privileged -d -p 8787:8787 -p 3838:3838 --name rstudio_shiny_server sevenbridges/sevenbridges-r
```
Check out the IP from Docker Machine if you are on a Mac OS.
```bash
docker-machine ip default
```
In your browser, you can see where the RStudio server is located from the path `http://<url>:8787/`. For example, if 192.168.99.100 is returned, visit `http://192.168.99.100:8787/` for Rstudio.
For the Shiny server, each app__ is hosted at `http://<url>:3838/users/<username of rstudio>/<app_dir>` for the Shiny server. For example, an app called `01_hello` owned by user `rstudio` (a default user) has the path `http://<url>:3838/users/rstudio/01_hello/`. To develop your Shiny apps as an Rstudio user, you can login your RStudio server and create a folder in your home folder called `~/ShinyApps`. There, you can develop shiny apps in that folder. For example, you can create an app called `02_text` at `~/ShinyApps/02_text/`.
Log into your RStudio at `http://<url>:8787`. Then, try to copy an app to your home folder, as follows:
```r
dir.create("~/ShinyApps")
file.copy("/usr/local/lib/R/site-library/shiny/examples/01_hello/",
"~/ShinyApps/", recursive = TRUE)
```
If you are logged in as user `rstudio`, visit `http://192.168.99.100:3838/rstudio/01_hello`. You should be able to see the "hello" example.
_Note_: Generic Shiny apps can also be hosted at `http://<url>:3838/` or, for a particular app, at `http://<url>:3838/<app_dir>`. Inside the Docker container, it's hosted under `/srv/shiny-server/`.
## FAQ
The best place to ask questions about the `sevenbridges` package is the [mailing list](https://groups.google.com/forum/#!forum/sevenbridges-r).
- __Q__: Does this package support Seven Bridges' API v1 which was not CWL compatible?<br />
__A__: No. This package only supports API v2 +. For API v1, please check out the [sbgr](https://github.com/road2stat/sbgr) package. Note that API v1 and associated legacy project types will be deprecated eventually.
- __Q__: Which version of the Common Workflow Language (CWL) is supported?<br />
__A__: We support draft 2 and are making progress on supporting draft 3.
- __Q__: Is there a Python binding for the API?<br />
__A__: Yes, the official Python client is [here](https://github.com/sbg/sevenbridges-python). Recipes and tutorials using the Python bindings are [here](https://github.com/sbg/okAPI).
- __Q__: Why do I get warning messages when I use the API R client?<br />
__A__: The warning only exists in Rstudio and is potentially a bug in Rstudio. To ignore, it use `options(warn = -1)`
- __Q__: I still have problems despite dismissing the messages.<br />
__A__: Please try to use the latest package on GitHub or [update installed Bioconductor packages](https://bioconductor.org/install/#update-bioconductor-packages). This usually includes the most recent bug fixes.
## Events
| Time | Event | Location |
|:------------------|:--------------------------|:------------------------------|
| Jan 12, 2017 | [Genomics in the Cloud - Boston Bioconductor Meetup](https://www.meetup.com/Boston-R-Bioconductor-for-genomics/events/235580582/) (talk) [[slides](https://nanx.me/talks/bioc-meetup-cgc-170112.pdf)] | Dana-Farber Cancer Institute, Boston, MA |
| Sep 12 - 14, 2016 | [Probabilistic Modeling in Genomics](https://www.stats.ox.ac.uk/events/probgen16) (poster) | University of Oxford, Oxford, UK |
| May 27 - 29, 2016 | [The 9th China-R Conference](http://china-r.org/bj2016/index.html) (talk) | Renmin University of China, Beijng, China |
| Jun 27 - 30, 2016 | [The R User Conference 2016](http://user2016.org/) (talk) | Stanford University, Stanford, CA |
| Jun 24 - 26, 2016 | [BioC 2016: Where Software and Biology Connect](https://bioconductor.org/help/course-materials/2016/BioC2016/) (workshop) | Stanford University, Stanford, CA |
| Apr 1 - 3, 2016 | [NCI Cancer Genomics Cloud Hackathon](https://www.cancergenomicscloud.org/hacking-cancer/) (tutorial)<br />[[HTML](https://sbg.github.io/sevenbridges-r/articles/bioc-workflow.html)] [[R Markdown Source](https://raw.githubusercontent.com/sbg/sevenbridges-r/master/vignettes/bioc-workflow.Rmd)] | Seven Bridges Genomics, Inc., Boston, MA |
## Contribute
Please file bug reports/feature requests on the [issue page](https://github.com/sbg/sevenbridges-r/issues), or create pull requests [here](https://github.com/sbg/sevenbridges-r/pulls).
Contributors should read the [Seven Bridges Notice to Contributors](https://drive.google.com/file/d/0B9ms5nmyMyvSY3ZmeDRqV1p4SHc/view?usp=sharing) and sign the [Seven Bridges Contributor Agreement](https://secure.na1.echosign.com/public/esignWidget?wid=CBFCIBAA3AAABLblqZhAqt_9rHEqy2MggS0uWRmKHUN2HYi8DWNjkgg5N68iKAhRFTy7k2AOEpRHMMorxc_0*) before submitting a pull request.
## Copyright
© 2017 Seven Bridges Genomics, Inc. All rights reserved.
This project is licensed under the terms of the [Apache License 2.0](LICENSE).
