Skip to content

G3viz/g3lollipop.js

Repository files navigation

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.



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


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.


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