Skip to content

Latest commit

 

History

History
178 lines (120 loc) · 6.78 KB

API.rst

File metadata and controls

178 lines (120 loc) · 6.78 KB
Raw

API

(OpenCRAVAT 1.6.0 feature)

OpenCRAVAT GUI supports web API for submitting a job, checking the status of a job, creating a job report, and downloading a job report. Examples below are in Python, using requests module. If you want to try the examples, first open Python console and run the below and then follow examples.

f = open('test_input.txt', 'w')
f.write('chr10 8055656 + A T s3 var001\n')
f.close()

Logging in

The instruction above are based on using the public OpenCRAVAT server mode. If you are instead running against a personal instance of the OpenCRAVAT GUI, you can skip this step and replace all mentions of session below with requests. For example session.get is replaced by requests.get.

import requests
import base64
session = requests.Session()
reply = session.get('https://run.opencravat.org/server/login', headers={'Authorization': 'Basic ' + base64.b64encode(b'USERNAME:PASSWORD').decode()})

Submitting a job

Submit a new input file for annotation.

  • Method: POST
  • Location: /submit/submit
  • Consumes: Multipart/form-data
  • Produces: a JSON object, notable fields of which are as follows.
    • status['status']: 'Submitted' for successful job submission
    • id: job ID of the submitted job
  • Form data parameters:
    • annotators: list. Annotation modules
    • reports: list. Report types
    • assembly: string. Genome assembly of input
    • forcedinputformat: string. Input format
    • note: string
  • File data: "file_x" where x is a number from 0 should be used to enumerate input files. Multiple files can be submitted as one job.

Example:

r = session.post('https://run.opencravat.org/submit/submit', files={'file_0':open('test_input.txt')}, data={'options': '{"annotators": ["clinvar"], "reports": ["text"], "assembly": "hg38", "note": "test run"}'})
print(r.json())
job_id = r.json()['id']

Checking job status

Get the status of a job (in queue, running, finished, failed)

  • Method: GET
  • Location: /submit/jobs/<JOBID>/status (replace JOBID with the "id" value obtained from the response of the submission POST request.)
  • Produces: a JSON object, notable fields of which are as follows.
    • status: string. Latest status update of the job. When the job finishes, it will be "Finished".

Example:

r = session.get('https://run.opencravat.org/submit/jobs/' + job_id + '/status')
print(r.json()['status'])

Creating report files

Request a report of the annotated variants in one of the supported formats.

  • Method: POST
  • Location: /submit/jobs/JOBID/reports/REPORTTYPE (replace JOBID with the "id" value obtained from the response of the submission POST request and REPORTTYPE with a report type string.)
  • Produces: string. "done" means normal return.

Example:

r = session.post('https://run.opencravat.org/submit/jobs/' + job_id + '/reports/vcf')
print(r.json)

Checking report files available for download

Check the completed reports for a job.

  • Method: GET
  • Location: /submit/jobs/JOBID/reports
  • Produces: a JSON list with the report types the files for which are available for download

Example:

r = session.get('https://run.opencravat.org/submit/jobs/' + job_id + '/reports')
print(r.json())

Downloading report files

Download a report containing annotated variants.

  • Method: GET
  • Location: /submit/jobs/JOBID/reports/REPORTTYPE (replace JOBID with the "id" value obtained from the response of the submission POST request and REPORTTYPE with a report type string.)
  • Produces: HTTP(S) response with a report file. See "Content-Type" in its headers for the type of the file and "Content-Disposition" for the filename of the file.

Example:

r = session.get('https://run.opencravat.org/submit/jobs/' + job_id + '/reports/vcf')
wf = open('output.vcf','w')
wf.write(r.text)
wf.close()

Single variant annotation

Get annotation on a single variant as a json object. This endpoint does not require login.

  • Method: GET
  • Location: /submit/annotate
  • Parameters
    • chrom: chromosome
    • pos: position (1-based)
    • ref_base: reference base
    • alt_base: alternate base
    • annotators: comma-delimited string of annotation module names
  • Produces: a JSON object with annotation result, which is organized by annotation module names as the first level key and column names as the second level key.

Example:

r=requests.get('https://run.opencravat.org/submit/annotate?chrom=chr1&pos=12777320&ref_base=G&alt_base=T&annotators=clinvar,dbsnp,exac_gene,go,rvis')
print(r.json())
{'clinvar': {'sig': '', 'disease_refs': '', 'disease_names': '', 'rev_stat': '', 'id': ''}, 'dbsnp': {'snp': 'rs112368379'}, 'exac_gene': {'exac_pli': 3.89692512946575e-06, 'exac_prec': 0.369464079984044, 'exac_pnull': 0.630532023090827, 'exac_nontcga_pli': 2.29346103558518e-06, 'exac_nontcga_prec': 0.28488011039975, 'exac_nontcga_pnull': 0.715117596139215, 'exac_nonpsych_pli': 2.04859216406268e-06, 'exac_nonpsych_prec': 0.250289965336068, 'exac_nonpsych_pnull': 0.749707986071768, 'exac_del_score': None, 'exac_dup_score': None, 'exac_cnv_score': None, 'exac_cnv_flag': None}, ..., 'crx': {'uid': 'noid', 'chrom': 'chr1', 'pos': 12777320, 'ref_base': 'G', 'alt_base': 'T', 'note': '', 'coding': 'Yes', 'hugo': 'PRAMEF12', 'transcript': 'ENST00000357726.4', 'so': 'synonymous', 'achange': 'A391A', 'all_mappings': '{"PRAMEF12":[["O95522","A391A","synonymous","ENST00000357726.4","G1173T"]]}'}}
r=requests.get('https://run.opencravat.org/submit/annotate?chrom=chr7&pos=140753336&ref_base=A&alt_base=T')
print(r.json())
{"segway_kidney": {"fetal_kidney": "Transcribed"}, "segway_lung": {"fetal_lung": "Transcribed"}, "segway_muscle": {"fetal_muscle_trunk": "Transcribed", "skeletal_muscle_female": "Transcribed", "skeletal_muscle_male": "Quiescent"}, "segway_ovary": {"ovary": "Quiescent"}, "abraom": null, "biogrid": ..., "thousandgenomes": null, "thousandgenomes_ad_mixed_american": null, "thousandgenomes_african": null, "thousandgenomes_east_asian": null, "thousandgenomes_european": null, "thousandgenomes_south_asian": null, "vest": null, "crx": {"uid": "", "chrom": "chr7", "pos": 140753336, "ref_base": "A", "alt_base": "T", "note": "", "coding": "Yes", "hugo": "BRAF", "transcript": "ENST00000288602.10", "so": "missense", "achange": "V600E", "all_mappings": "{\"BRAF\":[[\"P15056\",\"V600E\",\"missense\",\"ENST00000288602.10\",\"T1799A\"]]}"}}