Repository files navigation

jsProteinMapper is a browser-based tool for interactive visualization of genomic alterations in relation to the protein structure of the gene product.

This guide contains information for:

• users: how to use the widget to interact with your data
• developers: how to add the widget to your page, configure it with your desired data sources, and interact with it using javascript.

Check it out

The jsProteinMapper widget lets you see where a variant of interest falls in relation to the structure of the protein - for example, if it is in a functional domain, or at the site of a particular active group. In addition, it can display graphs ("tracks") of previously-reported data for context. In order to interactively explore the data, use your mouse or touchscreen to zoom in and out, navigate around the protein, and show/hide information.

By default, the structure of the whole protein is displayed in the widget. However, this "wide view" can make it hard to see certain details around locations of interest. Similarly, each variant track is initially scaled to show the full range of the data. The widget provides a number of ways to zoom in and out to explore the data most effectively.

• Using the scroll wheel (mouse - anywhere on the widget) or pinch gesture (touchscreen - on the protein structure), you can control the zoom on the X-axis to get a closer look. Click (or touch) and drag lets you move the whole structure left or right.
• Double-clicking on the protein structure will also zoom in (X-axis)
• A double-click on avariant track will zoom in on theY-axis of that track, to show lower-frequency events more clearly. If you zoom in too far, the zoom level resets.
• If you are using a PC, the variant tracks can also be zoomed in and out using the mouse wheel while holding the shift key. On a touch-enabled device, you can zoom on variant tracks using pinch gestures on the track of interest.
• To zoom directly to an area of interest, hold shift while clicking and dragging. This will draw a rectangle, and the widget will zoom to that region when you release the mouse button. If this is done on a variant track, you can zoom in X and Y simultaneously.

In addition, each variant track contains a control panel with buttons for zooming in and out of both axes, and resetting the axes to the initial zoom level. The y-axis scale can be drawn with either a linear (default) or logarithmic scale. The control panels can be turned on and off using theoptions window.

To see more information - for example, details of a protein domain or a variant - simply hover your mouse (or tap a touchscreen) to reveal a popup tooltip. If you prefer clicking, rather than hovering, to show the tooltip, use theoptions window to choose this mode of action.

In the upper right corner of widget is an "Options" button, which brings up a window with options for configuring the behavior of certain actions:

• Show/hide the clickable control panels
• Switch between click and hover mode for showing additional information in the tooltip

• jsproteinmapper.css
• jQuery
• d3.js (version 4)
• d3tip.js
• jsproteinmapper.js
• your own javascript, which callsnew jsProteinMapper(); (see below)

When jsproteinmapper.js is executed, a constructor function namedjsProteinMapper is added to the global workspace. Call this function to create an instance of the widget.

varwidget=newjsProteinMapper();

Then,configure andinitialize it.

widget.init(config);

The widget provides functions so that user scripts can interact in certains ways.

• init()
• setPfamData()
• setVariantOfInterest()
• setTracks()
• drawWidget()
• Helper functions
• helpers.pfamAjaxResults
• helpers.parseVariantString
• helpers.aggregate
  • Functions to generate tooltips:
    • helpers.tooltips.basicTooltip
    • helpers.tooltips.variantTable
    • helpers.tooltips.variantPiechart
    • helpers.tooltips.variantBarchart

Initializes the widget, creating html and svg elements for data visualization and graphical user interface.

Creating a widget with all default values is as simple as callinginit() with no arguments:

widget.init();

init removes existing widgets, creates a new widget in a container element (<div class='jsproteinmapper'></div>), and appends it to a target element. By default, the target is<body>. This behavior can be customized by providing a selector for a target element. This, and other configuration options, are discussed in detail below.

The widget can be configured by passing in an object with desired options defined as fields. The object is then merged with default values (see below), so only non-default values need to be specified.

A full set of the default configuration options is below:

default_options={//target: selector for element to append the widget to.target:'body',//pfamData: data in string format defining the protein structurepfamData:null,//parsed response from pfam, via a proxy server//variantOfInterest: javascript object containing information about the variant of interestvariantOfInterest:{},//fields: codon, annotation//variantTracks: array of objects, one per trackvariantTracks:[],//array of objects, each of which has fields: 'label' and 'data'//width, height: dimensions of the widget (pixels)width:775,height:300,//fontSize: font size of the textfontSize:16,//variantColor: string representation of the color to highlight the variant of interestvariantColor:'red',//geometry of the protein functional domain annotationslollipopHeight:15,lollipopHeadSize:6,disulphideBridgeHeightIncrement:0,//geometry of the protein structure graphicregionHeight:16,sequenceHeight:7,//tracksYOffset: spacing, in pixels, between the protein structure and where the graphs of variant tracks starttracksYOffset:20,//padding: padding surrounding the widget, in pixelspadding:25,//trackFillColor: background color for variant trackstrackFillColor:'none',//showControls: [true|false] initial option for showing/hiding control panels.showControls:true,//tooltip: ['hover'|'click'] inital option for tooltip behaviortooltip:'hover',};

varoptions={sequenceHeight:10,padding:50,variantOfInterest:{codon:600,annotation:{'Protein alteration':'p.V600E'}},target:'#widget-container'};widget.init(options);

Protein structure data frompfam can be passed into the widget as aconfiguration option, but can also be added after the widget has been created, using the setPfamData() function. See thesection on fetching pfam data for more information about this process, as well as thehelper function that provide a default parsing pipeline for pfam data.

In this example, data is fetched from pfam via an ajax call, and the results are passed to the widget within the success callback.

varuniprot_id='P15056';//corresponds to BRAF//build the url that pfam expectsvarpfam_url='https://pfam.xfam.org/protein/'+uniprot_id+'/graphic';$.ajax({url:pfam_url,type:'GET',success:widget.helpers.pfamAjaxResults(function(r){//use the helper function to add tooltipswidget.setPfamData(r);//in the callback, set the pfam datawidget.drawWidget();//then draw the widget}),failure:function(data,textStatus,jqXHR){console.log('Failed to fetch data from PFAM',JSON.stringify(data));},});

Information about a variant of interest can be passed into the widget during initialization as aconfiguration option, but can also be added after the widget has been created, using the setVariant() function.

widget.setVariant({codon:245,//position of the alteration in protein coordinatesannotation:{'Protein alteration':'p.G245S'//text label to be displayed as a tooltip on mouseover/touch}});widget.drawWidget();//trigger a redraw

Variant tracks are bar graphs of other data that serve to provide context about the localization of variants relative to the protein structure. These data can be provided during initialization as aconfiguration option, but can also be added after the widget has been created, using the setTracks() function.

Whether setting up variant tracks during configuration or using thesetTracks() function, the data should be organized as anarray of objects - the array defines the order of the tracks, and each object contains fields for thelabel and thedata for that track. See the section onvariant track data objects for details of how the track data should be structured.

In the example below, two tracks of variant data are added, to allow comparisons to external and internal databases.

widget.setTracks([{label:'COSMIC database',data:cosmicDataString},{label:'In-house database',data:inhouseDataString}]);widget.drawWidget();//trigger a redraw

When you are done configuring the widget, either during initialization or using the API functions to add data, call thedrawWidget() function to complete the process and generate the interactive graphic.

//all done with configuration... yay!//now draw the widgetwidget.drawWidget();

The jsProteinMapper widget provides a number of helper functions that provide default implementations of certain tasks. These functions are exposed in an object named "helpers." Using these helper functions isnot required - they are merely a convenient option for getting started.

Querying data from pfam is often done asynchronously using AJAX, sohelpers.pfamAjaxResults()returns a function suitable for use as thesuccess callback of the ajax call. It alsotakes a function as an argument - this function is passed the parsed data structure and is responsible for continuing to doing useful things like drawing the widget.

Argument: callback function with prototypefunction(protein_structure){...}, to be called after parsing the data.
Return value: function with prototypefunction(data, status, jqXHR){...}, suitable for use as an ajax success callback.

To make it more clear what is happening, the implementation of the helper function is below.

functionpfamAjaxResults(callback){//create a function suitable for use as an ajax success callbackfunctionf(data,textStatus,jqXHR){varresponse=data;if(typeof(data)=="string")response=JSON.parse(response);//parse the json string if neededvarr=response[0];//extract the first result// iterate over the functional regions$.each(r.regions,function(i,e){//use the helper function makeBasicTooltip to add additional information about the region to a simple tooltipvartt=makeBasicTooltip({title:'Region: '+e.metadata.identifier+' ('+e.metadata.accession+')',Description:e.metadata.description,Coordinates:e.metadata.start+' - '+e.metadata.end+' (alignment region '+e.metadata.aliStart+' -'+e.metadata.aliEnd+')',Source:e.metadata.database});//add this object to the region as the "tooltip" field.e.tooltip=tt;});//pass the data on to the callback to continue processingcallback(r);}//return the above functionreturnf;};

See the helper function [helpers.tooltips.basicTooltip] for an explanation of the functionmakeBasicTooltip in the example code above.

This function creates structured data from a text string representation, which may come from a text file or database. It splits a text string with variant data into an array of objects. The text string should be a repeating sequence of tuples in the order [gene_name, cdna_change, protein_change]. The string is parsed into objects which have fields {codon(numeric), pdot(string) cdna(string)}. The string is split on whitespace - newlines, tabs, and spaces all count - so do not put any whitespace inside a value.

It returns an array of objects, each of which contains propertiescodon,pdot, andcdna.

functionparseVariantString(geneName,variants){m=variants.split(/\s+/);mut=[];for(ii=1;ii<m.length;ii+=3){vargene=m[ii];varcdna=m[ii+1];varprot=m[ii+2];varcodon=prot.match(/p.[a-zA-Z](\d+)/);//extract the location of the protein change//if the gene_name field matches the gene of interest, add it to the arrayif(gene.toLowerCase()==geneName.toLowerCase()){mut.push({codon:codon[1],pdot:prot,cdna:cdna);}}returnmut;}

This helper function takes a set of variants and uses d3's nest functionality to aggregate the data set by codon, counting the number of variants at each site, and within that, counting the number of each distinct variant. This is useful for creating meaningful tooltips that display the proportions of different alterations at each site within a protein structure.

The aggregate helper function expects an array of objects withcodon,pdot, andcdna fields. Seehelpers.parseVariantString for an example.

It returns an array of objects. Each object has the following format:

object={codon:1,//position in the protein structurecount:5,//number of alterations at this positionnestedAlterations:[ArrayofObjects]};

The most important fields arecodon andcount: these define the x and y location of the bars in the histogram representing the number of alterations at that location. The helper function also creates an array of objects and stores in the thenestedAlterations field. This array is used by the tooltip generator functions to create the bar charts, pie charts, or other display of the breakdown of variants reported at each position.

Displays text-based details of alteration frequency.

Displaysaggregated variant data in table form.

Displaysaggregated variant data in pie chart form.

Displaysaggregated variant data in bar chart form.

When protein structure information is fetched frompfam, the resulting JSON string must first be parsed to create a javascript object. The results are returned in an array; since we are only dealing with asingle result, the relevant information is in thefirst element of the array.

results=JSON.parse(json_string_from_pfam);//parse the json stringprotein_structure=results[0];//take first item from the array

By itself, these results are enough for the widget to draw the protein backbone and functional regions. Additional information about each region can be displayed in a tooltip by adding html to the "tooltip" field.

To retrieve the JSON data from pfam, create a URL that includes the Uniprot ID of the gene:

varuniprot_id='P15056';//corresponds to BRAF//build the url that pfam expectsvarpfam_url='https://pfam.xfam.org/protein/'+uniprot_id+'/graphic';//make an AJAX GET request$.ajax({url:pfam_url,type:'GET',success:successCallbackFcn},});

To provide data for the widget to use for drawing variant tracks above the protein structure, pass in an array of objects. Each object must contain the title for the track in the "label" field, and an array of objects in the "data" field.

The data must be an array of objects; each object must contain the propertycodon (required). By default, a simple histogram (bar chart) will be created to plot the number of events at each codon. To use this default histogram, a propertycount is required, describing how many events occurred at each codon. Bars are black by default, but if acolor property is defined, the specified color will be used instead. Additional properties can be optionally included and used to create tooltips with more detailed information about the variants reported at each location. Seehelpers.aggregate for more information.

To use the default histogram:

vardata=[{codon:1,count:5//this bar will be black by default},{codon:2,count:3,color:'black',//black is explicitly defined},{codon:3,count:15,color:'red',//this bar will be red}];

Advanced usage: ThedrawTrackItem property can be used to pass a callback function, which can be used to draw any desired visual representation of the data at the codon. The callback function signature should befunction(group,scale). Arguments:

1. group, the current<g> element, which is already transformed to the appropriate location for the codon, and which additional SVG elements should be added to.
2. scale, a function which will convert a numeric 'count' value to the appropriate pixel position.

Important: In order to make the element render appropriately while zooming or changing the axis scale, you must also provide aredraw function to update any necessary attributes (typicallyy and/orheight)

Example of custom draw callback:

vardata=[{codon:1,count:5//solid black bar, by default},{codon:2,count:8,bars:[{start:0,end:5,color:'blue'},{start:5,end:8,color:'red'},],drawTrackItem:function(g,scale){g.selectAll('rect').data((d)=>d.bars).enter().append('rect').attr('class','redraw').attr('y',(d)=>scale(d.start)).attr('height',(d)=>scale(d.end)-scale(d.start)).attr('width',1).attr('fill',(d)=>d.color).datum((d)=>{d.redraw=redraw;returnd;})functionredraw(el,newY){el.attr('y',(d)=>newY(d.start)).attr('height',(d)=>newY(d.end)-newY(d.start))}}}];

Example: Beginning from a whitespace separated list of tuples, use theparseVariantString andaggregate helper functions to create an appropriate array.

//create a whitespace-separated list with tuples [genename cdna pdot]varvariantString= 'TP53c.1176_1177insAp.D393fs*>2  \TP53c.1176A>Gp.S392S  \TP53c.1175C>Tp.S392L  \';varvariantObjects=widget.helpers.parseVariantString(variantString);varvariantCounts=widget.helpers.aggregate(variantObjects);varvariantTracks=[];//initialize empty arrayvartrack1={label:'Database #1',data:variantCounts};//add the object tovariantTracks.push(track1);