Skip to content

Commit fc0f676

Browse files
ckopanosckopanos
authored
Merge pull request #10 from saphetor/minor-changes-to-readme
added syntax highlighting to readme examples
2 parents 8e00d86 + f7fe98a commit fc0f676

3 files changed

Lines changed: 97 additions & 85 deletions

File tree

‎README.md‎

Lines changed: 95 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
This client is still in beta but it is a good for playing around with the API.
66

77
### Python versions
8-
Python version 3 is supported.
8+
Python versions 3.5 and greater are supported.
99

1010
### Installation
1111
We suggest that you create a python virtual environment instead of globally installing the library.
@@ -61,33 +61,35 @@ section below for how to annotate a VCF file with the annotations that are of in
6161
### Using the client in your code
6262

6363
Using the API client is quite straightforward. Just install the API client package and use the following in your code:
64-
65-
from varsome_api.client import VarSomeAPIClient
66-
# API key is not required for single variant lookups
67-
api_key = 'Your token'
68-
api = VarSomeAPIClient(api_key)
69-
# if you don't have an API key use
70-
# api = VarSomeAPIClient()
71-
# fetch information about a variant into a dictionary
72-
result = api.lookup('chr7-140453136-A-T', params={'add-source-databases': 'gnomad-exomes,refseq-transcripts'}, ref_genome='hg19')
73-
# access results e.g. the transcripts of the variant
74-
transcripts = result['refseq_transcripts']
75-
# fetch information for multiple variants
76-
variants = ['chr19:20082943:1:G','chr22:39777823::CAA']
77-
# Results will be an array of dictionaries. An API key will be required for this request
78-
results = api.batch_lookup(variants, params={'add-source-databases': 'gnomad-exomes,gnomad-genomes'}, ref_genome='hg19')
79-
# look at the python doc for batch_lookup method for additional parameters
80-
64+
```python
65+
from varsome_api.client import VarSomeAPIClient
66+
# API key is not required for single variant lookups
67+
api_key = 'Your token'
68+
api = VarSomeAPIClient(api_key)
69+
# if you don't have an API key use
70+
# api = VarSomeAPIClient()
71+
# fetch information about a variant into a dictionary
72+
result = api.lookup('chr7-140453136-A-T', params={'add-source-databases': 'gnomad-exomes,refseq-transcripts'}, ref_genome='hg19')
73+
# access results e.g. the transcripts of the variant
74+
transcripts = result['refseq_transcripts']
75+
# fetch information for multiple variants
76+
variants = ['chr19:20082943:1:G','chr22:39777823::CAA']
77+
# Results will be an array of dictionaries. An API key will be required for this request
78+
results = api.batch_lookup(variants, params={'add-source-databases': 'gnomad-exomes,gnomad-genomes'}, ref_genome='hg19')
79+
# look at the python doc for batch_lookup method for additional parameters
80+
```
8181
If errors occur while using the client, an exception will be thrown.
8282
You may wish to catch this exception and proceed with your own code logic:
8383

84-
from varsome_api.client import VarSomeAPIClient, VarSomeAPIException
85-
api = VarSomeAPIClient()
86-
try:
87-
result = api.lookup('chr19:20082943:1:G', ref_genome='hg64')
88-
except VarSomeAPIException as e:
89-
# proceed with your code flow e.g.
90-
print(e) # 404 (invalid reference genome)
84+
```python
85+
from varsome_api.client import VarSomeAPIClient, VarSomeAPIException
86+
api = VarSomeAPIClient()
87+
try:
88+
result = api.lookup('chr19:20082943:1:G', ref_genome='hg64')
89+
except VarSomeAPIException as e:
90+
# proceed with your code flow e.g.
91+
print(e) # 404 (invalid reference genome)
92+
```
9193

9294
To view available request parameters (used by the `params` method parameter), refer to an example at [api.varsome.com](https://api.varsome.com).
9395

@@ -98,86 +100,96 @@ To understand how annotation properties are included in the JSON response, pleas
98100
If you don't want to read through each attribute in the JSON response, you can wrap the result into a Python
99101
[JSON model](http://jsonmodels.readthedocs.io/en/latest/readme.html):
100102

101-
from varsome_api.client import VarSomeAPIClient
102-
from varsome_api.models.variant import AnnotatedVariant
103-
# API key is not required for single variant lookups
104-
api_key = 'Your token'
105-
api = VarSomeAPIClient(api_key)
106-
# fetch information about a variant into a dictionary
107-
result = api.lookup('chr7-140453136-A-T', params={'add-source-databases': 'gnomad-exomes,refseq-transcripts'}, ref_genome='hg19')
108-
annotated_variant = AnnotatedVariant(**result)
103+
```python
104+
from varsome_api.client import VarSomeAPIClient
105+
from varsome_api.models.variant import AnnotatedVariant
106+
# API key is not required for single variant lookups
107+
api_key = 'Your token'
108+
api = VarSomeAPIClient(api_key)
109+
# fetch information about a variant into a dictionary
110+
result = api.lookup('chr7-140453136-A-T', params={'add-source-databases': 'gnomad-exomes,refseq-transcripts'}, ref_genome='hg19')
111+
annotated_variant = AnnotatedVariant(**result)
112+
```
109113

110114
You now have access to a set of shortcut attributes (these will be updated over time in the code base):
111115

112-
annotated_variant.chromosome
113-
annotated_variant.alt
114-
annotated_variant.genes # directly get the genes related to the variant
115-
annotated_variant.gnomad_exomes_af # etc
116-
116+
```python
117+
annotated_variant.chromosome
118+
annotated_variant.alt
119+
annotated_variant.genes # directly get the genes related to the variant
120+
annotated_variant.gnomad_exomes_af # etc
121+
```
117122
Or you may access other inner properties of other available properties:
118123

119-
# get gnomad exomes allele number
120-
allele_number = [gnomad_exome.an for gnomad_exome in annotated_variant.gnomad_exomes]
124+
```python
125+
# get gnomad exomes allele number
126+
allele_number = [gnomad_exome.an for gnomad_exome in annotated_variant.gnomad_exomes]
127+
```
121128

122129
JSON model-type objects that contain a `version` property, like `annotated_variant.gnomad_exomes`, are
123130
always returned as lists of objects. This is because the API has the ability to return multiple versions of
124131
annotation databases (although this is not currently publicly available). For consistency, therefore,
125132
these are always lists, though it is safe to assume that they will only include a single item. So it is safe
126133
to rewrite as:
127-
128-
try:
129-
allele_number = [gnomad_exome.an for gnomad_exome in annotated_variant.gnomad_exomes][0]
130-
except IndexError:
131-
pass # no gnomad exomes annotation for the variant
132-
134+
135+
```python
136+
try:
137+
allele_number = [gnomad_exome.an for gnomad_exome in annotated_variant.gnomad_exomes][0]
138+
except IndexError:
139+
pass # no gnomad exomes annotation for the variant
140+
```
141+
133142
#### Annotating a VCF using the client
134143

135144
To annotate a VCF you can base your code on the VCFAnnotator object. This provides a basic implementation that
136145
will annotate a VCF file using a set of the available annotations. It uses [PyVCF](https://github.com/jamescasbon/PyVCF) to read and write to VCF files.
137146

138-
from varsome_api.vcf import VCFAnnotator
139-
api_key = 'Your token'
140-
vcf_annotator = VCFAnnotator(api_key=api_key, ref_genome='hg19', get_parameters={'add-all-data': 1, 'expand-pubmed-articles': 0})
141-
vcf_file = 'input.vcf'
142-
output_vcf_file = 'annotated.vcf'
143-
vcf_annotator.annotate(vcf_file, output_vcf_file)
144-
147+
```python
148+
from varsome_api.vcf import VCFAnnotator
149+
api_key = 'Your token'
150+
vcf_annotator = VCFAnnotator(api_key=api_key, ref_genome='hg19', get_parameters={'add-all-data': 1, 'expand-pubmed-articles': 0})
151+
vcf_file = 'input.vcf'
152+
output_vcf_file = 'annotated.vcf'
153+
vcf_annotator.annotate(vcf_file, output_vcf_file)
154+
```
155+
145156
To annotate the VCF file with the annotations that you are interested in, you need only override 2 methods
146157
(`annotate_record` and `add_vcf_header_info`) in the VCFAnnotator class:
147158

148-
from varsome_api.vcf import VCFAnnotator
149-
from vcf.parser import _Info
150-
class MyVCFAnnotator(VCFAnnotator):
159+
```python
160+
from varsome_api.vcf import VCFAnnotator
161+
from vcf.parser import _Info
162+
class MyVCFAnnotator(VCFAnnotator):
163+
164+
def annotate_record(self, record, variant_result):
165+
"""
166+
:param record: vcf record object
167+
:param variant_result: AnnotatedVariant object
168+
:return: annotated record object
169+
"""
170+
record.INFO['gnomad_exomes_AN'] = variant_result.gnomad_exomes_an
171+
# if you wish to also include the default annotations
172+
# return super().annotate_record(record, variant_result)
173+
return record
151174

152-
def annotate_record(self, record, variant_result):
153-
"""
154-
:param record: vcf record object
155-
:param variant_result: AnnotatedVariant object
156-
:return: annotated record object
157-
"""
158-
record.INFO['gnomad_exomes_AN'] = variant_result.gnomad_exomes_an
159-
# if you wish to also include the default annotations
160-
# return super().annotate_record(record, variant_result)
161-
return record
162175

163-
164-
def add_vcf_header_info(self, vcf_template):
165-
"""
166-
Adds vcf INFO headers for the annotated values provided
167-
:param vcf_template: vcf reader object
168-
:return:
169-
"""
170-
vcf_template.infos['gnomad_exomes_AN'] = _Info('gnomad_exomes_AN', '.', 'Integer',
171-
'GnomAD exomes allele number value', None, None)
172-
# if you wish to also include the default headers
173-
# super().add_vcf_header_info(vcf_template)
176+
def add_vcf_header_info(self, vcf_template):
177+
"""
178+
Adds vcf INFO headers for the annotated values provided
179+
:param vcf_template: vcf reader object
180+
:return:
181+
"""
182+
vcf_template.infos['gnomad_exomes_AN'] = _Info('gnomad_exomes_AN', '.', 'Integer',
183+
'GnomAD exomes allele number value', None, None)
184+
# if you wish to also include the default headers
185+
# super().add_vcf_header_info(vcf_template)
174186

175-
api_key = 'Your token'
176-
vcf_annotator = MyVCFAnnotator(api_key=api_key, ref_genome='hg19', get_parameters={'add-all-data': 1, 'expand-pubmed-articles': 0})
177-
vcf_file = 'input.vcf'
178-
output_vcf_file = 'annotated.vcf'
179-
vcf_annotator.annotate(vcf_file, output_vcf_file)
180-
187+
api_key = 'Your token'
188+
vcf_annotator = MyVCFAnnotator(api_key=api_key, ref_genome='hg19', get_parameters={'add-all-data': 1, 'expand-pubmed-articles': 0})
189+
vcf_file = 'input.vcf'
190+
output_vcf_file = 'annotated.vcf'
191+
vcf_annotator.annotate(vcf_file, output_vcf_file)
192+
```
181193
182194
### API Documentation
183195

‎scripts/varsome_api_annotate_vcf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
#!/usr/bin/env python
1+
#!/usr/bin/env python3
22
import argparse
33
import sys
44

‎scripts/varsome_api_run.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
#!/usr/bin/env python
1+
#!/usr/bin/env python3
22
import argparse
33
import json
44
import sys

0 commit comments

Comments
 (0)