Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.


Code Block
themeRDark
titleInitialise the OpenCGA connection and login
# 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:


Code Block
themeRDark
titleOpenCGA R functions
# 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:

Code Block
themeRDark
# 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:

Code Block
themeRDark
titlefetchOpenCGA function
fetchOpenCGA(object, category, categoryId, 
			 subcategory, subcategoryId, action, 
			 params, httpMethod, as.queryParam)

In the above function and following the terminology hereobject 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. By default, the parameters are NULL, so there is no need to set them if unused. 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

A help function (opencgaHelp()) has been also implemented to provide easy access to the information about the web services available. 

Code Block
themeRDark
titleopencgaHelp()
# List all services available
opencgaHelp(opencga=con)


# List all services available for a particular resource
opencgaHelp(opencga=con, client="studyClient")


# List all parameters available for a particular resource endpoint
opencgaHelp(opencga=con, client="studyClient", action="search")




Table of Contents:

Table of Contents
indent20px