Important note: This is a work-in-progress project to update the sevenbridges2 package. Accordingly, this vignette will also change as new features are implemented.

1 Introduction

sevenbridges2 is an R package that provides an interface for the Seven Bridges public API. The supported platforms include the Seven Bridges Platform, Cancer Genomics Cloud (CGC), BioData Catalyst (BDC) and CAVATICA.

Learn more from our documentation on the Seven Bridges Platform, Cancer Genomics Cloud (CGC), BioData Catalyst (BDC) and CAVATICA.

Unlike the current sevenbridges package that is built on top of Reference classes, the sevenbridges2 package is based on more modern and lightweight R6 classes. However, the basic idea and way of constructing API requests is largely preserved.

1.1 R Client for the Seven Bridges API

In order to use the sevenbridges2 package users must authenticate themselves first by creating an Auth object and providing necessary credentials. You can read more about the authentication types in our next chapters.

The sevenbridges2 package only supports v2+ versions of the API, since versions prior to v2 are not compatible with the Common Workflow Language (CWL). This package provides a simple interface for accessing and trying out various methods.

1.2 Installation

The sevenbridges2 package is available on CRAN and Seven Bridges Github repository.

To install it from CRAN, use simply:

# Install package from CRAN
install.packages("sevenbridges2")

To install the development version from the develop branch on our Github, use the remotes package:

# Install package from github
remotes::install_github(
  "sbg/sevenbridges2",
  build_vignettes = TRUE, dependencies = TRUE
)

If you have trouble with pandoc and do not want to install it, set build_vignettes = FALSE to avoid the vignettes build.

1.3 API General Information

There are two ways of constructing API calls. For instance, you can use low-level API calls which use arguments like path, query, and body. These are documented in the API reference libraries for the Seven Bridges Platform and the CGC. An example of a low-level request to “list all projects” is shown below. In this request, you can also pass query and body as a list.

# Load the package
library("sevenbridges2")

# Authenticate
a <- Auth$new(token = "<your_token>", platform = "aws-us")

# List all projects with raw api() function
a$api(path = "projects", method = "GET")

(Advanced user option) The second way of constructing an API request is to directly use the httr2 package to make your API calls.

The sevenbridges2 package is organized by main resources from the Seven Bridges API reference. There we have groups of endpoints to work with projects, files, apps, tasks, invoices, volumes, etc. For each group of resources, there is a set of operations such as query(), get() and delete() which are common, as well as other custom operations.

Before we start, keep in mind the following:

offset and limit

Almost every API call accepts two arguments named offset and limit.

Offset defines where the retrieved items start.
Limit defines the number of items you want to get.

By default, offset is set to 0 and limit is set to 50. As such, your API request returns the first 50 items when you list items or search for items by name. To search and list all items, use complete = TRUE if you are using the core api() function in your API request, or the all() operation within the Collection object you’ve received as the result.

Collection

Every API call that returns a list of items (usually the output from query() operations), operations), like fetching projects, files, apps etc, wraps the results into a general Collection class object containing the items field from which users may access the items returned. Additional options that the Collection class offers are to navigate between pages of results, for example, to load next or previous page of results by calling next_page() and prev_page() methods.

Moreover, users can fetch all results using Collection’s all() method which is a shortcut to send multiple API calls for each next page and collect all results. Keep in mind the limit used, as well as the API rate limit.

# Create a collection of files
public_files <- a$files$query(project = "admin/sbg-public-data")

# Load next 50 results
public_files$next_page()

# Load previous 50 results
public_files$prev_page()

# Load all results
public_files$all()

Lastly, printing Collection objects will print the first 10 items (if there are more than 10 items in the results) by default, but this can be changed with the n parameter in its print() function:

# Create a collection of files
public_files <- a$files$query(project = "admin/sbg-public-data")

# Default print
public_files

# Print 20 items
public_files$print(n = 20)

Search by ID

When searching by ID (usually it’s the resource’s get() operation), your request will return your exact resource as it is unique. Therefore, you do not have to set offset and limit manually. It is good practice to find your resources by their ID and pass this ID as an input to your task. You can find a resource’s ID in the final part of the URL in the visual interface or via API requests to list resources or get a resource’s details.

Search by name

Search by name as criteria in the query() operations of Resources, returns all exact or partial matches depending on the resource.

For example, to list all public files, use the admin/sbg-public-data project query parameter, while if you want to find an exact file by name, set its name parameter to the exact value (partial search by name is not possible for files).

# Search all public files
public_files <- a$files$query(project = "admin/sbg-public-data")

# Search files by name
file_1000G_omni <- a$files$query(
  project = "admin/sbg-public-data",
  name = "1000G_omni2.5.b37.vcf"
)

On the other hand, partial search by name works for Projects and Apps resources. You can set the corresponding name or query_terms parameters for this use case. In order to query public apps, set the visibility parameter to ‘public’.

# Search all public apps containing the STAR term
public_star_apps <- a$apps$query(
  visibility = "public",
  query_terms = list("STAR")
)

# Search all projects that contain "demo" in the name
demo_projs <- a$projects$query(name = "demo")

Platform Name	API Base URL	Short Name
Seven Bridges Platform (US)	`https://api.sbgenomics.com/v2`	`"aws-us"`
Seven Bridges Platform (EU)	`https://eu-api.sbgenomics.com/v2`	`"aws-eu"`
Seven Bridges Platform (China)	`https://api.sevenbridges.cn/v2`	`"ali-cn"`
Cancer Genomics Cloud (CGC)	`https://cgc-api.sbgenomics.com/v2`	`"cgc"`
Cavatica	`https://cavatica-api.sbgenomics.com/v2`	`"cavatica"`
BioData Catalyst Powered by Seven Bridges	`https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2`	`"f4c"`

Introduction and Quickstart for Seven Bridges API R Client

2024-07-01

1 Introduction

1.1 R Client for the Seven Bridges API

1.2 Installation

1.3 API General Information

2 Quickstart

2.1 Create Auth Object

2.2 Get User Information

2.3 Rate Limit

2.4 Show Billing Information

2.5 List and query projects

2.6 Create a new project

2.7 Get details of a specified project

2.8 Copy app into the project

2.9 Execute a new task

2.9.1 Find your app inputs

2.9.2 Prepare your input files

2.9.3 Create a new draft task

2.9.4 Preview your app’s expected outputs

2.10 Run a Task

2.11 Run tasks using spot instances

2.12 Execution hints per task run

2.13 Draft a batch task

2.1 Create `Auth` Object