A customizable web tool for visualizing genome-wide annotation
See also Flash GViewer.
Simon Twigger, Medical College of Wisconsin © 2005 Last Modified: February 16, 2006
The Rat Genome Database has an SVG-based genome viewer that shows the location of genes and QTLs against a backdrop of the rat cytogenetic map. For our proteomics projects we were interested in viewing the genomic locations of the proteins identified in a proteomics experiment and a GViewer-like display is well suited to this. To make a more stand-alone solution I rewrote much of the functionality into a Flash application that is more adaptable to other organisms and other types of data. It requires Macromedia Flash Plugin Version 7, you can download the plugin here.
Here are some of the Flash GViewer’s current features:
Here’s an example of the GViewer showing the rat genome with some of the rat genes and QTLs associated with blood pressure:
(Dont see anything? You need Flash Plugin version 7 for this to work. How can you gracefully handle browsers that dont have the plugin or an earlier version - I have had good success with Colin Moock’s FlashPlayerInspector. His page has more info on how this works (and when it doesnt), plus you can download the appropriate code (javascript) to test for the plugin and provide appropriate alternative text/content as required).
Flash/Javascript interaction MouseOver Demos
There is a real live demo at flashGViewer doc page on the GMOD blog site.
Flash GViewer is available at Sourceforge and all source code is available via the CVS repository.
Basic installation is very simple, copy these files/directories to a directory on your webserver:
Load up sample.html in a browser and you should see a working version of the GViewer. The sample.html is a very basic HTML page that contains the tags that display the same version of GViewer as you see above. The data directory contains the sample rat annotation file and the rat, human and mouse baseMaps. You can change the baseMapURL to point to one of the other organisms and see what their maps look like. Not a great fan of the background color - change the bgcolor parameter to something more appropriate, see the Input Parameters section below. If everything is working as expected, you can modify the HTML page or cut out the object tag and insert it on one of your own pages. You can create your own static annotation XML files or create a CGI/JSP script that retrieves the data from a database. Details of the various file formats are given below.
These values are passed into the flash application (refered to as a SWF
or “swiff” file, as it has a .swf suffix) via the <object> tag used to
place the flash SWF on an HTML page. An example tag that you might place
on an HTML page is given below. In this hypothetical example we are
retrieving the mouse chromosome and banding pattern (the baseMap) from a
static XML file on a server and the annotations are retrieved from a CGI
script which returns the annotation XML for QTLs associated with the
phenotype of blood pressure. Some of the longer lines have been broken
to keep the page width down, the sample.html page provided with the
download has a correctly formatted set of tags for you to copy.
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=7,0,0,0" width="300" height="250" id="GViewer2" align="middle">
<param name="allowScriptAccess" value="sameDomain" />
<param name="movie" value="GViewer2.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#FFFFFF" />
<param FlashVars="&baseMapURL=http://server.mcw.edu/~simont/
mouse_ideo.xml&annotationURL=http://server.mcw.edu/cgi-bin/getDiseaseQTLAnnotation.cgi
?disease=blood_pressure&titleBarText=Rat Genome with sample data
&browserURL=http://genome.ucsc.edu/cgi-bin/hgTracks?org=Rat%26position=Chr&">
<embed src="GViewer2.swf" quality="high" bgcolor="#FFFFFF" width="300"
height="250" name="GViewer2" align="middle" allowScriptAccess="sameDomain" type="application/x-shockwave-flash"
FlashVars="&baseMapURL=http://server.mcw.edu/~simont/mouse_ideo.xml&
annotationURL=http://server.mcw.edu/cgi-bin/getDiseaseQTLAnnotation.cgi?disease=blood_pressure&titleBarText=Rat Genome with sample data
&browserURL=http://genome.ucsc.edu/cgi-bin/hgTracks?org=Rat%26position=Chr&" pluginspage="http://www.macromedia.com/go/getflashplayer" />
</object>
The critical sections are FlashVars and the name of the Flash
application (e.g. GViewer2.swf). The other parts are standard and
you are unlikely to have to change any of them, though you can change
the background color of the GViewer using the bgcolor parameter. The
movie parameter is the path to the GViewer2.swf file on your
server/filesystem. The FlashVars parameter contains the information
that is passed into the GViewer to enable it to find the base map and
appropriate annotations. Due to differences between the windows and Mac
platforms, you have to put these parameters in two places, in the
<param> tags of the <object> tag, and also inside the <embed> tag.
The windows flash plugin seems to use the object tags, the mac plugin
uses the embed tags. If you modify these values and don’t see a change,
check to make sure you changed it in both locations as this is usually
the reason for nothing happening!
The FlashVars parameters that you can set are as follows:
| Parameter | description |
|---|---|
| baseMapURL | The URL of a file or server script that will return the XML
description of the base chromosomal map and banding patterns.
longestChromosomeLength The length of the longest chromosome (in base pairs). This value is only needed if the longest chromosome isnt Chromosome 1 (i.e. the first chromosome in the baseMapFile) as by default the application assumes this is the longest chromosome and scales every other chromosome accordingly. If another chromosome is actually longer (eg. in C. elegans) then the scaling will be off unless this value is set. |
| annotationURL | A URL of a file or server script that will provide the annotation XML |
| annotationXML | An embbeded annotation XML string that defines the annotation directly in the HTML page, rather than the SWF file having to call a remote script or file. If the annotationXML parameter is defined it will take precedence over the annotation URL - ie it will use the XML embedded in the page rather than the remote source. |
| dimmedChromosomeAlpha | The alpha value (transparency) of chromosomes with no annotations. Defaults to 100 (no transparency), set to value between 0 (invisible) and 100 to dim the chromosomes that have no annotation. Useful to highlight the chromosomes with annotation information, values between 20-40 work well for this effect. |
| bandDisplayColor | The color of features drawn as bands, eg QTL. Should be set to a hexadecimal color using the Flash nomenclature, eg. 0xFF0000 is red, as opposed to traditional HTML nomenclature of #FF0000 |
| wedgeDisplayColor | The color of features drawn as wedges, eg Genes. Should be set to a hexadecimal color using the Flash nomenclature, eg. 0xFF0000 is red, as opposed to traditional HTML nomenclature of #FF0000 |
| titleBarText | Text to be shown in the top left right corner of the GViewer - can be used to put a title on the display |
| browserURL | Optional URL to create link out to genome browser for regions
defined by region selection sliders in chromosome zoom view. The movie
appends the chromosome number and start/stop coordinates to the end of
this URL so it should be written with that fact in mind. The example
above shows a valid URL for UCSC Rat genome. If the region sliders are
used to select 1000 to 5000bp on chromosome 1, the final URL will look
like:
http://genome.ucsc.edu/cgi-bin/hgTracks?org=Rat%26position=Chr1:1000..5000 The part in purple comes from the browserURL value, the part in bold is added to the end of the URL to complete the browser URL. %26 is used to escape the ampersand present in the UCSC URL otherwise it interferes with the apersands delimiting the various FlashVars parameters. |
The baseMap file contains the data on the chromosome(s), their length, name, banding pattern and colors. A perl script is provided in the scripts directory that takes the cytoBandIdeo files produced by UCSC and converts them to the GViewer baseMap XML format. If this data is available you can find the appropriate UCSC file by going to http://hgdownload.cse.ucsc.edu/downloads.html, find your organism, find the annotation database and then see if there is a cytoBandIdeo.txt.gz file.
The Flash GViewer lays out the chromosomes by sorting them according to the index attribute of the chromosome and currently divides them over two rows with half the chromosomes on the top and half on the bottom. If there were 10 chromosomes, Chromosomes 1-5 would be on the top row with Chr 1 on the left, Chr 5on the right, Chrs 6-10 would be on the bottom from left to right. Chromosomes are sized automatically based on the length of the first Chromosome, the assumption being that this is the longest. The scaling for all the other chromosomes and the mapping of genome coordinates (eg. basepairs) to flash coordinates (pixels) is all based off this value. The first chromosome is set to be 45% of the height of the Flash movie, you can set the width and height of the movie using the tags on the HTML page and the GViewer will resize the chromosomes accordingly. It doesn’t scale the tooltip labels at this point so going really small makes the text illegible, going really large makes the text really large. It was developed with the movie having a size of 550px wide and 400px high so the text labels look good at this size, the further you stray from this the smaller/larger the text becomes. Try it and see how it looks, you can always zoom in using the Flash plugin’s zoom feature.
The baseMap XML format looks like this:
<?xml version="1.0" standalone="yes"?>
<genome>
<chromosome index="1" number="1" length="268121971">
<band index="1" name="p13">
<start>0</start>
<end>10150087</end>
<stain>gneg</stain>
<color>0xFF0000</color>
</band>
<band index="2" name="p12">
<start>10150087</start>
<end>24291782</end>
<stain>gvar</stain>
</band>
<band index="3" name="p11">
<start>24291782</start>
<end>38547522</end>
<stain>gneg</stain>
</band>
</chromosome>
<chromosome index="2" number="10" length="110733352">
<band index="1" name="q11">
<start>0</start>
<end>6255594</end>
<stain>gpos</stain>
</band>
<band index="2" name="q12">
<start>6255594</start>
<end>26236148</end>
<stain>gneg</stain>
</band>
<band index="3" name="q21">
<start>26236148</start>
<end>34825919</end>
<stain>gpos</stain>
</band>
</chromosome>
</genome>
The XML elements in this file are as follows, I’ve used @xxxx to indicate attributes of elements
| XML Element | description |
|---|---|
| chromosome | Each chromosome’s data is contained within a chromsome element |
| @index | the chromosome index - an integer value used solely to sort the chromsomes to get correct order on the image (otherwise Flash sorts them 1, 10, 11, 2, 3, 4, X, Y,etc). |
| @number | the actual chromosome number, eg.1, X, Y, used to label the chromosome on the Flash GViewer |
| @length | the length of the chromosome in appropriate units (probably basepairs). I dont think there would be a problem using other units (cR, cM) as long as you were consistent throughout the baseMap file and annotation XML. |
| band | each band’s data on the chromosome is contained within a band element |
| @index | index number for the band, used to sort the bands in an appropriate order |
| @name | name of band, eg q11, p12. Currently not used but could be used to display the band info when the mouse was placed over it |
| start | band start location in appropriate Units (probably basepairs) |
| end | band end location in appropriate Units (probably basepairs) |
| color | Flash hex representation of the band color (begins with 0x rather than a #), eg. 0xFF0000 would give a red band. Can be used to create a customized color scheme for the baseMap. |
| stain | Giemsa stain abbreviation, obtained from the UCSC cytogenetic banding files. This is used to color the bands appropriately. This value is overruled by the value in a color element (see below). Currently recognized stain abbreviations and the corresponding colors are shown below. |
Stain abbreviations and colors
| Stain Abbreviation | Hex Color | Swatch |
|---|---|---|
| gpos & gpos100 | #000000 | |
| gpos75 | #444444 | |
| gpos66 | #666666 | |
| gpos50 | #888888 | |
| gpos33 | #AAAAAA | |
| gpos25 | #CCCCCC | |
| gneg | #FFFFFF | |
| gvar | #CCCCCC | |
| [default] | #CCCCCC |
The following base maps are provided in the standard distribution.
Basic Genome Maps
| Base Map File | Map Description | External Links |
|---|---|---|
| rat_ideo.xml | Rat genome with cytogenetic bands, created from UCSC cytoBandIdeo file | Yes - <a href=”http://genome.ucsc.edu/” class=”external text” |
| rel=”nofollow”>UCSC Genome Browser</a> | ||
| rgd_rat_ideo.xml | Rat genome with cytogenetic bands, created from UCSC cytoBandIdeo file | Yes - RGD |
| Genome Browser</a> | ||
| mouse_ideo.xml | Mouse genome with cytogenetic bands, created from UCSC cytoBandIdeo file | Yes - <a href=”http://genome.ucsc.edu/” class=”external text” |
| rel=”nofollow”>UCSC Genome Browser</a> | ||
| human_ideo.xml | Human genome with cytogenetic bands, created from UCSC cytoBandIdeo file | Yes - <a href=”http://genome.ucsc.edu/” class=”external text” |
| rel=”nofollow”>UCSC Genome Browser</a> | ||
| celegans_ideo.xml | C. elegans genome, no bands. | No |
Comparative Maps (Synteny data from RGD VCMap SEQBASD v1.0)
| Base Map File | Map Description | External Links |
|---|---|---|
| human-rat_synteny.xml | Human genome with bands corresponding to syntenic regions in Rat | No |
| human-mouse_synteny.xml | Human genome with bands corresponding to syntenic regions in Mouse | No |
| rat-human_synteny.xml | Rat genome with bands corresponding to syntenic regions in Human | No |
| rat-mouse_synteny.xml | Rat genome with bands corresponding to syntenic regions in Mouse | No |
| mouse-rat_synteny.xml | Mouse genome with bands corresponding to syntenic regions in Rat | No |
| mouse-human_synteny.xml | Mouse genome with bands corresponding to syntenic regions in Human | No |
Flash GViewer can read annotation data in the XML format shown below from a static text file or dynamically from a server-side script. The annotation consists of multiple feature elements which provide the basic information for each feature to be displayed. The server-side script would probably query a database for this information and then return the XML data as its output.
The annotation XML format looks like this:
<?xml version="1.0" standalone="yes"?>
<genome>
<feature>
<chromosome>7</chromosome>
<start>10150087</start>
<end>10150087</end>
<type>gene</type>
<label>Abc1</label>
<color>0xFF0000</color>
<link>http://rgd.mcw.edu/showReport.cgi?id=45678</link>
</feature>
<feature>
<chromosome>6</chromosome>
<start>20150087</start>
<end>40150087</end>
<type>qtl</type>
<label>Bp123</label>
<color>0x33AA33</color>
<link>http://rgd.mcw.edu/showReport.cgi?id=12345</link>
</feature>
</genome>
| XML Element | description |
|---|---|
| chromosome | The chromosome number that this feature belongs to |
| start | start location in appropriate Units (probably basepairs) |
| end | end location in appropriate Units (probably basepairs) |
| type | feature type, used to determin what glyph to use when rendering the feature - currently two types gene and qtl. Gene is displayed as a triangle with the point towards the chromosome at the location of the feature. QTL is displayed as a bar stretching from the start location to the end location. |
| label | The tooltip text that is displayed when the mouse is placed over the
feature, or when the feature is displayed on the larger scale single
chromosome view
color Flash hex representation of the band color (begins with 0x rather than a #), eg. 0xFF0000 would give a red feature. Can be used to create a customized color scheme for each individual feature. |
| link | URL to link out to if the user clicks on the feature, eg. to go to a gene report when they click on a gene |
To allow users to upload their own features for display on GViewer, a simple web form is available that takes annotation from a text field or uploaded file and displays it against the base map selected by the user. This allows users to view their own data against a variety of different base maps (eg. Mouse-Human syntenic map, Mouse-Rat syntenic map). Availble options include:
Upload annotations in a simple text format, either by pasting into the form or uploading a file Select from one of the available base maps (or create your own and edit the list accordingly) Cusomize the movie’s color scheme. The background color, bar color and wedge colors can be modified using a pop-up color selector. Select different movie sizes. Three size options are provided - normal, large and extra large. Enlarging the movie can be useful for taking better screenshots for publication, etc. Web Interface Installation
1. The HTML page for the web interface is part of the main file distribution and is /GViewer/index.html. This contains an HTML form that points to the perl cgi script (see 2, below) and is initially configured to point to /cgi-bin/gviewer_annotation.cgi. The action attribute of the form tag should be modified if the perl script is installed in a different location.
<form name=”gviewer_form” method=”post” action=”/cgi-bin/gviewer_annotation.cgi” enctype=”multipart/form-data”>
The form contains a list of the available base maps provided with GViewer. These should be edited to remove any that are inappropriate and to add in any custom base maps that you may have created. The value attribute of the option tag should be the basemap’s file name and these basemaps are assumed to be in the GViewer/data directory.
<select name="baseMap">
<option value="rat_ideo.xml" selected>Rat Cytogenetic Map</option>
<option value="mouse_ideo.xml">Mouse Cytogenetic Map</option>
<option value="human_ideo.xml">Human Cytogenetic Map</option>
...
</select>
The web page can be cusomized to fit in with an existing web site by modifying the .css stylesheet, changing the header graphic and the gradient.gif file used to create the background for the form header rows. The form is the only part of the page that is required so the header and footer could be deleted and the form could be copied into an existing web page with no ill effects.
2. Move the contents of the cgi-bin/ directory to your server’s cgi-bin directory. The current script is a single perl script that relies only on the CGI.pm module. Check that the path to the perl executable is correct at the top of the script and that CGI.pm is available. The perl script has a couple of variables that may need to be modified to suit the location of the GViewer files on your server.
# absolute URL pointing to GViewer directory holding movie and data
my $pathToGViewerWebDir = "/Gviewer";
# absolute URL pointing to GViewer style sheet, probably the same as the webdir, above.
my $pathToStyleSheet = "/Gviewer";
3. Text Annotation file format. The format of the annotation data that can be uploaded is very simple and is designed to be easy to create from typical spreadsheet applications or by manual typing into a text document. It consists of the same data found in the XML file with a single tab-delimited row for each feature. The data is in the following order:
Chromosome [tab] start_position [tab] end_position [tab] type [tab] label_text [tab] link (optional)
The data used in the example annotation XML file above would look like this and could be pasted into the form or uploaded as a text file:
7 10150087 10150087 gene Abc1 http://rgd.mcw.edu/showReport.cgi?id=45678
6 20150087 40150087 qtl Bp123 http://rgd.mcw.edu/showReport.cgi?id=12345
It is possible to use javascript to control basic functions in the flash movie. This allows a higher degree of interactivity between the web content and the flash movie itself by allowing javascript to trigger actions in the movie without the User having to directly interact with the movie itself. This feature uses the Flash/Javascript Integration Kit and has been tested on Mac (Safari, Firefox) and windows (IE6) using Flash Player 7 and 8. A number of additional flash .swf and actionscript files and some javascript files are required, these are included in the GViewer distribution so no further installation is necessary. Currently the following functions are available for control via Javascript.
| Flash function | Function description |
|---|---|
| setHighlight(featureName) | Turns on the highlight and label for the feature with the label ‘featureName’ |
| unsetHighlight(featureName) | Turns off the highlight and label for the feature with the label ‘featureName’ |
| getAnnotationData(format) | Can be used to get the raw annotation data from the Flash Movie in various formats (text and html). Data is passed back to a javascript function displayAnnotationData(String) as a string object containing tab-delimited (text) or table (html). The function can then do something with the data such as display it in a new window, etc. |
To call these functions using Javascript, a few changes are required in the web page containing the flash movie:
Import the JavaScriptFlashGateway.js javascript file.
<script type="text/javascript" src="./GViewer/javascript/JavaScriptFlashGateway.js"></script>
Configure the flash proxy that acts as a bridge between the javascript and GViewer flash movie. A unique ID (uid) is created that configures the connection between javascript and a particular instance of the flash movie. If
you have more than one GViewer on the page, you should use different uids to communicate with them individually.
There is then a simple javascript function that takes the name of a feature and an appropriate action parameter and then calls the setHiglight or unsetHighlight methods in the flash movie.
<script type="text/javascript">
var uid = 1234567890; // needs to be unique on page, gets passed to Flash movie too
var flashProxy = new FlashProxy(uid,"./GViewer/javascript/JavaScriptFlashGateway.swf");
function doHighlight(action, featureName) {
if (action == 'set') {
flashProxy.call('setHighlight', featureName);
}
else {
flashProxy.call('unsetHighlight', featureName);
}
}
// Function to trigger the Flash method to get the annotation data in html format
function getAnnotationData() {
flashProxy.call('getAnnotationData', 'html');
}
// Function called by flash to display the annotation data
function displayAnnotationData(data) {
var generator=window.open('','Annotation Data','height=400,width=600');
generator.document.write('<html><head><title>Annotation Data</title>');
generator.document.write('<link rel="stylesheet" href="style.css">');
generator.document.write('</head><body>');
generator.document.write('===Known Issues with the Flash/Javascript connection===
Using mouseOver or mouseOut can cause the highlight to accidentally
stay on if another mouseOver event happens before the mouseOut event
(can happen if two mouseOver links are very close together on the page
and the user moves the mouse quickly from one to the other).
Current Solution - Moving the mouse on and off the link a few times should make the highlight go away.