GIVE Tutorial 1.2: HTML code detail of tweaking a genome browser

This tutorial will show you how to directly edit HTML codes to implement a customized genome browser with existing GIVE code base and data source.

Table of Contents

How to follow this tutorial

There are several ways to follow this tutorial.

Building a full-fledged genome browser

Here we start by using GIVE code base together with the data sources. With them it will be extremely easy to create a genome browser by generating an HTML file under your web hosting folder simply as following (key lines in the HTML file are preceded by comments in <!-- --> to show their functionality):

<!doctype html>
<html>
  <head>
    <title>GIVE Demo</title>
    <!-- Polyfill Web Components for browsers without native support -->
    <script src="https://www.givengine.org/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
    <!-- Import GIVE component -->
    <link rel="import" href="https://www.givengine.org/components/chart-controller/chart-controller.html">
  </head>
  <body>
    <!-- Embed the browser in your web page -->
    <chart-controller ref="mm10" coordinate='["chr17:35504032-35512777"]'
      group-id-list='["genes", "singleCell", "customTracks"]'>
    </chart-controller>
  </body>
</html>

When you visit the HTML page, you will get a full-fledged genome browser. Click here to see a live demo of this file.

Embedding a full-fledged genome browser in existing pages

If you are trying to embed a genome browser into an existing pages, you need to put the Polyfill code and the importing code first but only once in the page, then use the embedding code in a container you want to put the browser in.

Note that the container (for example, a <div>) should have its CSS position property set as non-static (such as absolute, relative, or fixed) and its dimension well-defined (either by explicitly setting the values, or use flex-box model). This applies to all embedding elements in GIVE, including <chart-controller> and <chart-area>.

The following code is an example of embedding:

<!-- Polyfill Web Components for browsers without native support -->
<script src="https://www.givengine.org/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
<!-- Import GIVE component -->
<link rel="import" href="https://www.givengine.org/components/chart-controller/chart-controller.html">
<!-- Embed the browser in your web page -->
<chart-controller ref="mm10" coordinate='["chr17:35504032-35512777"]'
  group-id-list='["genes", "singleCell", "customTracks"]'>
</chart-controller>

Live embedding examples are available on CodePen or JSFiddle

Embedding the browser panel only in existing pages

By using the <chart-area> element instead of <chart-controller> element, it is possible to embed the browser panel (the panel with all the visualized data) only, instead of the whole thing.

(Note that both the importing part and embedding part have been changed.)

<!-- Polyfill Web Components for browsers without native support -->
<script src="https://www.givengine.org/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
<!-- Import GIVE component -->
<link rel="import" href="https://www.givengine.org/components/chart-area/chart-area.html">
<!-- Embed the browser in your web page -->
<chart-area ref="mm10" coordinate='["chr17:35504032-35512777"]'
  group-id-list='["genes", "singleCell", "customTracks"]'>
</chart-area>

Live embedding examples are available on CodePen or JSFiddle

Tweak elements in the embedded browser

GIVE provides several ways to tweak the embedded browser by specifying the corresponding HTML attributes. Most of the attributes will be applicable to both <chart-controller> and <chart-area> elements unless otherwise specified.

Change your reference genome

By specifying the ref attribute, you may change the reference genome used in the browser. Currently the following references are supported:

For example, the following embedding codes can be used to use hg19 as the reference genome (Polyfill and importing codes are omitted here): (CodePen demo, JSFiddle demo)

<chart-controller ref="hg19" coordinate='["chr6:31130000-31137000"]'
  group-id-list='["genes", "encode", "customTracks"]'>
</chart-controller>

Change the number of sub-views for interactions

GIVE supports multiple sub-views to better visualize interactions among different regions across the genome. by specifying the num-of-subs attribute, you may show multiple views in your embedded browser. (CodePen demo, JSFiddle demo)

<chart-controller ref="hg19" num-of-subs="2"
  group-id-list='["genes", "interaction", "customTracks"]'>
</chart-controller>

Change the coordinates showing in the browser

To change the coordinates that are showed in the browser, use coordinates attribute. coordinates should be specified in JSON array format (notice that double quotes "" should be used to quote the string).

<chart-controller ref="hg38" num-of-subs="2"
  coordinate='["chrX:73800000-73870000", "chrX:40000000-90000000"]'
  group-id-list='["genes", "interaction", "customTracks"]'>
</chart-controller>

Change the data shown in the browser

GIVE server provides several known data groups. By specifying group-id-list attribute, you can choose what data you would like to show in your browser. group-id-list should also be specified in JSON array format.

The data source on our server currently provides these track groups:

API documentation

The detailed attributes available for <chart-controller> and <chart-area> elements can be seen on the API documentation pages here:

Note that the attribute names in the API document is for JavaScript codes and are in camelCase format. To use those attributes, please convert the camelCase names into name with dashes. For example, to use numOfSubs mentioned in API as an HTML attribute, use num-of-subs instead. Please see Polymer property name to attribute name mapping for details.