Revision as of 17:20, 19 January 2009

Introduction

GBrowse 2.0 is a complete rewrite of the original GBrowse version. In addition to making the code base more maintainable, GBrowse 2.0 adds the following major features:

• User Interface: The user interface uses AJAX to provide a smoother user experience. Tracks turn on and off immediately, and updates affect only the tracks that have changed.

• More rational configuration: Most configuration options have been moved into a single shared configuration file. This allows data source-specific files to be shorter and more concise. This also increases the performance for sites that use hundreds of configuration files to display annotations on multiple species because only the global configuration file and the source-specific configuration file need to be read.

• Multiple database support: You can now declare multiple databases for each data source and attach them to different tracks. This allows you to add and remove genome annotation data sets far more easily than in earlier versions.

• Slave renderer support: If you have a multi-CPU processor, or access to several machines, you can distribute the tasks of reading the databases and rendering tracks across multiple processes and machines via a series of "slave" renderers. This greatly increases performance.

This document describes how to install and configure GBrowse 2.0 on your system. Readers familiar with GBrowse 1.70 or earlier should start with the next section, which is a quick summary of what is different. Readers who have not installed or configured GBrowse before should skip to GBrowse Installation.

For Users of GBrowse 1.X

GBrowse 2.0 is largely backward compatible with GBrowse 1.X, but you will need to do some modest work in order to port existing sources to the new system. Please see Migrating from GBrowse 1.X to 2.X for a guide to the process.

GBrowse Installation

This section describes how to install GBrowse 2.0 on either Linux or Mac OSX systems. Windows users please see Installing GBrowse 2.0 on Windows (document pending).

Prerequisites and Downloading

First, make sure that your system has all the GBrowse 2.0 Prerequisites installed.

Download (or CVS checkout) the distribution. GBrowse 2.00 is currently only available via CVS, so the command to issue is:

cvs -d:pserver:anonymous@gmod.cvs.sourceforge.net:/cvsroot/gmod co Generic-Genome-Browser

This will create a directory named Generic-Genome-Browser:

Running the Build.PL Script

Next, enter the newly-created directory and run the Build.PL script:

 % '''cd Generic-Genome-Browser'''
 % '''perl Build.PL'''
 Checking whether your kit is complete...
 Looks good

 Checking prerequisites...
 Looks good

 cc -I/usr/lib/perl/5.8/CORE -fPIC -c -D_REENTRANT -D_GNU_SOURCE -DTHREADS_HAVE_PIDS -DDEBIAN -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -O2 -o /tmp/compilet.o /tmp/compilet.c
 cc -shared -L/usr/local/lib -o /tmp/compilet.so /tmp/compilet.o

 Creating new 'Build' script for 'GBrowse' version '2.00'
 Now run:
  ./Build test
  ./Build config
  ./Build demo          (optional)
  ./Build install       (as superuser/administrator)
        -or-
  ./Build install_slave (optional, for slave installations)

% cd ~/packages
% wget http://www.bioperl.org/DIST/nightly_builds/bioperl-live.tar.gz
% tar zxvf bioperl-live.tar.gz
% cd ~/packages/Generic-Genome-Browser
% perl -I ~/packages/bioperl-live Build.PL

Among other things, this script will check for missing Perl libraries that you need to run GBrowse, and will tell you about them. Please be sure to install all prerequisites before going any further. All but one of the prerequisites can be downloaded from CPAN or installed from the command line using the CPAN shell. There are also Debian and RPM installer packages for these libraries. See GBrowse 2.0 Prerequisites for full details.

This will create a script named Build in the current directory.

Running the Build Script

You will now use Build to test, configure and install GBrowse. First you will confirm that GBrowse's libraries are completely functional by running ./Build test (the "./" is there to ensure that you are running the Build script in the current directory, and not some other Build script somewhere in your path:

 % '''./Build test'''
 t/01yeast...................ok
 t/02.rearchitecture.........ok
 t/03.render.................ok
 ...
 All tests successful.
 Files=8, Tests=323, 12 wallclock secs
 Result: PASS

All tests should pass (you may safely ignore warnings and occasional timeout errors). If not, please file a bug report, and/or send an inquiry to the GBrowse mailing list.

Selecting Installation Directories

After passings its tests, you should configure GBrowse by running ./Build config:

 % '''./Build config'''

 **Beginning interactive configuration**
 Apache loadable module directory (for demo)? [/usr/lib/apache2/modules]
 Apache CGI scripts directory? [/usr/lib/cgi-bin]
 Directory for GBrowse's config and support files? [/etc/GBrowse2]
 Directory for GBrowse's static images & HTML files? [/var/www/gbrowse2]
 Internet port to run demo web site on (for demo)? [8000]
 User account under which Apache daemon runs? [www-data]

 **Interactive configuration done. Run './Build reconfig' to reconfigure**

The configuration process will ask you to confirm six site-specific configuration options, and will do its best to guess for you. In most cases you can just hit return to accept the default. If you specify a directory that does not exist, the system will ask you to confirm that this is what you mean. If you press yes, the directory (and all its needed parents) will be created at install time.

The configuration options are:

apachemodules

The directory in which Apache's loadable modules are located. This is only needed to run a demo GBrowse site before formal installation. If you do not know the location of this directory and you do not want to run the demo, you can safely ignore this option.

cgibin

The directory in which Apache's executable CGI scripts are located, for example /usr/lib/cgi-bin. This directory is set up for you when Apache is installed, and you must have the path correct in order for Build to install GBrowse's CGI scripts in the right place. GBrowse will be installed into the "gb2" subdirectory, so its path will be "/usr/lib/cgi-bin/gb2/gbrowse".

conf

The location of GBrowse's configuration files. The default is to place them in /etc/gbrowse2. This is where you will go to customize GBrowse and add new data sources.

databases

The default location for GBrowse's in memory databases, and the place where the example databases will be stored. The default is to place this into a subdirectory of the same directory in which GBrowse places its static files, such as /var/www/gbrowse2/databases.

htdocs

The directory in which to install GBrowse's Javascript libraries, static HTML pages and stylesheets. You can choose any location for this directory and it will be added to Apache's document tree. The default is to place the directory under the default document tree, such as /var/www/gbrowse2.

portdemo

The internet port on which the demo will run. The demo launches a new instance of Apache running under your user privileges. Because port 80 will usually already be taken by the system Apache, Build will choose an unused port like 8000 or 8080. You may manually select the port if you wish.

tmp

The directory in which GBrowse will store its working data, including users' session information (such as preferred tracks), uploaded data files, and temporary image files. The default is to place these files into /var/tmp/gbrowse2.

wwwuser

The account under which the system Apache runs, often "nobody", "www-data" or "httpd." If you do not know, you can find out by running ps aux | grep -i apache on a system that has Apache already running. The first column of the output contains the name of the user account.

Once you have configured GBrowse, the values you chose will stick until you run ./Build reconfig. You can also bypass interactive configuration by directly passing Build.PL one or more of the configuration options on the command line:

perl Build.PL --apachemodules=/usr/local/share/apache/libexec \
              --cgibin=/var/lib/cgi \
              --conf=/etc/gbrowse \
              --htdocs=/usr/local/docs/gbrowse \
              --databases=/usr/local/gbrowse/databases \
              --tmp=/tmp/gbrowse \
              --portdemo=9000 \
              --wwwuser=fred

The options passed on the command line will become the defaults for ./Build config will be used during installation, and will also become the defaults if you later run ./Build config or ./Build reconfig.

Running the GBrowse Demo (optional)

Before you install GBrowse, you may wish to run its demo. This will attempt to launch a correctly configured instance of Apache running under your own account. To launch the demo, run ./Build demo:

% ./Build demo
Demo is now running on http://localhost:8000
Run "./Build demostop" to stop it.

You can now point your web browser at http://localhost:8000 (or whatever the build message specifies), and interact with the GBrowse web site, browse sample genomes and otherwise test the waters. When you are done, run ./Build demostop to stop Apache and clean up.

Final Installation

To install GBrowse and its support files permanently, run ./Build install as the superuser. This will copy GBrowse's library and support files into the locations chosen during configuration. It will then configure Apache to run GBrowse by writing the appropriate configuration directives into Apache's configuration file. Finally, it will attempt to restart Apache. If all goes well, you will see a note telling you to load http://localhost/gbrowse2. This will take you to an autogenerated page that describes the install configurations you chose, points to an example database to run, and gives pointers to documentation, tutorials and other useful information.

Debugging and Customizing the Installation

If you are having trouble with the installation, see Common Problems with GBrowse2 Installation. If you wish install GBrowse in your home directory because you do not have superuser privileges or for any other reasons, see Installing GBrowse2 in your Home Directory.

Configuring GBrowse

GBrowse's options and controlled by two types of configuration file. GBrowse.conf contains site-specific options that apply to all data sources. One or more Data source-specific configuration files define the options needed to create a specific genome browser.

GBrowse.conf

When you installed GBrowse, it created an initial GBrowse.conf configuration file in the directory you specified at configure time. The default location of this directory is /etc/gbrowse2. This file contains two types of information:

1. Global configuration options to apply to all data sources that you want to make available to users.
2. A list of the data sources, including their names and their source-specific configuration files.

Here is the default GBrowse.conf:

# This is the global configuration for gbrowse
# It contains setting common to all data sources as well
# as the various constants formerly scattered amongst scripts and libraries

[GENERAL]
config_base            = /etc/GBrowse2   # overridden by environment variable GBROWSE_CONF
htdocs_base            = /var/www/gbrowse2
url_base               = /gbrowse2
db_base                = /var/www/gbrowse2/databases
tmp_base               = /var/tmp/gbrowse2
tmp_slave              = /var/tmp/gbrowse2/slave

# These paths are relative to the config base
plugin_path    = plugins
language_path  = languages
templates_path = templates
moby_path      = MobyServices

# Session settings
session driver = driver:file;serializer:default
session args   = Directory /var/tmp/gbrowse2/sessions

titles are balloons = 1

# Debug settings
debug                  = 0
debug_external         = 0
debug_plugins          = 0

# Performance settings
renderfarm             = 1
cache time             = 2h
slave_timeout          = 45
global_timeout         = 60
remember_source_time   = 3M
remember_settings_time = 1M

# Appearance (can be overridden in per datasource config files)
# the stylesheet is relative to url_base if not otherwise noted
balloon tips        = 1
titles are balloons = 1
stylesheet          = css/gbrowse.css
plugins             = FastaDumper RestrictionAnnotator SequenceDumper Submitter
overview grid       = 0
detail grid         = 1
overview bgcolor    = lightblue
detail bgcolor      = lightgoldenrodyellow
key bgcolor         = beige
image widths        = 450 640 800 1024
default width       = 800
pad_left            = 60
pad_right           = 30
too many landmarks  = 100

# where to link to when user clicks in detailed view
link          = AUTO

# HTML to insert inside the <head></head> section
head =

# At the top of the HTML...
header =

# At the footer
footer = <hr />

# Various places where you can insert your own HTML -- see configuration docs
html1 =
html2 =
html3 =
html4 =
html5 =
html6 =

# Limits on genomic regions (can be overridden in datasource config files)
region segment         = 200000
max segment            = 5000000
default segment        = 5000
zoom levels            = 100 200 1000 2000 5000 10000 20000 50000 100000 200000 5000000 1000000
region sizes           = 1000 5000 10000 20000
default region         = 5000

# keyword search maxima
too many segments      = 5000
too many features      = 100
too many refs          = 5000
max keyword results    = 1000

# constants you probably don't need to change
mag icon height        = 20
mag icon width         = 8
fine zoom              = 10%
tiny seg size          = 2
expand seg size        = 5000
overview ratio         = 1.0
annotation edit rows   = 25
annotation edit cols   = 100

###############################################################################################
#
# One stanza for each configured data source
#
###############################################################################################
default source = yeast

[yeast]how long
description   = S. cerevisiae chromosomes I & II
path          = yeast_chr1+2.conf

[renderfarm]
description  = Renderfarm demo (gbrowse_slave must be running!)
path         = yeast_renderfarm.conf

GBrowse.conf consists of several sections. The [GENERAL] section is the largest, and describes options that apply to GBrowse globally. Below this are one or more source-specific sections with short descriptive names like [yeast]. Each of these short sections describes a genome datasource which you will make available for browsing. how long

The GBrowse.conf [GENERAL] Section

The [GENERAL] section defines a large number of options, most of which you will never need to change. The format of an option is the option name, an equals sign, and the value of the option. There may be whitespace before and after the equals sign. To continue long option values across multiple lines, begin the second and subsequent lines with one or more spaces or tabs; the additional whitespace will be treated as a single space. Lines beginning with the hash (#) symbol are comments. Please note that for historical reasons, some options separate words by underscores ("remember_settings_time") and others separate words by spaces ("cache time"). The two forms are not interchangeable.

Several options take true/false values. A false value is numeric 0. A true value is numeric 1, or indeed any other non-zero value (including the word true).

Paths and Directories

config_base, htdocs_base, url_base, db_base, tmp_base,tmp_slave

The first six options describe the location of GBrowse's configuration and support files. config_base is the location of GBrowse's datasource-specific configuration files, typically /etc/gbrowse2. htdocs_base specifies the location of GBrowse's static HTML files, stylesheets and javascript libraries. url_base is similar to htdocs_base and gives the location of same HTML files, stylesheets and javascript libraries in URL form. So, for example, if GBrowse's static files are located in /var/www/html/GBrowse and this maps in URL space to http://your.site/GBrowse, then htdocs_base will be /var/www/html/GBrowse and url_base will be /GBrowse. db_base describes the default location of in-memory databases. tmp_base points to the directory used for user sessions, uploads and other temporary files. Finally, tmp_slave describes the temporary directory used by GBrowse's optional rendering slaves (see Running a GBrowse2 Render Farm).

The config_base directive is overridden by the environment variable GBROWSE_CONF. This variable is set when Apache starts up, and can be found in /etc/apache2/conf.d/gbrowse2.conf, /etc/httpd/conf.d, or /etc/apache/conf.d, depending on how your system is layed out.

buttons,balloons,gbrowse_help,js

These four configuration options tell GBrowse where to find the images for its navigation buttons, popup balloons, help pages, and javascript libraries. Ordinarily you will not need to change these locations. The default locations are subdirectories of htdocs_base. If you specify a relative path, they will be taken as relative to htdocs_base (in filesystem space) and url_base (in URL space).

plugin_path, language_path, templates_path, moby_path

These configuration options specify where plugins, language translation files, templates and MOBY configuration files are located. If relative paths are given here, they are taken relative to the config_base. The default is to place them in subdirectories of config_base.

Session Settings

session driver, session args

These two options pass settings to the CGI::Session module, which is responsible for GBrowse's persistent user settings. As described in the CGI::Session documentation, session driver selects the driver to be used for storing and retrieving user session information, and session args passes additional arguments to the selected driver. The default is to use the standard "file" driver. To use the faster (but not universally available) DB_File driver, the options might look like this:

 session driver = driver:db_file;serializer:default
 session args   = FileName /var/tmp/gbrowse2/sessions.db

Debug Settings

The next set of options toggles on or off various debug flags, enabling you to watch what GBrowse2 is doing and help the developers catch and fix bugs. Their values are either 0 (no debugging messages) or 1 (activate debugging messages). When debugging is active, the messages will appear in the Apache error log, typically /var/log/apache2/error_log.

debug

This turns on messages about general GBrowse operations.

debug_external

This turns on messages concerning the uploading and processing of user-supplied tracks, as well as tracks fetched from remote sources via the DAS protocol.

debug_plugins

This turns on debugging messages concerning the operation of GBrowse's user-contributed plugins.

Performance Settings

This section contains a variety of performance-related settings that you may want to change in order to tune GBrowse for your needs.

renderfarm

This configuration directive turns on and off GBrowse's support for a rendering farm (see Running a GBrowse2 Render Farm). By default this support is enabled, but there no particular performance penalty if you choose not to take advantage of it. If you plan never to use the feature, set it to a false (zero) value:

 renderfarm = 0

cache_time

How long tracks will be cached before they are regenerated. This speeds up page load speed for frequently-accessed pages. The format is a number followed by a time unit, where units are s for second, m for minute, h for hour, d for day, and M for month. The default is "2h", or two hours.

slave_timeout

When running a GBrowse2 render farm, this option controls how long the master server will wait for one of its slaves before it times out and considers the slave "down". The units are seconds, 45 seconds by default.

global_timeout

If a database query, search or plugin takes longer than the number of seconds given by this option, GBrowse will time out and return an error to the user. The default is 60 seconds.

remember_source_time

This option controls how long the user's last-selected data source will be remembered in his or her session. The format is similar to cache_time and is a number followed by a time unit, where units are s for second, m for minute, h for hour, d for day, and M for month. The default is "3M" for three months.

remember_settings_time

This option controls how long the user's track configuration, which includes which tracks are turned on and their customized settings, will be remembered in his or her session. The format is the same as remember_source_time and is set to one month by default.

allow remote callbacks

If this option is set to a true (non-zero) value, then uploaded and remote track files will be able to contain configuration stanzas with Perl callbacks. The callbacks will be executed if and only if the Perl Safe::World module is installed on your server. This module provides a restricted execution environment that mitigates (but does not eliminate) the risk from untrusted code accessing local files and other sensitive content. Note that Safe::World does not currently work with Perl 5.10 and higher.

Appearance Settings

The following options control the appearance and behavior of GBrowse. Unlike the earlier options, any of them can be overridden on a per-datasource basis in datasource-specific configuration files simply by inserting the option into the [GENERAL] section of the datasource-specific config file.

balloon tips

This is a true/false option. If true, popup balloons are activated such that when the user mouses over a feature, additional information about that feature appears in a balloon.

titles are balloons

This is a true/false option. If true, popup balloons are automatically populated by default information about the feature unless a track has a balloon hover option that overrides the content. If false, then you will need to set the balloon hover option for the track in order for balloons to appear at all.

stylesheet

This option sets the path to the GBrowse cascading stylesheet (CSS) file. This sets such options as the page background color, font size, background image, and so forth. Edit this option here to change the appearance of all data sources, or add a stylesheet option to the [GENERAL] section of datasource-specific configuration files to change the appearance on a case-by-case basis.

You can also specify multiple stylesheets by separating them by spaces or newlines. To associate specific stylesheets with different media types, place the media type(s) in parentheses and append them to the stylesheet, as in the following example:

stylesheet = css/gbrowse.css(screen)
             http://www.example.com/hires.css(paper,projection)
             http://www.example.com/audio.css(audio)

plugins

This option selects which, if any, of the GBrowse plugins to offer to the user. It is a space-delimited list of plugin names. Plugins are Perl .pm modules that can be found in the plugins subdirectory of the GBrowse2 configuration directory. Select the ones you wish to activate, and put their in this configuration directive, minus the ".pm" extension. See GBrowse2 Plugins for a description of what each plugin does.

overview grid, region grid, detail grid

These three options control whether the background grid should be displayed in the overview, region, and detail panels by default. They are either true (1) or false (0) values. The user can later turn the detail panel grid on and off, but currently there is no user interface for deselecting the overview and region grids.

image widths, default width

These two options control the width of the panels displayed to the user. image widths is a space-delimited list of numeric widths to be made available to the user to select from. default width is a single numeric value indicating the default width when the user first loads the browser. In this example, the browser assumes a default width of 1024 pixels, but offers the user a menu of five widths ranging from 450 to 1280 pixels.

image widths    = 450 640 800 1024 1280
default width   = 1024

pad_left, pad_right

These options control how much additional whitespace (in pixels) to surround the detail panel with on the left and the right. This is sometimes necessary for glyphs that need extra space to the left or right for additional information. An example of this is the UCSC multiple alignment glyph.

too many landmarks

This option controls the maximum number of results to return when the user performs a wildcard search on the database. The default is 100.

hilite fill

This option controls the interior color of the selection rectangle that appears when the user clicks and drags on a scalebar, as well as the highlighted region of the currently selected region. It accepts a Graphics color value, such as "beige:0.8" for a beige background at 80% opacity.

hilite outline

This option controls the outline color of the selection rectangle that appears when the user clicks and drags on a scalebar, as well as the highlighted region of the currently selected region. It accepts a Graphics color value, such as "red:0.8".

overview bgcolor, region bgcolor, detail bgcolor

These three options control the background colors of the overview, region and detail panels respectively. They each accept Graphics color values.

grid color, grid major color

These options control the appearance of the grid lines in the overview, region and detail panels. The first controls the color of the minor grid lines, and the second controls the color of the major grid lines. They each accept a Graphics color value.

Configuring Genomic Regions

Several options allow you to configure the behavior of genomic regions, such as the levels of zoom you wish to offer and the largest segment of genome that it is safe to display in the detail panel.

max segment

The maximum size (in base pairs) that the detail panel can display. If the user tries to display a region that is too large, he will be given a message to select a smaller region. GBrowse performance degrades as the number of features per track increases, so you can use this setting to avoid making the user wait unreasonable lengths of time for the region to display.

zoom levels

A space-delimited list of region sizes (in base pair) that the user can zoom through. Each zoom level will be listed in a popup menu in the navigation bar. This example offers the user resolutions of 100, 500, 1000, 5000, 50000, and 100,000 bp:

zoom levels  = 100 500 1000 5000 50000 100000

fine zoom

This option controls the increment that the user will zoom in or out when pressing the "+" and "-" buttons in the navigation bar. The default value is "10%".

default segment

If the user has selected a region that is too large to display, then single-clicks on one of the scale bars, he will be centered on a region this many base pairs in length.

region sizes

This option is similar to zoom levels except that the list of zoom levels applies to the region panel.

default region

This option specifies the default length of the region panel, in bp.

max keyword results

If the user does a wildcard or keyword search, this option limits the maximum number of results that can be displayed.

HTML Customization Settings

Several settings in the [GENERAL] section allow you to insert fragments of HTML (including images) into the GBrowse screen. This lets you create banners and other cutomizations for visual integration with other pages on your site.

header,footer

These two options place HTML at the top or bottom of the page. Example:

 header = <img src="/banner.jpg">
 footer = <hr>For help please see the <a href="help.html">help pages.</a>

html1,html2,html3,html4,html5,html6

These options insert snippets of HTML in various strategic places on the page:

Configured Data Source Sections

After the [GENERAL] section comes a list of all the data sources that you can make visible to the user. The format of each data source is as follows:

[symbolic_name_of_data_source]
description = human readable description of this data source
path        = path_to_the_source_config_file.conf

Each data source declaration begins with the name of the data source, enclosed in square brackets. Any name is allowed, provided that it does not contain newlines. The name "GENERAL" is also disallowed, to avoid conflicts with the [GENERAL] section.

Each data source has description and path options. The first provides a human-readable description of the source; this description will appear in the menu offered to the user in the navigation bar. The path option indicates the location of the configuration file for this data source. Relative paths are interpreted relative to GBrowse.conf. In the usual case, you will store all your data source config files in the same directory as GBrowse.conf.

To specify a default data source to show when the user first visits GBrowse, place a default source option before the first data sources stanza. For example, to specify the zebrafish v2 data source as the default, create a data source config section like the following:

default source = zebrafish v2

[zebrafish v3]
description    = Zebrafish genome, build 2
path           = zebra3.conf

[zebrafish v2]
description    = Zebrafish genome, build 1 (deprecated)
path           = zebra2.conf

If no default source option is defined, GBrowse will pick the first data source stanza as default.

Data Source Configuration Files

Each data source has an configuration file listed in the main GBrowse.conf configuration file. This configuration file specifies the databases to connect to, defines the tracks to show, and allows you to customize some of the appearance options specified in GBrowse.conf. Each data source configuration file has three sections, the [GENERAL] section, the database definitions section, and the track sections. In addition there are some special sections that allow you to configure advanced options.

The [GENERAL] Section

In the [GENERAL] section, you can override all the display options specified in GBrowse.conf, including the stylesheet, panel colors, genomic region length, zoom levels, and so forth. In addition, this section recognizes the following source-specific options:

database

This option sets the default database to use when searching and displaying features. See #Database Definitions below.

default tracks,default features

The default tracks options control which tracks are turned on by default when the user visits the browser for the first time. Its value is a whitespace-delimited list of track names, for example:

default tracks = Genes ORFs tRNAs CDS Centro:overview

An earlier (deprecated) name for this option was default features and this name is recognized for backward compatibility.

examples

This option designates a list of searches that the user can click on to see sample regions. For example:

examples = chrI

chrII chrI:80,000..120,000 "membrane trafficking" NUT21 YAL063C

automatic classes

This option can be used in conjunction with the Bio::DB::GFF database adaptor in order to designate one or more namespaces to use when searching for features by name. This option is not needed unless you are using a legacy database.

Database Definitions

Following the [GENERAL] section, each data source config file must have one or more database definition stanzas. This type of stanza begins with the heading [name:database], where name is any symbolic name you choose.

Advanced Topics

These are advanced configuration topics.

Grouping Features

GBrowse recognizes the concept of a "group" of related features that are connected by dotted lines. The canonical example is a pair of ESTs that are related by being from the two ends of the same cDNA clone. However many feature databases, including the GFF database recommended for GBrowse, do not allow for arbitrary hierarchical grouping. To work around this, you may specify a feature name-based regular expression that will be used to trigger grouping.

It works like this. Say you are working with EST feature pairs and they follow the nomenclature 501283.5 and 501283.3, where the suffix is "5" or "3" depending on whether the read was from the 5' or 3' ends of the insert. To group these pairs by a dotted line, specify the "group_pattern" option in the appropriate track section:

     group_pattern =  /\.[53]$/

At render time, GBrowse will strip off this pattern from the names of all features in the EST track and group those that have a common base name. Hence 501283.5 and 501283.3 will be grouped together by a dotted line, because after the pattern is removed, they will share the same common name "501283".

This works for all embedded pattern, provided that stripping out the pattern results in related features sharing the same name. For example, if the convention were "est.for.501283" and "est.rev.501283", then this grouping pattern would have the desired effect:

     group_pattern = /\.(for|rev)\./

Don't forget to escape regular expression meta-characters and to consider the various ways in which the regular expression might break. It is entirely possible to create an invalid regular expression, in which case gbrowse will crash until you comment out the offending option.

Controlling the gbrowse_details page

If a track definition's "link" option (see section B2) is set to AUTO, the gbrowse_details script will be invoked when the user clicks on a feature contained within the track. This will generate a simple table of all feature information available in the database. This includes the user-defined tag/value attributes set in Column 9 of the GFF for that feature.

You can control, to some extent, the formatting of the tag value table by providing a configuration stanza with the following format:

 [feature_type:details]
 tag1 = formatting rule
 tag2 = formatting rule
 tag3 = formatting rule

"feature_type" is the type of the feature you wish to control. For example, "gene:sgd" or simply "gene". You may also specify a feature_type of "default" to control the formatting for all features. "tag1", "tag2" and so forth are the tags that you wish to control the formatting of. The tags "Name," "Class", "Type", "Source", "Position", and "Length" are valid for all features, while "Target" and "Matches" are valid for all features that have a target alignment. In addition, you can use the names of any attributes that you have defined. Tags names are NOT case sensitive, and you may use a tag named "default" to define a formatting rule that is general to all tags (more specific formatting rules will override less specific ones).

A formatting rule can be a string with (possible) substitution values, or a callback. If a string, it can contain one or more of the substitution variable "$name", "$start", "$end", "$stop", "$strand", "$method", "$type", "$description" and "$class", which are replaced with the corresponding values from the current feature. In addition, the substitution variable "$value" is replaced with the current value of the attribute, and the variable "$tag" is replaced with the current tag (attribute) name. HTML characters are passed through.

For example, here is a simple way to boldface the Type field, italicize the Length field, and turn the Notes into a Google search:

 [gene:details]
 Type   = <b>$value</b>
 Length = <b>$value</b>
 Note  = <a href="http://www.google.com/search?q=$value">$value</a>

If you provide a callback, the callback subroutine will be invoked with three arguments. WARNING: the three arguments are different from the ones passed to other callbacks, and consist of the tag value, the tag name, and the current feature:

 Note = sub {
            my($value,$tag_name,$feature) = @_;
            do something....
            }

You can use this feature to format sequence attributes nicely. For example, if your features have a Translation attribute which contains their protein translations, then you are probably unsatisified with the default formatting of these features. You can modify this with a callback that word-wraps the value into lines of at most 60 characters, and puts the whole thing in a <pre> section.

[gene:details]
Translation = sub {
               my $value = shift;
               $value =~ s/(\S{1,60})/$1\n/g;
               "<pre>$value</pre>";
            }

Linking out from gbrowse_details

The formatting rule mechanism described in the previous section is the recommended way of creating a link out from the gbrowse_details page. However, an older mechanism is available for backward compatibility.

To use this legacy mechanism, create a stanza header named [TagName:DETAILS], where TagName is the name of the tag (attribute name) whose values you wish to turn into URLs, and where DETAILS must be spelled with capital letters. Put the option "URL" inside this stanza, containing a string to be transformed into the URL.

For example, to link to a local cgi script from the following GFF2 line:

IV     curated exon    518     550     . + .   Transcript B0273.1; local_id 11723

one might add the following stanza to the configuration file:

   [local_id:DETAILS]
   URL   = http://localhost/cgi-bin/localLookup.cgi?tag=$tag;id=$value

The URL option's value should be a URL containing one or more variables. Variables begin with a dollar sign ($), and are replaced at run time with the information relating to the selected feature attribute. Recognized variables are:

    $tag        The "tag" of the tag/value pair
    $value      The "value" of the tag/value pair

The value of URL can also be an anonymous subroutine, in which case the subroutine will be invoked with a two-element argument list consisting of the name of the tag and its value. This example, provided by Cyril Pommier, will convert Dbxref tags into links to NCBI, provided that the value of the tag looks like an NCBI GI number:

[Dbxref:DETAILS]
URL = sub {
      my ($tag,$value)=@_;
      if ($value =~ /NCBI_gi:(.+)/){
       return "http://www.ncbi.nlm.nih.gov/gquery/gquery.fcgi?term=$1";
       }
       return;
     }

Configuring Balloon Tooltips

GBrowse can display popup balloons when the user hovers over or clicks on a feature. The balloons can display arbitrary HTML, either provided in the config file, or fetched remotely via a URL. You can use this feature to create multiple choice menus when the user clicks on the feature, to pop up images on mouse hovers, or even to create little embedded query forms. See http://mckay.cshl.edu/balloons.html for examples.

In the config file for the database you wish to modify, set "balloon tips" to a true value:

     [GENERAL]
     ...
     balloon tips = 1

Then add "balloon hover" and/or "balloon click" options to the track stanzas that you wish to add buttons to. You can also place these options in [TRACK DEFAULTS] to create a default balloon.

"balloon hover" specifies HTML or a URL that will be displayed when the user hovers over a feature. "balloon click" specifies HTML or a URL that will appear when the user clicks on a feature. The HTML can contain images, formatted text, and even controls. Examples:

 balloon hover = <h2>Gene $name</h2>
 balloon click = <h2>Gene $name</h2>
                 <a href='http://www.google.com/search?q=$name'>Search Google</a><br>
                 <a href='http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=pubmed&term=$name'>Search NCBI</a><br>

Alternatively, you can populate the balloon using data from an HTML page or dynamic CGI script running on the same server as GBrowse. This uses AJAX; it can often speed up page loading by reducing the amount of text that must be downloaded by the client. To dynamically load the balloon contents from the server, use a balloon hover or balloon click option like this:

 balloon click = /cgi-bin/get_gene_data?gene=$name

In this case, when the user clicks on the feature, it creates a balloon whose content contains the HTML returned by the CGI script "get_gene_data". GBrowse knows that this is a URL rather than the contents of the balloon by looking for the leading slash. However, to reduce ambiguity, we recommend that you prefix the URL with "url:" as so:

 balloon click = url:/cgi-bin/get_gene_data?gene=$name

This also allows you to refer to relative URLs:

 balloon click = url:../../get_gene_data?gene=$name

It is also possible to fill the balloon with content from a remote source. Simply specify a full URL beginning with "http:" "https:" or "ftp:"

balloon hover = http://www.wormbase.org/db/get?name=$name;class=gene

Note that the balloon library uses an internal <iframe> to populate the balloon with the content of external URLs. This means that vertical and horizontal scrollbars will appear if the content is too large to be contained within the balloon. If the formatting does not look right, you can design a custom balloon of the proper size as described in the next section.

The usual option value substitution rules ($name, $start, etc) work with balloons, as do callbacks. GBrowse will automatically escapes single (') and double (") quotes in the values returned by the "balloon hover" and "balloon click" options so that you don't have to worry about them messing up the HTML.

You might also wish to specify "titles are balloons" in the [GENERAL] section:

 [GENERAL]
 titles are balloons = 1

This will generate balloons on all mouse hover events, using the content that would otherwise have been placed in the built-in browser tooltip.

There is a limited amount of balloon customization that you can perform within the [track] section. If you wish the balloon to be sticky (require the user to press the close button) even if it is a hover balloon, then place this option in the [track section]:

 balloon sticky = 1

Setting "balloon sticky" to 0 will have the effect of making balloons disappear as soon as the mouse leaves them, even if it was created by a mouse click event.

If you are displaying content from a remote web or FTP server and you do not like the height of the balloon, you can adjust the height with the "balloon height" option:

 balloon height = 400

Customizing Balloons

GBrowse supports multiple balloons with different shapes, sizes, background images and timing properties. There is one built-in balloon, named "balloon", which should meet most peoples' needs. However, you can configure any number of custom balloons.

To declare two new balloons, create a "custom balloons" option in the [GENERAL] section:

custom balloons = [blue_balloon]
                  images   =  /gbrowse/images/blue_balloons
                  maxWidth = 300
                  shadow   = 0

                  [wide_balloon]
                  maxWidth = 800

This creates two new balloons. The first, named "blue_balloon" will look for its images and icons at the local URL /gbrowse/images/blue_balloons. It will have a maximum width of 300 pixels, and will cast no shadow. The second, named "wide_balloon" takes all the defaults for the default balloon, including the location of its images in the directory /gbrowse/images/balloons, except that it has a maximum width of 800 pixels. The various balloon options are described well at http://www.gmod.org/wiki/index.php/Popup_Balloons.

To use the blue balloon rather than the standard one, format the "balloon hover" and/or "balloon click" options like this:

 balloon click = [blue_balloon] /cgi-bin/get_gene_data?gene=$name

The [blue_balloon] keyword tells gbrowse to use the blue balloon for clicks on these features. The standard balloon is called "balloon", and so the following two options are equivalent:

 balloon click = /cgi-bin/get_gene_data?gene=$name
 balloon click = [balloon] /cgi-bin/get_gene_data?gene=$name

The images for custom balloons reside in the default location of /gbrowse/images/balloons, unless indicated otherwise using the "images" config option. To use custom balloon images, point "images" to a a web-accessible directory in your document tree which contains the seven PNG images described at http://www.gmod.org/wiki/index.php/Popup_Balloons. These images must be named as follows:

 balloon.png     down_right.png  up_right.png
 balloon_ie.png  down_left.png   up_left.png
 close.png

Tips for creating these images can be found at the www.gmod.org WIKI described earlier.

Generating Static Images: PNGs, SVGs and PDFs

GBrowse can create three types of static image suitable for incorporation into posters, publications or other web pages:

• PNG -- a bitmapped format suitable for low-resolution graphics, such as web pages.
• SVG -- an editable vector-graphics format, suitable for posters, publications and other high-resolution applications.
• PDF -- the familiar document exchange format, suitable for posters, publications and other high-resolution applications.

All the work is handled by the gbrowse_img script and needs little configuration. When the user selects a region and set of tracks to browse, the "link to image" and "high-res image" links at the top of the page will be automatically set to reproduce the user's view as closely as possible. GBrowse_img customization options, including instructions on how to embed an image in a web page so that the clickable imagemap links are maintained, can be found here.

The PNG generation will work in the default installation. In order to get SVG generation to work, you will need to install the perl SVG and GD::SVG modules, available from CPAN.

For PDF generation, you will need the perl GD and GD::SVG modules installed, as well as a helper application called Inkscape. Inkscape provies a command-line tool that will convert SVG files into PDF. To install, download and install it somewhere on the standard system path (e.g. /usr/bin). You will then need to create two subdirectories in the web user's home directory in order for inkscape to work properly. Assuming that the web user is "www-data" run the following commands:

sudo mkdir ~www-data/{.inkscape,.gnome2}
sudo chown www-data ~www-data/{.inkscape,.gnome2}

This will create the two directories ".inkscape" and ".gnome2" in the www-data user's home directory, and make them writable by the www-data user.

Unfortunately, Inkscape will generate a one line warning into the server error log every time it executes:

(inkscape:28490): Gdk-CRITICAL **: gdk_display_list_devices: assertion `GDK_IS_DISPLAY (display)' failed

At the current time there is no known fix for this problem.

Note that Inkscape PDF generation should work properly on all platforms, including Linux, Mac OSX and Windows. However, it has only been tested on Linux platforms at the current time.