## Latest stable version
pip install pyopencga

## Get latest stable version from https://github.com/opencb/opencga/releases. You can use wget from the terminal
wget https://github.com/opencb/opencga/releases/download/v2.0.0/opencga-2.0.0.tar.gz

## Decompress
tar -zxvf opencga-2.0.0.tar.gz

## Move to the pyOpenCGA client folder
cd opencga-2.0.0/clients/python

## Install the library
python setup.py install

## Import ClientConfiguration class
from pyopencga.opencga_config import ClientConfiguration

## You can create a ClientConfiguration by using the path to the client-configuration.yml file (it can also accept a JSON file)
config = ClientConfiguration('opencga-2.0.0/conf/client-configuration.yml')

## Additionally, you can pass a dictionary using the same structure as the client-configuration.yml (the only required parameter is REST host)
config = ClientConfiguration({"rest": {"host": "http://bioinfo.hpc.cam.ac.uk/opencga-demo"}})

## Import ClientConfiguration and OpencgaClient class
from pyopencga.opencga_config import ClientConfiguration
from pyopencga.opencga_client import OpencgaClient

## Create an instance of OpencgaClient passing the configuration
config = ClientConfiguration('opencga-2.0.0/conf/client-configuration.yml')
oc = OpencgaClient(config)

## Two authentication options:
## Option 1. If the user has a valid token, it can be passed to start doing calls as an authenticated user
oc = OpencgaClient(config, token='TOKEN')

## Option 2. If no token is provided, the user must login with valid credentials. Password is optional (if it is not passed to the login method, it will be prompted to the user)
oc.login(user='USER')	## The password will be asked
# or
oc.login(user='USER', password='PASSWORD')

## You can logout by executing the following command, the token will be deleted. 
oc.logout()

## Create main clients
users = oc.users
projects = oc.projects
studies = oc.studies
files = oc.files
jobs = oc.jobs
families = oc.families
individuals = oc.individuals
samples = oc.samples
cohorts = oc.cohorts
panels = oc.panels

## Create analysis clients
alignments = oc.alignment
variants = oc.variant
clinical = oc.clinical
ga4gh = oc.ga4gh

## Create administrative clients
admin = oc.admin
meta = oc.meta
variant_operations = oc.variant_operations

## Look for the first 5 sample IDs of the study "study"
sample_result = oc.samples.search(study='study', limit=5, include='id')

## Returns the list of results for the response in position "response_pos" (response_pos=0 by default)
sample_response.get_results(response_pos)

## Returns the result in position "result_pos" for the response in position "response_pos" (response_pos=0 by default)
sample_response.get_result(result_pos, response_pos)

## Returns the list of responses
sample_response.get_responses()

## Returns the response in position "response_pos" (response_pos=0 by default)
sample_response.get_response(response_pos)

## Returns all results from the response in position "response_pos" as an iterator (response_pos=None returns all results for all QueryResponses)
sample_response.result_iterator(response_pos)

## Returns all response events by type "event_type" ('INFO', 'WARNING' or 'ERROR') (event_type=None returns all types of event)
sample_response.get_response_events(event_type)

## Returns all response events by type "event_type" ('INFO', 'WARNING or 'ERROR') for the response in position "response_pos" (event_type=None returns all types of event; response_pos=0 by default)
sample_response.get_result_events(event_type, response_pos)

## Return number of matches for the response in position "response_pos" (response_pos=None returns the number for all QueryResponses)
samplsamplesample_responsee_resultresponse.get_num_matches(response_pos)

## Return number of results for the response in position "response_pos" (response_pos=None returns the number for all QueryResponses)
sample_response.get_num_results(response_pos)

## Return number of insertions for the response in position "response_pos" (response_pos=None returns the number for all QueryResponses)
sample_response.get_num_inserted(response_pos)

## Return number of updates for the response in position "response_pos" (response_pos=None returns the number for all QueryResponses)
sample_response.get_num_updated(response_pos)

## Return number of deletions for the response in position "response_pos" (response_pos=None returns the number for all QueryResponses)
sample_resultresponse.get_num_deleted(response_pos)

## Print results of the query for the response in position "response_pos" (response_pos=None returns the results for all QueryResponses)
sample_resultresponse.print_results(fields='id', response_pos=0, limit=5, separator='\t', metadata=True, outfile='path/to/output.tsv')

# First, we need to import both the ClientConfiguration and the OpencgaClient
from pyopencga.opencga_config import ClientConfiguration
from pyopencga.opencga_client import OpencgaClient

# The main client-configuration.yml file has a "host" section to point to the REST OpenCGA endpoints.
# We need to either pass the path to the configuration file or a dictionary with the format of the file.
config = ClientConfiguration({"rest": {"host": "http://bioinfo.hpc.cam.ac.uk/opencga-demo"}})

# And finally create an instance of the OpencgaClient passing the configuration
oc = OpencgaClient(config)

# Now we need to authenticate.
oc.login(user='demo', password='demo')

# We can check that we've logged in successfully by printing the obtained token
print(oc.token)

# We can get the name of all the available projects
for project in oc.projects.search().get_results():
    print(project['id'])

# We can also get the name of all the available studies
for study in oc.studies.search(project='exomes_grch37').get_results():
    print(study['id'])

# Let's assume our installation already has been populated and we are interested in looking for 
# all the families containing a concrete disorder: 'Rod-cone dystrophy'. To fetch this data, we will need to:
family_query_response = oc.families.search(study="study1", limit=10, disorders="Rod-cone dystrophy", include="id,members.id")

# Running oc.families.search(disorders="Rod-cone dystrophy") with only the 'disorders' field would only work
# if only one project and one study has been defined. However, we expect that most of the OpenCGA installations
# will have more than one study, so we need to specify the families of which study we are looking for.

# Additionally, we are passing limit = 10 to limit the number of family results we want to fetch. Because this
# is an example, we are simply limiting the number of results to 10. 

# Finally, if we don't specify anything else, all the values from the Family will be fetched. When writing 
# scripts, we are normally interested in just a few fields of a whole entry, so adding the include/exclude fields
# will definitely help us getting the results faster as we will avoid sending data we are going to discard through
# the network. In this particular case, we are only interested in getting the Family id and the id of the members
# of the family. To know what fields you can include/exclude, please follow the data models we have defined.

# family_query_response is an instance of the QueryResponse class defined in the Python library. To read the fields,
# we could do the following:
family_query_response.time         # Get the time spent with the REST call
family_query_response.apiVersion   # Get the API version of the REST
family_query_response.queryOptions # Get the QueryOptions of the call (include/exclude, limit, skip, count...)
family_query_response.warning      # Get warning messages
family_query_response.error        # Get error messages
family_query_response.responses    # Get the responses (Array of QueryResults containing the data queried)

# We can iterate over all the results to print all the id's using the 'results()' method such as in the example below:
for family in family_query_response.results():
	print (family['id'])

# We could have this same behaviour if we run the following script, which is why 'results()' is that useful.
for query_result in family_query_response.responses:
	for family in query_result['results']:
		print (family['id'])

# If we want to know exactly the amount of results obtained, we can run:
family_query_response.num_results()

# Or let's say that instead of querying the data, we only wanted to get the number of families in the study with that disorder. In that case, we could:
family_count_response = oc.families.search(study="study1", disorders="Rod-cone dystrophy", count=True)

# And then get the number of matches by calling to the num_matches method:
family_count_response.num_matches()

# Now that we know how to work with the OpenCGA QueryResponse object, we will write a script to fetch all the variants 
# falling in the 'BMPR2' gene found in any member of the family. In this case, we will limit the variant query to a maximum
# of 10 results excluding the sample information (sample information can be huge and would make this query much slower).
for family in oc.families.search(study="study1",limit=10,disorders="Rod-cone dystrophy",include="id").results():
    print ("Family: " + family['id'])
    variant_response = oc.variant.query(family=family['id'], gene= 'BMPR2', study='study1', includeSamples=None, limit=10)
    if variant_response.num_total_results() > 0:
        for variant in variant_response.results():
            print (variant['chromosome'] + ":" + str(variant['start']) + "-" + str(variant['end']) + '\t' + variant['type'])
    else:
        print ("No variant results found")
    print()