g3-lollipop.js: Interactively visualize genetic mutations using a lollipop-diagram
Date: 2019-04-06 (version 0.5.0)
Table of Contents
1. Introduction
g3-lollipop.js
is D3-based JavaScript library which generates interactive lollipop diagram for the given genetic mutation data. g3viz, the R-interface of this package, provides more functionality and usability.
-
Introduction of
g3viz
R-package: [introduction] [chart themes]
2. Installation
<!-- (optional) css -->
<link rel="stylesheet" href="https://s3-us-west-2.amazonaws.com/cdsjsd3/g3-viz/0.5.0/g3-lollipop.min.css">
<!-- D3 and G3-lollipop libraries -->
<script src="https://d3js.org/d3.v4.min.js"></script>
<script src="https://s3-us-west-2.amazonaws.com/cdsjsd3/g3-viz/0.5.0/g3-lollipop.min.js"></script>
3. Usage
3.1 Genetic mutation data
The input genetic mutation data should be an array of JSON objects. For example,
var mutation_data = [
{
"Hugo_Symbol": "PIK3CA",
"Variant_Classification": "Silent",
"HGVSp_Short": "p.F70F",
"Mutation_Class": "Inframe",
"AA_Position": 70
}, {
"Hugo_Symbol": "PIK3CA",
"Variant_Classification": "Missense_Mutation",
"HGVSp_Short": "p.E81K",
"Mutation_Class": "Missense",
"AA_Position": 81
}, {
"Hugo_Symbol": "PIK3CA",
"Variant_Classification": "Missense_Mutation",
"HGVSp_Short": "p.E81K",
"Mutation_Class": "Missense",
"AA_Position": 81
}, {
"Hugo_Symbol": "PIK3CA",
"Variant_Classification": "Missense_Mutation",
"HGVSp_Short": "p.F83S",
"Mutation_Class": "Missense",
"AA_Position": 83
}, {
"Hugo_Symbol": "PIK3CA",
"Variant_Classification": "Missense_Mutation",
"HGVSp_Short": "p.R88Q",
"Mutation_Class": "Missense",
"AA_Position": 88
}
];
In addition, users need to specify data columns for the x, y, and factor values. The default settings are
var mutation_data_default_settings = {
x: "AA_Position", // mutation position
y: "Protein_Change", // amino-acid changes
factor: "Mutation_Class", // classify mutations by certain factor (optional)
};
3.2 Protein domain information
Pfam domains are commonly used for protein structural annotation in genetic mutation lollipop diagrams.
For exmaple,
var pfam_data = {
"hgnc_symbol":"TP53",
"protein_name":"tumor protein p53",
"uniprot_id":"P04637",
"length":393,
"pfam":[
{
"pfam_ac":"PF08563",
"pfam_start":6,
"pfam_end":29,
"pfam_id":"P53_TAD"
},
{
"pfam_ac":"PF00870",
"pfam_start":95,
"pfam_end":288,
"pfam_id":"P53"
},
{
"pfam_ac":"PF07710",
"pfam_start":318,
"pfam_end":358,
"pfam_id":"P53_tetramer"
}
]
}
Similarly, users need to specify the format settings of Pfam data. The default settings are
var pfam_data_default_settings = {
domainType: "pfam", // key to the domain annotation entries
length: "length", // protein length
details: {
start: "pfam_start", // protein domain start position
end: "pfam_end", // protein domain end position
name: "pfam_id", // protein domain name
},
};
g3-lollipop
chart
3.3 Generate To generate g3-lollipop
chart, we first need to create a lollipop object, set chart options, and draw the chart.
For example,
// create in "g3lollipop" div
var lollipop = g3.Lollipop("g3lollipop");
// add mutation data
lollipop.data.snvData = mutation_data;
// mutation data format settings
lollipop.format.snvData = mutation_data_default_settings;
// Pfam domain data
lollipop.data.domainData = pfam_data;
// Pfam data format settings
lollipop.format.domainData = pfam_data_default_settings;
// set up more chart options ...
// draw lollipop
lollipop.draw();
3.4 Lollipop chart options
g3-lollipop
has more than 60 chart options. Users can use getter/setter to set up or query chart options. For example,
lollipop.options.chartMargin = {
"left": 40, "right": 40, "top": 30, "bottom": 25
};
lollipop.options.titleFont = "normal 20px Sans";
lollipop.options.titleColor = "steelblue";
lollipop.options.titleAlignment = "middle";
lollipop.options.titleDy = "0.3em";
or you can use setOptions
to set a list of options,
var plot_options = {
"chartMargin": {
"left": 40, "right": 40, "top": 30, "bottom": 25
},
"titleFont": "normal 20px Sans",
"titleColor": "steelblue",
"titleAlignment": "middle",
"titleDy": "0.3em"
};
// add chart options
lollipop.setOptions(plot_options);
The full list of g3-lollipop
chart options
- Chart options
Option | Description |
---|---|
chartTarget | chart target DIV id. |
chartID | (getter only) unique id of chart SVG element |
chartWidth | chart width in px. Default 800 . |
chartHeight | (getter only) chart height in px. |
chartType | pop type, pie or circle . Default pie . |
chartMargin | specify chart margin in JSON format. Default {"left": 40, "right": 20, "top": 15, "bottom": 25} . |
chartBackground | chart background. Default transparent . |
transitionTime | chart animation transition time in millisecond. Default 600 . |
- Lollipop options
Option | Description |
---|---|
lollipopTrackID | (getter only) unique id of lollipop track. |
lollipopTrackHeight | height of lollipop track in px. Default 420 . |
lollipopTrackBackground | background of lollipop track. Default rgb(244,244,244) . |
lollipopPopMinSize | lollipop pop minimal size in px. Default 2 . |
lollipopPopMaxSize | lollipop pop maximal size in px. Default 12 . |
lollipopPopInfoLimit | threshold of lollipop pop size to show counts in middle of pop. Default 8 . |
lollipopPopInfoColor | text color of lollipop pop counts. Default #EEE . |
lollipopPopInfoDy | y-axis direction text adjustment of lollipop pop counts. Default -0.35em . |
lollipopLineColor | lollipop line color. Default rgb(42,42,42) . |
lollipopLineWidth | lollipop line width. Default 0.5 . |
lollipopCircleColor | lollipop circle border color. Default wheat . |
lollipopCircleWidth | lollipop circle border width. Default 0.5 . |
lollipopLabelRatio | lollipop click-out label font size to circle size ratio. Default 1.4 . |
lollipopLabelMinFontSize | lollipop click-out label minimal font size. Default 10 . |
lollipopColorScheme | color scheme to fill lollipop pops. Default accent . Check color palettes for details. |
highlightTextAngle | the rotation angle of on-click highlight text in degree. Default 90 . |
- Protein doamin annotation track
Option | Description |
---|---|
annoID | (getter only) unique id of protein domain annotation track. |
annoHeight | height of protein structure annotation track. Default 30 . |
annoMargin | margin of protein structure annotation track in JSON format. Default {"top": 4, "bottom": 0} . |
annoBackground | background of protein structure annotation track. Default transparent . |
annoBarFill | background of protein bar in protein structure annotation track. Default #E5E3E1 . |
annoBarMargin | margin of protein bar in protein structure annotation track. Default {"top": 2, "bottom": 2} . |
domainColorScheme | color scheme of protein domains. Default category10 . Check color palettes for details. |
domainMargin | margin of protein domains. Default {"top": 0, "bottom": 0} . |
domainTextFont | domain label text font in shorthand format. Default normal 11px Arial . |
domainTextColor | domain label text color. Default #F2F2F2 . |
- Y-axis label
Option | Description |
---|---|
yAxisLabel | Y-axis label text. Default # of mutations . |
yAxisLineColor | color of y-axis in-chart lines (ticks). Default #c4c8ca . |
yAxisLineStyle | style of y-axis in-chart lines (ticks), dash or line . Default dash . |
yAxisLineWidth | width of y-axis in-chart lines (ticks). Default 1 . |
yMaxRangeRatio | ratio of y-axis range to data value range. Default 1.1 . |
axisLabelFont | css font style shorthand (font-style font-variant font-weight font-size/line-height font-family). Default normal 12px Arial . |
axisLabelColor | axis label text color. Default #4f4f4f . |
axisLabelAlignment | axis label text alignment (start/end/middle). Default middle |
axisLabelDy | text adjustment of axis label text. Default -2em . |
- Chart title
Option | Description |
---|---|
titleText | title of chart. Default "". |
titleFont | font of chart title. Default normal 16px Arial . |
titleColor | color of chart title. Default #424242 . |
titleAlignment | text alignment of chart title (start/middle/end). Default middle . |
titleDy | text adjustment of chart title. Default 0.35em . |
- Chart legend
Option | Description |
---|---|
legend | if show legend. Default true . |
legendMargin | legend margin in JSON format. Default {"left": 10, "right": 0, "top": 5, "bottom": 5} . |
legendInteractive | legend interactive mode. Default true . |
legendTitle | legend title. |
legendHeight | (getter only) height of legend in px. |
- Brush selection tool
Option | Description |
---|---|
brush | if show brush. Default true . |
brushBackground | background color of selection brush. Default #666 . |
brushOpacity | background opacity of selection brush. Default 0.2 . |
brushBorderColor | border color of selection brush. Default #969696 . |
brushBorderWidth | border width of selection brush. Default 1 . |
brushHandler | color of left and right handlers of selection brush. Default #333 . |
- Tooltip and zoom
Option | Description |
---|---|
tooltip | if show tooltip. Default true . |
zoom | if enable zoom feature. Default true . |
3.5 Color palettes
g3-lollipop
package includes 37 built-in color palettes for categorical data. These color palettes can be used for lollipops (demo1) or protein domains (demo2). The full list of these palettes are shown in this dome.
3.6 Export chart
g3-lollipop
package includes built-in functions to export the resultant chart in PNG or vector-based SVG file.
For example, HTML code
<div>
<span class="btn-group">
<button id="save-as-png">save as PNG</button>
<button id="save-as-svg">save as SVG</button>
</span>
</div>
<div id="g3-lollipop"></div>
JavaScript code
// get chart div id
var chartID = lollipop.options.chartID;
// set default filename
var output_chart_filename = "g3-lollipop";
// button actions: download chart
document.getElementById("save-as-png").onclick = function (e) {
g3.output().toPNG(output_chart_filename, chartID);
};
document.getElementById("save-as-svg").onclick = function (e) {
g3.output().toSVG(output_chart_filename, chartID);
};