Gobe: interactive comparative genomics viewer
=============================================
.. image:: http://lh5.ggpht.com/_uU_kLC5AdTc/TCJP77hL_HI/AAAAAAAAA2E/LwVimCjeoUs/s800/gobe.png
:align: right
interactive, light-weight, customizable, web-based comparative genomics viewer with simple text input format.
:Authors: Brent Pedersen (brentp), Haibao Tang (tanghaibao)
:Email: bpederse@gmail.com
:License: MIT
.. contents ::
Summary
=======
You define a set of features, a set of tracks, and a css for styling features
and you get a flash movie that allows you to interact with genomic data. The
simple format makes it trivial to implement further interactivity including
panning and zooming.
Interaction is customizable via javascript callbacks, css, and the input data.
No server-side rendering is required. `haxe`_ programming language is used for
development, but it is not required to use the library.
Annotations
===========
The annotations to be rendered by the flash movie are in a simple text format.
The best way to understand them is to briefly skim the summaries below and
have a look at the examples in the
`data/ `_ directory.
Annotation
----------
An annotation is anything to be drawn. These will be things like CDSs,
genes, mRNAs, UTRs or any feature you define and style.
There are 2 special types: `HSP`_'s and `Track`_
Briefly, an `HSP`_ allows one to draw relationships between features. The
relationship is inferred between consecutive annotations with type 'HSP'
in the file.
`Track`_ s allow one to explicitly set the limits for each track (otherwise
inferred by the extent of the features in that track).
The annotation file is a text file with 7 **comma-delimited** columns per row:
1) `id`: a unique identifier for this annotation. this is anything you
want, can be your own database id or gene name or just an enumeration.
2) `track_id`: the id of the track on which to draw this feature.
See `Track`_.
3) `start`: the start of the feature.
4) `end`: the end of the feature.
5) `type`: a feature type (CDS, gene etc). If not specified, 'default' is used.
6) `strand`: either '+' or '-', the strand of the feature. `HSP`_'s with a
+/- match should both be assigned - as the strand. If not specified '+' is used.
7) *optional* `name`: the name of the feature e.g. 'At2g26540'. Can be anything. If not specified
`id` is used.
8) *optional* `color`: the color of the feature to override that specified by its type. if not specified
the value in `type` is used.
an example looks like ::
1,5,25,38,HSP,+,name1
2,4,22,123,HSP,+,name2
At2g26540,4,1110,1683,gene,+,feature name
3,4,1210,1653,CDS,+,name3
4,4,1210,1653,CDS,-,name4
Note the last 4 will all be drawn in a `Track`_ with id 4. The 5th will be
drawn in track with id '5' and only the 3rd item is on the - strand. You may
have thousands of annotations. The ids do not have to be numeric.
Consecutive `HSP`_'s will be linked with an edge.
Glyphs
------
Glyphs can be specified in the .css file as ::
{ glyph: cross; fill_color: #fff000; fill_alpha: 1.0 }
when a row in the annotations file has a type of 'cross', it will then be drawn
with a glyph that appears as a cross a the specified as the x coordinate specified.
For glyphs, the xmin, xmax columns will likely be the same, if not, the glyph will
be rendered in the center of the specified range.
Text
----
when the glyph is specified as glyph: text_glyph, the text in the `name` field will
be rendered as is. The text can contain any markup that flash can understand.
`See here `_
for a description of the supported tags. This allows arbitrary labelling,
coloring, and sizing for each feature.
See the example in `glyph.txt `_
Track
=====
An line in the annotation file with type 'track' defines the name and extent
of regions a track. The first column is used as the track_id (which is
referenced by other anntations) and the 2nd column is used as the display name.
The start and end indicate the bounds of the track. Annotations outside of
these bounds will not be rendered.
an example looks like (note this is the same format and same file as
`Annotations`_) ::
track_1,Track 1,9,1999,track
So in that example, the bounds are from 9 to 1999 in basepair coordinates and
any annotation beloning to this track will use 'track 1' in the track column.
**NOTE** that if no tracks are specified then the track ids and extents
will be inferred from the annotations. The extent of the annotations for
each track will be padded slightly to calculate the extent of the track.
HSP
===
Consecutive HSP's specified in the `Annotations`_ file are related.
Inside the flash movie, clicking either part of an HSP will result in
a wedge being drawn between it and its pair (as in the example images).
edges are inferred between consecutive HSP's. So that hsp annotation
lines like::
1,HSP,25,38,+,4,4
2,HSP,22,123,+,5,5
3,HSP,35,68,+,4,4
4,HSP,99,223,+,5,5
will infer edges between HSP's 1,2 and HSP's 3,4. This is common e.g. when
parsing a blast, where it's very simple to output consecutive lines for a
single blast pair.
Any annotation **beginning with** "HSP" will be treated in this manner. This
allows one to have different style classes for HSPs. e.g. HSP_blue, HSP_red.
Style
=====
Styling is done via CSS. See the `default style `_
in gobe. When adding new features, it's wise to add a new style corresponding to each feature type.
The style sheet is specified on the URL through the style argument. e.g. ::
&style=/static/super-awesome.css
it must be on the same server as the SWF movie, or set up on a server that allows access via
crossdomain.xml.
Plots
=====
It is also possible to plot line plots and histogram plots. Here is an example with a line plot
on the top strand and a histogram on the bottom strand. (this is linked in index.html examples).
.. image:: http://lh6.ggpht.com/_uU_kLC5AdTc/S_waNKlZqwI/AAAAAAAAA1Q/6cmENZia_Co/gobe_plot.png
LinePlots
---------
The data-source for a line plot is indicated in the annotations file by a line
like::
#id,track_id,xmin,xmax,style,strand,data-source
plot1,q,71630143,71695587,plot_line,+,data/pair/gc_content.txt
where the `track_id` indicates the track on which to draw the plot.
and the final column indicates a (local) url from which to get the data.
The data format is a **single y value per line** with the number of lines matching
the range specified by the `xmin`, `xmax` parameters in the annotations file.
NOTE: the `style` type specified in the annotations file must be exactly:
'plot_line'. Data is scaled automatically. If a plot is specified in a new track (without
other annotations, the values specified in the `xmin`, `xmax` will be used as the track bounds
and it will be drawn in it's own track.
The line-color and width are specified in the css file under plot_line.
See the example `data `_
, `annotations file `_ (the line with id of 'plot1')
and `css `_
Histograms
----------
Histograms are specified in the same manner as `LinePlots`_ except the style type must be:
'plot_hist'. An example annotations line looks like::
#id,track_id,xmin,xmax,style,strand,data-source
plot2,q,71630143,71695587,plot_hist,-,data/pair/hist_data.txt
the format for histogram data is 4 columns:
1) xmin
2) xmax
3) y
4) hex-color
so example data looks like::
71692442,71692569,20,#ff0000
71692721,71692883,21.444,#fc0000
71693023,71693079,38,#ffff00
71693375,71693591,60.2,#ff00bb
This allows one to specify arbitrary widths and colors for each bar.
Javascript Callbacks
====================
Whenever you click an annotation Gobe.onclick() is called with arguments:
id, name, bpx, px, track_id corresponding to the values in the annotations
file you specified. You should override this callback to perform sophisticated
queries on an annotation, e.g.: via an AJAX call to a server-side script which
will return more information about the feature.
Getting Started
===============
The best way is to copy the index.html example included in the repository,
adjust the paths to correctly point to your own gobe.js and the gobe.swf and
then specify the paths to your own data with a url like:
/gobe/?annotations=data/t.annos&style=gobe.css
Once you have each of those files in the proper location, gobe will render the
interactive flash movie.
TODO
====
* improve docs.
* customizable fonts
* move HSP colors to CSS.
.. image:: http://lh4.ggpht.com/_uU_kLC5AdTc/S9O1wilCMBI/AAAAAAAAA0A/NniSF6OhTps/s800/screen2.png
.. _`haxe`: http://haxe.org/