Flash GViewer

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.

Current Features (v0.5)

Here are some of the Flash GViewer's current features:

Uses a base map containing the chromosomes and banding pattern of the desired organism. Perl scripts are available to take the UCSC cytogenetic map files and convert them to the appropriate XML format. This can also be used to portray any other custom backdrop for a chromosome - colored segments corresponding to syntenic regions in other organisms, colored according to feature density, etc.

Bands can link out to a URL defined in the base map (to allow users to click to view a region in a genome browser, for example).

Annotations can come from a static XML file or can be dynamically generated by a server-side script

New in v0.5. Annotations can be colored independently, allowing further information to be conveyed (eg. red/green/yellow for expression levels, peptide coverage or Xcorr for proteomic data.

Features appear at the appropriate position on the chromosome and then dynamically move out to form a non-overlapping display.

Placing the mouse over individual features brings up a tooltip displaying the feature's name, it also visually highlights the region of the chromosome that the feature is aligned with

Clicking on a feature toggles the highlight display so it will stay on when you move the mouse away. This can be used to turn on the region highlights for multiple features to better visualize their overlapping regions. Click again to turn each feature's highlight off.

Clicking on a feature can open up a new browser window with a cusomizable URL, eg a gene report page.

Clicking on a chromosome will expand that chromosome and enlarge and label the features making them easier to view. Click the chromosome again to return the whole genome view.

Turn on/off labels for zoom view and genome view (press i button in bottom left corner). Click redraw to refresh the view to show/hide labels.

Javascript can be used to dynamically highlight displayed annotations by using triggering javascript functions in the web page containing the flash movie. Javascript can be used to query annotation data from the flash movie and handle the returned data.

Customizable web interface and perl CGI script provided to allow users to upload annotations and display them on the GViewer against the base map of their choice.

Region selection sliders in Zoom View allow the selection of a genomic region so you can then click to open up a genome browser window for the specified region.

Changes in v0.5

Added the ability to color annotation features independently via addition of color tag to annotation XML format. Annotations without separate color information will rever to the default color for that particular feature type.

Changes in v0.4

Improved Javascript functionality - added feedback from Flash to Javascript to allow Javascript to query Flash for the annotation data and have Flash pass this data back to a Javascript function for display or other use.

Added ability to add a title to the GViewer movie.

Reset zoom view to provide 2x zoom of chromosome and annotation.

Added Region selection sliders in Zoom View to allow the selection of a genomic region. New configuration parameter to set external URL for browser link.

Changes in v0.3

Added basic javascript to flash connectivity to allow javascript in a web page to control the feature highlighting in the flash movie

Changes in v0.2

Bands can link out to a URL defined in the base map (to allow users to click to view a region in a genome browser, for example).

Changed click/shift click of features and bands. Clicking on a feature turns highlight on/off, shift-clicking opens external link. Clicking on a band changes to zoomed view or back to genome view, shift clicking opens external link. This was altered because it was too easy to accidentally click on a feature and open a new browser window by accident.

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).

Installation

Basic installation is very simple, copy these files/directories to a directory on your webserver:

GViewer directory and contents

sample.html

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.

Input Parameters

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.

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:

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

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 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 Base Maps

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

The Annotation Data

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.

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

Web Interface & CGI script

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.

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.

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.

<perl>

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";
</perl>

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:

Javascript - Flash Connectivity

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.

Known Issues

If you load many features (hundreds), Flash is probably going to start running slowly - I havent done any testing on this as it is rather dependent on the hardware the user is using to view the webpage but each new feature creates a new MovieClip in Flash and ultimately this can start to bog it down.

Similarly, if your baseMap has many bands, the same thing may start to happen, again I have no quantitative data on this but if you have hundreds of bands (or syntenic segments or whatever the 'bands' represent in your situation) be aware that things might start to slow down. This is not probably not going to be a great solution to viewing an entire set of genome annotations (25,000 genes, 600,000 ESTs, etc), they will need to be filtered somehow. If you try a really large dataset, let me know how it goes!

If you have lots of features that overlap on the chromsome, when you view an individual chromosome the current layout manager displays them all so they dont overlap - the problem being this may spread outside of the viewable area. You can now turn the labels off in the zoomed view which will alleviate this problem to some extent. The features are compressed on the genome view so they will overlap but all will be visible

Debugging - the SWF has limited debugging messages at this point, so if your XML files are incorrectly formatted, etc. it wont tell you what's going wrong, you just wont get past the 'Loading' stage, not too friendly I agree. It will tell you if no annotation file was provided or if it has no baseFile.