araport.org@araport

Integrate JBrowse REST API with ADAMAVivek Krishnakumar

12/03/2015

araport.org@araport

Outline• JBrowse REST API spec• ADAMA endpoints• Mapping JBrowse to ADAMA endpoints• Extending JBrowse REST feature store• Handling Auth in JBrowse 1.x• Use Case– Integrate Chromatin States data into JBrowse via

ADAMA• Summary• Challenges

araport.org@araport

JBrowse REST API spec• Javascript based portable genome browser tool

developed by GMOD community• Ships with REST feature and names store adapter• REST feature store requires access to following

endpoints via HTTP GET:– (base)/stats/global– (base)/stats/region/(refseq)?start=123&end=456– (base)/stats/regionFeatureDensities/(refseq)?

start=123&end=456&basesPerBin=20000– (base)/features/(refseq)?start=234&end=5678

• Can provide feature, sequence, and quantitative data for display

• Accepted response type: application/jsonhttp://gmod.org

/wiki/JBrowse_Configuration_Guide#Writing_JBrowse-compatible_Web_Services

araport.org@araport

ADAMA endpoints• Araport Data And Microservices API– Developed by WalterM and MattV

• Encapsulates python code into reusable docker containers

• Exposes internal logic as API endpoints:– query, generic adapters via HTTP GET

• (base)/search• (base)/list

– passthrough adapters via HTTP GET and POST• (base)/access

• Implements token based Auth via iPlant OAuth2https://github.com/Arabidopsis-Information-Portal/adama

araport.org@araport

Mapping JBrowse to ADAMA endpoints

• ADAMA (currently) doesn’t allow defining custom endpoints

• So, we have to map the 4 JBrowse endpoints to the 2 ADAMA endpoints

• Proposed endpoint mapping:JBrowse ADAMA

(base)/stats/global (base)/search?q=global

(base)/stats/region (base)/search?q=region

(base)/stats/regionFeatureDensities (base)/search?q=regionFeatureDensities

(base)/features (base)/search?q=features

(base)/list?q=makeTrackListJson

araport.org@araport

Extending JBrowse REST feature store

• JBrowse/Store/SeqFeature/REST handles requests from the browser to the configured API service– Understands the 4 pre-defined endpoints

• REST feature store extended based on proposed endpoint mapping

• Utilize JBrowse Plugin architecture to develop Araport plugin: Araport/Store/SeqFeature/REST

http://gmod.org/wiki/JBrowse_Configuration_Guide#Writing_JBrowse_Plugins

araport.org@araport

Handling Auth in JBrowse 1.x• ADAMA (currently) requires all requests to be

accompanied by an Authorization Bearer $TOKEN• JBrowse 1.x does not support OAuth2 implicit

flow, thus cannot generate tokens• Solution:

– OAuth2 $TOKEN created with unlimited validity (-1)• $TOKEN generated by Araport anonymous user• $TOKEN scope limited to ADAMA services

– Araport/Store/SeqFeature/RESTAuth hard codes $TOKEN

– Araport/Store/SeqFeature/REST inherits from RESTAuth

araport.org@araport

Use CaseIntegrate Chromatin States data into JBrowse via ADAMA

• Published dataset representing a landscape of Arabidopsis thaliana chromatin states using 16 features, including DNA sequence, CG methylation, histone variants, and modifications

• Data represents chromosomal regions (start/stop coordinates) corresponding with 9 distinct chromatin states

• Published with manuscript as supplementary dataset (in XLS format)

Sequeira-Mendes, J., Aragüez, I., Peiró, R., Mendez-Giraldez, R., Zhang, X., Jacobsen, S. E., ... & Gutierrez, C. (2014). The functional topography of the Arabidopsis genome is organized in a reduced number of linear motifs of chromatin states. The Plant Cell, 26(6), 2351-2366.

araport.org@araport

• Develop ADAMA adapter to dynamically query data from desired region and represent as JBrowse compatible JSON

• Code: https://github.com/Arabidopsis-Information-Portal/chromatin_states_to_jbrowse

• Implementation logic:– Data transformed from 9 XLS worksheets into individual GFF3 files– Pythonic parser developed using gffutils, allowing range querying (via intermediary

sqlite database)– ADAMA metadata.yml written which describes dependencies, endpoints and

provenance• Data hosted with code (due to small size, well within

GitHub file size limits)• ADAMA namespace created and adapter registered• Available in API explorer (search for ‘chromatin’)

Use CaseIntegrate Chromatin States data into JBrowse via ADAMA

https://jira.araport.org/browse/MINE-1078

araport.org@araport

Integrate Chromatin States data into JBrowse via ADAMA• JBrowse tracks configured to talk to registered ADAMA endpoint• End result visible in screenshot above• Live view: https://apps.araport.org/jbrowse/?

data=arabidopsis&loc=Chr3:11355449..11407858&tracks=chromatin_state_1,chromatin_state_2,chromatin_state_3,chromatin_state_4,chromatin_state_5,chromatin_state_6,chromatin_state_7,chromatin_state_8,chromatin_state_9,Araport11_gene_models

araport.org@araport

Summary• Extended JBrowse to integrate with

ADAMA endpoints• Exposed a published community

dataset via ADAMA as an API• Exposed track configuration via

ADAMA API• Visualized dataset in JBrowse via

ADAMA API

araport.org@araport

Challenges• Making web service calls to ADAMA

requires Authorization $TOKEN• JBrowse needs to hard code the

Authorization $TOKEN• Track configuration needs to be

manually added to JBrowse• Scaling to larger datasets not

feasible via GitHub route

araport.org@araport

Acknowledgements• JCVI Araport Team– Chia-Yi Cheng– Agnes Chan– Chris Town

• TACC Araport Team–Walter Moreira–Matthew Vaughn

• Prof. Crisanto Gutierrez (CBMSO)