Overview

The OpenCGA R Client has been implemented following the Bioconductor guidelines for package development which promote high-quality, well documented and interoperable software. The client provides a user-friendly interface to work with OpenCGA REST Web Services through R.

Client Library

Design Principles

The R package can be downloaded from XXXX and the source code can be found in https://github.com/opencb/opencga/tree/develop/opencga-client/src/main/R. The methods and classes implemented have been designed following the S4 interface as recommended by Bioconductor. Class definitions are stored in R/AllClasses.R. Currently, there is only one class defined containing the OpenCGA connection details which is extensively used by all methods in the package. A set of methods have been implemented to deal with the connectivity and login to the REST host. These methods are stored in R/OpencgaR-methods.R. Connection to the host is done in two steps using the functions initOpencgaR and opencgaLogin for defining the connection details and loging in, respectively.

# Initialise connection
con <- initOpencgaR(host = "http://localhost:8080/opencga/", version = "v1")
# Log in
con <- opencgaLogin(opencga = con, userid = "user", passwd = "pass")

API

The package implements at least one function for each available resource (user, project, study, etc.) which are defined in R/AllGeneric.R. Currently, the following functions are available:

# User
userClient(OpencgaR, user, action, params=NULL)
userConfigClient(OpencgaR, user, name, action, params=NULL)
userFilterClient(OpencgaR, user, name, action, params=NULL)


# Project
projectClient(OpencgaR, project, action, params=NULL)

# Study
studyClient(OpencgaR, study, action, params=NULL)
studyGroupClient(OpencgaR, study, group=NULL, action, params=NULL)
studyAclClient(OpencgaR, study, memberId, action, params=NULL)
studyVariablesetClient(OpencgaR, variableSet, action, params=NULL)
studyVariablesetFieldClient(OpencgaR, variableSet, action, params=NULL)

# File
fileClient(OpencgaR, f, action, params=NULL)
fileAclClient(OpencgaR, f, memberId, action, params=NULL)

# Job
jobClient(OpencgaR, jobId, action, params=NULL)
jobAclClient(OpencgaR, jobId, memberId, action, params=NULL)

# Family
familyClient(OpencgaR, family, action, params=NULL)
familyAnnotationsetClient(OpencgaR, family, annotationsetName, action, params=NULL)
familyAclClient(OpencgaR, memberIds, action, params=NULL)

# Individual
individualClient(OpencgaR, individual, action, params=NULL)
individualAnnotationsetClient(OpencgaR, individual, annotationsetName, action, params=NULL)
individualAclClient(OpencgaR, memberIds, action, params=NULL)

# Sample
sampleClient(OpencgaR, sample, action, params=NULL) 
sampleAnnotationsetClient(OpencgaR, sample, annotationsetName, action, params=NULL) 
sampleAclClient(OpencgaR, memberIds, action, params=NULL)

# Cohort
cohortClient(OpencgaR, cohort, action, params=NULL)
cohortAnnotationsetClient(OpencgaR, cohort, annotationsetName, action, params=NULL)
cohortAclClient(OpencgaR, memberIds, action, params=NULL)

# Clinical
clinicalClient(OpencgaR, clinicalAnalysis, action, params=NULL)

# Meta
metaClient(OpencgaR, action, params=NULL)

# Ananlysis
analysisVariantClient(OpencgaR, action, params=NULL)

Every method belonging to each resource takes the mandatory parameters individually and calls to the corresponding web service using the correct HTTP method (GET or POST). All functions require an OpencgaR connection object (as described in the initialisation and login step). The action parameter expects a character string specifying what information we want to obtain (the endpoint, as described here). Any additional query and body parameters (params) should be specified in the params field as a list(). For example, if we want to get the information about two samples ("sample1" and "sample2") excluding the attributes and stats fields, we could do it as follows:

# Create params list
params <- list(exclude="attributes,stats")


# Get information
sampleClient(OpencgaR=con, 
			 sample=c("sample1","sample2"), 
			 action="info",
			 params=params)

In addition to the individual resource clients, we have created a general method that gives the user more flexibility to construct REST queries. This is the fetchOpenCGA() function which accepts multiple parameters:

fetchOpenCGA(object, category, categoryId, 
			 subcategory, subcategoryId, action, 
			 params, httpMethod, as.queryParam)

In the above function and following the terminology here, object is the OpencgaR connection object, category is the resource, categoryId is the resource ID we want to query and action is the endpoint, as specified earlier. More complex web services will require subcategory and subcategoryId. As happens with the other methods, additional query and body parameters are handled internally so the user should just pass a list() to the params parameter. The HTTP method (GET or POST) should be specified using httpMethod, please check the Swagger documentation to know what is the correct method for the function you want to use.

Help