pyOpenCGA Overview

The OpenCGA Python Client provides a user-friendly API to work with OpenCGA through the REST Web Services. Python client is called pyOpenCGA, some of the main features include:

full RESTful web service API implemented, all endpoints are supported including new alignment or clinical functionality
data is returned in a new QueryResponse object which contains metadata and the results, some handy methods and iterators implemented
it uses the OpenCGA client-configuration.yml file and the stored session
several Jupyter Notebooks iimplemented

pyOpenCGA has been implemented and contributed by Pablo Marin and David Gomez and it is based on the previous pyCGA library implemented by Antonio Rueda and Daniel Perez from Genomics England.

You can find some examples in the Tutorials section at Using the Python client.

Installation

Python client requires at least Python 3.x, although most of the code is fully compatible with Python 2.7. You can install pyOpenCGA either from PyPI repository or from the source code.

PyPI

You can find stable releases of pyOpenCGA at https://pypi.org/project/pyopencga/, installing is as simple as:

Code Block

language	bash
theme	RDark

## Latest stable version
pip install pyopencga

Source Code

Python client source code can be found in OpenCGA GitHub repository at https://github.com/opencb/opencga/tree/develop/opencga-client/src/main/python/pyOpenCGA. To install any stable of development version of pyOpenCGA we will first need to clone the right branch of OpenCGA repository and install the library using the setup.py file.

Code Block

language	bash
theme	RDark

## Latest stable version
git clone -b master https://github.com/opencb/opencga.git

## Move to the pyOpenCGA client folder
cd opencga/opencga-client/src/main/python/pyOpenCGA/

## Install the library
python setup.py install

Library Implementation

Developers only need to create an instance of the ConfigClientClientConfiguration class passing it as an argument to the OpenCGAClient. They can optionally pass the user and password or a valid token to start doing calls as an authenticated user. The only role of the OpenCGAClient class is to work as a factory of the actual clients.

Code Block

language	py
theme	RDark

## Import OpenCGAClient and ConfigClientClientConfiguration classes
from pyopencga.opencga_client import OpenCGAClient
from pyopencga.opencga_config import ConfigClientClientConfiguration

## Creating ConfigClient
host a ClientConfiguration: 
# This can be done by passing the path to the main client-configuration.yml file
config = 'localhost:8080/opencga'
cc = ConfigClient()
config_dict = cc.get_basic_config_dict(hostClientConfiguration('/opt/opencga/conf/client-configuration.yml')
# Or by creating a dictionary using the below format passing the OpenCGA host to point to
config = ClientConfiguration({
    "rest": {
            "host": "http://bioinfo.hpc.cam.ac.uk/opencga-demo"
    }
})

## Create an instance of OpenCGAClient passing the user credentialsconfiguration
oc = OpenCGAClient(configuration=config_dict, user="user", pwd="password"config)


## Authenticate the user. Password is optional and if this is not passed to the login method, it will be prompted to the user
oc.login('user')
# or
oc.login('user', 'password')

Design

OpenCGAClient class works as a factory containing all the different clients necessary to call to any REST web service.

As described in RESTful Web Services#RESTResponse, most of the web services return a QueryResponse object containing a list of QueryResults. This structure has been maintained in the Python library and everytime a call to any WS is done, the response is automatically encapsulated into a custom QueryResponse RESTResponse class that automatically stores all the different values returned and defines a few public methods to help users navigating through the data.

The QueryResponse RESTResponse methods developed are:

Code Block

language	py
theme	RDark

## Return the first QueryResult from an iterator to help iterating over all the QueryResponseresults.

firstresults()

## Return the firsttotal resultnumber fromof the 'index' QueryResult. 
## If 'index' is not provided, it will automatically show the first result of the first QueryResult
result(index)

## Return an iterator to help iterating over matches taking of all the resultsQueryResponses.
resultsnum_matches()


## Return the total number of results obtainedtaking of all the QueryResponses.
num_total_results()

API

The client implements at least one function for each available resource (user, project, study, etc.). Currently, the following functions are available:

Code Block

language	py
theme	RDark

## User
oc.users.login(user, pwd, **options)
oc.users.refresh_token(user, **options)
oc.users.logout()

oc.users.info(query_id, **options)
oc.users.create(data, **options)
oc.users.update(query_id, data, **options)
oc.users.delete(**options)

oc.users.projects(user, **options)
oc.users.update_password(user, pwd, newpwd, **options)
oc.users.configs(user, **options)
oc.users.update_configs(user, data, action, **options)
oc.users.filters(user, **options)
oc.users.update_filters(user, data, action, **options)
oc.users.update_filter(user, filter_name, data, **options)


## Projects
oc.projects.info(query_id, **options)
oc.projects.create(data, **options)
oc.projects.update(query_id, data, **options)
oc.projects.delete(**options)

oc.projects.search(**options)
oc.projects.studies(project, **options)
oc.projects.aggregation_stats(project, **options)
oc.projects.increment_release(project, **options)


## Studies
oc.studies.info(query_id, **options)
oc.studies.create(data, **options)
oc.studies.update(query_id, data, **options)
oc.studies.delete(**options)

oc.studies.acl(query_id, **options)
oc.studies.update_acl(memberId, data, **options)

oc.studies.groups(study, **options)
oc.studies.search(**options)
oc.studies.scan_files(study, **options)
oc.studies.resync_files(study, **options)
oc.studies.create_groups(study, data, **options)
oc.studies.update_groups(study, data, action, *options)
oc.studies.update_users_from_group(study, group, data, action, **options)
oc.studies.permission_rules(study, entity, **options)
oc.studies.update_permission_rules(study, entity, data, action, **options)
oc.studies.variablesets(study, **options)
oc.studies.update_variablesets(study, data, action, **options)
oc.studies.aggregation_stats(study, **options)
oc.studies.update_variable_from_variableset(study, variable_set, action, **options)


## Individuals
oc.individuals.info(query_id, **options)
oc.individuals.create(data, **options)
oc.individuals.update(query_id, data, **options)
oc.individuals.delete(**options)

oc.individuals.search(**options)
oc.individuals.aggregation_stats(**options)
oc.individuals.update_annotations(query_id, annotationset_id, data, **options)

oc.individuals.acl(query_id, **options)
oc.individuals.update_acl(memberId, data, **options)


## Samples
oc.samples.info(query_id, **options)
oc.samples.create(data, **options)
oc.samples.update(query_id, data, **options)
oc.samples.delete(**options)

oc.samples.search(**options)
oc.samples.load(file, **options)
oc.samples.aggregation_stats(**options)
oc.samples.update_annotations(query_id, annotationset_id, data, **options)

oc.samples.acl(query_id, **options)
oc.samples.update_acl(memberId, data, **options)


## Files
oc.files.info(query_id, **options)
oc.files.create(data, **options)
oc.files.update(query_id, data, **options)
oc.files.delete(**options)

oc.files.search(**options)
oc.files.aggregation_stats(**options)
oc.files.bioformats(**options)
oc.files.formats(**options)
oc.files.scan_folder(folder, **options)
oc.files.list_folder(folder, **options)
oc.files.content(file, **options)
oc.files.grep(file, **options)
oc.files.refresh(file, **options)
oc.files.tree_folder(folder, **options)
oc.files.upload(data, **options)
oc.files.download(file, **options)
oc.files.update_annotations(query_id, annotationset_id, data, **options)

oc.files.acl(query_id, **options)
oc.files.update_acl(memberId, data, **options)


## Jobs
oc.jobs.info(query_id, **options)
oc.jobs.create(data, **options)
oc.jobs.update(query_id, data, **options)
oc.jobs.delete(**options)

oc.jobs.search(**options)
oc.jobs.visit(job, **options)

oc.jobs.acl(query_id, **options)
oc.jobs.update_acl(memberId, data, **options)

## Families
oc.families.info(query_id, **options)
oc.families.create(data, **options)
oc.families.update(query_id, data, **options)
oc.families.delete(**options)

oc.families.search(**options)
oc.families.aggregation_stats(**options)
oc.families.update_annotations(query_id, annotationset_id, data, **options)

oc.families.acl(query_id, **options)
oc.families.update_acl(memberId, data, **options)


## Cohorts
oc.cohorts.info(query_id, **options)
oc.cohorts.create(data, **options)
oc.cohorts.update(query_id, data, **options)
oc.cohorts.delete(**options)

oc.cohorts.search(**options)
oc.cohorts.aggregation_stats(**options)
oc.cohorts.samples(self, cohort, **options)
oc.cohorts.update_annotations(query_id, annotationset_id, data, **options)

oc.cohorts.acl(query_id, **options)
oc.cohorts.update_acl(memberId, data, **options)


## Disease Panels
oc.panels.info(query_id, **options)
oc.panels.create(data, **options)
oc.panels.update(query_id, data, **options)
oc.panels.delete(**options)

oc.panels.search(**options)

oc.panels.acl(query_id, **options)
oc.panels.update_acl(memberId, data, **options)

Table of Contents:

Table of Contents

indent	20px

Page tree

Versions Compared

Old Version 10

New Version 11

Key

pyOpenCGA Overview

Installation

PyPI

Source Code

Library Implementation

Design

API

Page tree

Page History

Versions Compared

Old Version 10

New Version 11

Key

pyOpenCGA Overview

Installation

PyPI

Source Code

Library Implementation

Design

API