g3viz / g3lollipop.js

Lollipop-diagram to visualize genomic mutations

g3-lollipop.js: Interactively visualize genetic mutations using a lollipop-diagram

Date: 2019-04-06 (version 0.5.0)

Table of Contents

• 1. Introduction
• 2. Install
• 3. Usage
  • 3.1 Genetic mutation data
  • 3.2 Protein domain information
  • 3.3 Generate g3-lollipop chart
  • 3.4 Lollipop chart options
  • 3.5 Color palettes
  • 3.6 Export chart

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.

• Demos of g3-lollipop.js: [demo1] [demo2] [demo3]

• Demos for color palettes: [demo1] [demo2] [dome3]

• Introduction of g3viz R-package: [introduction] [chart themes]

↥ back to top

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>

↥ back to top

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)
};

↥ back to top

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
    },
};

↥ back to top

3.3 Generate g3-lollipop chart

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.

↥ back to top

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.

↥ back to top

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);
};

↥ back to top

g3lollipop.js's Issues

Where can I find the base pfam data?

Hi, I use the g3lollipop.js in my project. But I don't know how can I download the base pfam data for lollipop. Can you help me? Where can I download it.
Thank you very much.

Import loading is not supported

d3 @4.0 import scaleOrdinal error
[email protected] latest version Do not support the d3. Queue

How to set the default mutation?

Thank you for the great tool. I wonder whether there is an interface which can choose one mutation by default just as the effect of clicking on a certain mutation in the lollipop line? In other words, how to have an initial selection? Thank you.

如何更改主题？g3-lolllipop.js中未找到theme相关内容。