jscomut is a javascript widget that creates interactive co-mutation plots in the web browser using d3.js. The widget allows mutation and demographic data to be loaded locally from a text file without uploading to the web, sorted interactively, and exported to a .svg file.
This guide contains information for:
new Comut(); (see below)When jscomut.js is executed, a constructor function named Comut is added to the global workspace. Call this function to create an instance of the widget.
var widget = new Comut();The widget provides functions so that user scripts can interact in certains ways.
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 calling init() with no arguments:
widget.init();By default, init creates a <div class='comut'></div> which contains the widget, and appends it to the body of the page. 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 a structure with desired options defined as fields. The structure 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: a selector that defines where the widget is added.
//default behavior is to create a div with class='comut' and append it to the body of the document.
target: '',
//grid: defines the geometry of the gene/alteration grid
//cellwidth: width of each cell in pixels
//cellheight: height of each cell in pixels
//maxgridwidth: the grid will grow depending on the number of samples; the total grid width is capped at this value...
// and the grid can be zoomed in/out if there are more samples than can fit in the max size.
//padding: padding between cells in pixels
grid: {
cellwidth: 20,
cellheight: 30,
maxgridwidth:500,
padding:1,
},
//bar: defines the geometry (width only) of the bar graph of alteration frequency, to the left of the grid
bar: {
width: 200,
//height: same as grid because the data is the same
},
//geneLegend: defines the geometry (width only) of the text legend of the gene names, left of the grid
geneLegend: {
width: 70,
},
//sampleLegend: defines the height of the sample legend above the grid. show:'no' will hide the legend.
sampleLegend:{
height: 100,
show: true, //if false (or falsey) a scale of zero will hide the labels
},
//colorLegend: defines the width of the legend of cell colors to the right of the grid.
colorLegend:{
width:200,
},
//innerLayout: pixels between the grid and the legend, bar graph, etc.
innerLayout:{
margins:5,
},
//legendOrder: defines which order the alterations show up in the legend
legendOrder: [
'missense',
'stop',
'fs',
'inframe',
'splice',
'amp',
'del',
'fusion',
'wt',
],
//mutTypeEncoding: defines which colors and text go with each type of alteration
mutTypeEncoding: {
"wt": { "code": 0, "color": "#D4D4D4", "text": "No alteration" },
"missense": { "code": 1, "color": "#0F8500", "text": "Missense" },
"stop": { "code": 2, "color": "#000000", "text": "Stop gain" },
"fs": { "code": 3, "color": "#5E2700", "text": "Frameshift" },
"inframe": { "code": 4, "color": "#C973FF", "text": "Inframe" },
"splice": { "code": 5, "color": "#F57564", "text": "Splice site" },
"amp": { "code": 6, "color": "#2129FF", "text": "Amplification" },
"del": { "code": 7, "color": "#FF0000", "text": "Deletion/loss" },
"fusion": { "code": 8, "color": "#00BFFF", "text": "Fusion" }
},
//dataInput: data can be loaded using a filepicker or pastebox
dataInput: {
filePicker: true,//if true, adds a button to select a file
pasteBox:true,//if true, adds a textinput for copy/paste
}
};var options = {
grid: {
cellwidth: 40,
maxgridwidth: 800
},
geneLegend: { width: 100 },
target: '#comut-widget-container'
};
widget.init(options);The randomize function shuffles the gene and sample order, and redraws the widget. This can be triggered by a button click, for example.
//trigger the randomize function by clicking a button
var button = $('#randomize-button');
button.on('click', widget.randomize);
//or it can be called directly
widget.randomize();The sort function organizes the data according to either the gene alteration frequency, the sample alterations, or both. A struct passed as an argument defines which axes to sort along.
//sort the genes by alteration frequency
var button = $('#sort-genes');
button.on('click', function(){
widget.sort({x:true});
});
//sort the samples by presence/absence of alterations, according to the current gene order
var button = $('#sort-samples');
button.on('click', function(){
widget.sort({y:true});
});
//sort the genes by alteration frequency, then sort the samples
var button = $('#sort-genes-and-samples');
button.on('click', function(){
widget.sort(); //equivalent to widget.sort({x:true, y:true})
});
So you have a webpage with the widget installed. Congratulations! How does this thing work?
First, and this is important: Your data stays completely in your control. It does not get uploaded to a server; it comes from your computer and all the processing is done right in the browser, without sending it over the internet. This means you can safely use the widget without losing confidentiality, until you're ready to distribute your findings.
Let's get started.
1) Click the Configure widget button to get started 2) Select a file with the mutations/alterations: 1) Click the button to choose a file from your computer, or copy-paste your data into the text box. 3) Do the same for additional demographic data, if desired 1) Click the button to choose a file from your computer, or copy-paste your data into the text box. 2) Select which types of data to display, and which colors should go with each value 4) Once you're satisfied, click the Create widget button.
Once your data is drawn into the plot, you can start exploring. The Drag-and-drop mode lets you re-order the grid data by clicking on the grid or the gene names and moving vertically to re-order the genes. Similarly, clicking on the grid or sample names and moving horizontally allows for re-ordering the samples. If there are a lot of samples and the grid is compressed, the Pan and zoom mode lets you zoom in and move around inside the grid. Choosing None lets you safely click around on the graphic without worrying about moving things inadvertently.
If the widget is configured to let you automatically sort the data by genes or by samples, there may be buttons for this as well.
Once you have ordered the data to your liking, you can use the Create downloadable svg file button to save your figure as a file on your computer. This process occurs entirely within the browser - even though the file is "downloaded" it is not being downloaded over the internet, it is simply being saved from the browser into a stand-alone file.
Data files should be tab-delimited text.
The first row of the file should contain the column names (gene, sample, type, alteration). Each subsequent row defines either: 1) A sample with a genetic alteration 2) Only a sample id (for samples with no detected alterations - only one row is needed)
If a sample has multiple alterations, each one belongs on a separate row
For example:
Sample Gene Type Alteration
Case1 BRAF missense c.1799T>A;p.V600E
Case2
Case3 RB1 fs c.2657delG
Case3 RB1 del All other non-altered data points will be automatically filled in.
The first row of the file should contain the column names. The only required column is "sample", because this links the demographic data to the genomic data. Other columns can contain any type of desired data. The configuration process allows you to select which columns to use in the plot. The columns should be tab-separated, and the text in each header will become the label for the corresponding row of demographic data (non-tab white space is allowed).
For example:
Sample Gender Tumor site
Case1 female thyroid
Case2 male bladder
Case3 female lungThis software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. The output of this software does not constitute medical advice and should not supplant appropriate medical judgment.