GBrowse 2.0 HOWTO
Important note: GBrowse 2.0 is in beta test phase. It can be found on CPAN (the Comprehensive Perl Archive Network) in the directory http://search.cpan.org/~lds/, or installed from CVS. The software is fully functional, but this documentation is incomplete.
Contents
- 1 Introduction
- 2 For Users of GBrowse 1.X
- 3 GBrowse Installation
- 4 Configuring GBrowse
- 5 Advanced Topics
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.
Installing via the CPAN Shell
You can install the latest released version of GBrowse by running the CPAN shell. Run this command:
sudo perl -MCPAN -e 'install Bio::Graphics::Browser'
This will run all the steps described in the "Installing Manually" section below, including configuring GBrowse's installation directories and installing GBrowse and its demo databases. Among other things, GBrowse will ask you a series of questions about where to install it. See #Selecting Installation Directories for a detailed description of each question. The suggested defaults are almost always correct.
If any perl modules are missing from the prerequisites, the CPAN shell will install them for you. This will run
Installing Manually
Alternatively, you can download and install the bleeding edge version via the CVS source code control system. 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)
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:
- Global configuration options to apply to all data sources that you want to make available to users.
- 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
# These paths are relative to the url base
buttons = images/buttons
balloons = images/balloons
gbrowse_help = .
js = js
# These paths are relative to the config base
plugin_path = plugins
language_path = languages
templates_path = templates
moby_path = MobyServices
# session settings
session lock type = default
session driver = driver:file;serializer:default
session args = Directory /var/tmp/gbrowse2/sessions
# to use the berkeley DB driver comment out the previous
# line and uncomment these two
#session driver = driver:db_file;serializer:default
#session args = FileName /var/tmp/gbrowse2/sessions.db
# Debug settings
debug = 0
debug_external = 0
debug_plugins = 0
# Performance settings
renderfarm = 1
slave_timeout = 45
global_timeout = 60
# Clean up settings (used by the gbrowse_clean script)
expire session = 1M # expire unused sessions after a month
expire cache = 2h # expire cached data if unmodified for >2 hours
expire uploads = 6w # expire uploaded data if unused for >6 weeks
# Appearance settings
truecolor = 1 # better appearance at the expense of larger image files
# The #include line following this one defines a transparent theme.
# Replace "transparent_colors" with "solid_gray_colors"
# or "warm_colors" for different themes.
#include "themes/transparent_colors"
balloon tips = 1
titles are balloons = 1
plugins = FastaDumper RestrictionAnnotator SequenceDumper TrackDumper
overview grid = 0
region grid = 0
detail grid = 1
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 />
<p style="font-size:small">Generic Genome Browser version 1.99. For questions about the data
at this site, please contact its webmaster. For support of the
browser software <i>only</i>, send email to
<a href="mailto:gmod-gbrowse@lists.sourceforge.net">gmod-gbrowse@lists.sourceforge.net</a>
or visit the <a href="http://www.gmod.org">GMOD Project</a> web pages.
</p>
# 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
fine zoom = 10%
# keyword search maxima
max keyword results = 1000
###############################################################################################
#
# One stanza for each configured data source
#
###############################################################################################
default source = yeast
[yeast]
description = Yeast chromosomes 1+2 (basic)
path = yeast_simple.conf
[yeast_advanced]
description = Yeast chromosomes 1+2 (advanced)
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.
There are two include directives that allow you to break up GBrowse configuration files into smaller logically-related bits. The directive:
#include "path/to/file"
will import the file at the named path into the configuration file. Relative path names are treated as relative to the location of the configuration file. Wildcards are also allowed. For example #include "/etc/gbrowse2/conf.d/*.conf" will include all files that match the wildcard pattern. This mechanism is currently used to defined a variety of GBrowse "themes" that set page background patterns and colors.
The directive:
#exec "/usr/bin/script_to_execute"
will cause the command "script_to_execute" to be executed each time the configuration file is loaded. The output of this script will be included into the configuration file.
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
- 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.
- 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
- session lock type
- Since GBrowse runs several processes in parallel, it needs to flag when another instance of it is working on session data in order to avoid another process from clobbering the same session. This option controls the type of locking to perform. Valid values are:
flock -- Use standard file locking. This works fine in most cases, but can cause GBrowse to
get very slow if its temporary directory is mounted on a shared NFS filesystem.
nfs -- Use the File::NFSLock module for locking. This is fast and works across NFS, but requires
you to install the File::NFSLock module from CPAN.
mysql -- Use the locking in the MySQL database. It is handy if you already have a Mysql database
up and running. The full format of this value is:
session lock type = mysql:dbi:mysql:my_db;host=hostname;port=portnum;user=user;password=pass
for simplicity, you can leave off the initial "mysql:".
- A value of default will choose the File::NFSLock module if it is available, and otherwise fall back onto standard flock.
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
- 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.
- 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.
Cleanup Settings
These settings are used by the gbrowse_clean.pl script to remove stale temporary files of various sorts.
- expire cache
- How long generated 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, w for week, and M for month. The default is "2h", or two hours.
- expire sessions
- 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 expire cache and is set to one month by default.
- expire uploads
- This option controls controls how long to keep user uploaded data for custom tracks on disk. It makes sense to keep it on disk for as long or longer than the session. Even if the user’s session expires, he can still get at the uploaded data if he bookmarked his session or shared the uploaded track at any point. The format is the same as expire cache and defaults to six weeks.
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.
- autocomplete
- This is a true/false option. If true, then any databases that have the "autocomplete" option set will be searched when the user types three or more letters into the GBrowse search field. Proposed matches will be displayed in a popup menu. Please see #Database Search Options for more information.
- 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.
- show sources
- Ordinarily GBrowse generates a popup menu showing all configured data sources; the user can change the datasource by selecting from this menu. To inhibit generation of this menu, set show sources to zero.
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:
| Option | Where it goes |
|---|---|
| html1 | between the title and the instructions bar |
| html2 | between the instructions and the navigation bar |
| html3 | between the navigation bar and the overview |
| html4 | between the detail view and the tracks table |
| html5 | between the tracks table and the add custom tracks section |
| html6 | between the add custom tracks section and the display settings |
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.
GBrowse will place the descriptions of all configured datasources into its Sources popup menu. To hide a source from the menu, simply place hide=1 into its stanza:
[zebrafish v2] description = Zebrafish genome, build 1 (deprecated) path = zebra2.conf hide = 1
Themes
GBrowse has a simple theming system that allows you to change colors and background patterns. This is done by #include-ing a themes file from the directory /etc/gbrowse2/themes. Each themes file contains the "stylesheet" option, and one or more options for setting the colors of the overview, region and details sections. Three different themes are currently available:
- solid_gray_colors
- A pleasantly professional "button-down" look.
- transparent_colors
- A funky theme which makes extensive use of transparency.
- warm_colors
- An earth-themed color set.
You can switch between themes by finding this GBrowse.conf line:
#include "themes/transparent_colors"
and changing it to one of the other theme files. Each theme file is associated with a stylesheet located in /var/www/gbrowse2/css. You are encouraged to customize these stylesheets or add new ones.
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 following shows a basic data source configuration file:
[GENERAL]
description = Yeast chromosomes 1+2 (basic)
database = scaffolds
initial landmark = chrI:143000..180000
default tracks = Genes
ORFs
tRNAs
CDS
Transp
Centro:overview
GC:region
# examples to show in the introduction
examples = chrI
chrII
chrI:80,000..120,000
"membrane trafficking"
NUT21
YAL063C
#################################
# database definitions
#################################
[scaffolds:database]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor memory
-dir $DATABASES/yeast_scaffolds
[annotations:database]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor memory
-dir $DATABASES/yeast_chr1+2
# Default glyph settings
[TRACK DEFAULTS]
glyph = generic
database = annotations
height = 8
bgcolor = cyan
fgcolor = black
label density = 25
bump density = 100
### TRACK CONFIGURATION ####
# the remainder of the sections configure individual tracks
[Centro:overview]
feature = centromere
bgcolor = blue
glyph = dot
fgcolor = black
height = 8
point = 1
key = Centromeres
[tRNA:overview]
feature = tRNA
glyph = generic
bgcolor = lightgray
fgcolor = black
height = 4
stranded = 1
description = 1
key = tRNAs
[GC:region]
glyph = dna
global feature = 1
database = scaffolds
height = 40
gc_window = auto
do_gc = 1
strand = both
fgcolor = red
axis_color = blue
key = GC Content
[Genes]
feature = gene
glyph = so_transcript
bgcolor = yellow
height = 6
description = 0
key = Named gene
[CDS]
feature = CDS
glyph = cds
description = 0
height = 26
sixframe = 1
label = sub {shift->name . " reading frame"}
key = CDS
citation = This track shows CDS reading frames.
[tRNAs]
feature = tRNA
glyph = generic
bgcolor = lightgray
fgcolor = black
height = 4
stranded = 1
description = 1
key = tRNAs
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
- initial landmark
- If an initial landmark option is present, then its value will be used to populate the navigation box when the user initially visits GBrowse. For example, to start with a view of chromosome 1 from base pairs 50,000 to 150,000:
initial landmark = chr1:50000..150000
- 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 [dbname:database], where dbname is any symbolic name you choose. The body of the stanza has db_adaptor and db_args options, where db_adaptor is the name of a Perl database adaptor module for accessing the sequence annotation database and db_args are a series of arguments to pass to the module's new() method in order to open and initialize the database. The symbolic names are used in track configuration stanzas to attach databases to particular tracks.
There are a variety of database backends that work with GBrowse 2; the major ones are Bio::DB::SeqFeature::Store, a database designed for rapid access to GFF3-format annotation data, Bio::DB::Das::Chado, an interface to the powerful Chado database, Bio::Das, an interface to the Distributed Annotation System, Bio::DB::Das::BioSQL, an interface to the BioSQL system, and lastly Bio::DB::GFF, a quick and dirty interface to GFF2-formatted annotation data. See GBrowse Backends for more information about these adaptors.
A typical Bio::DB::SeqFeature::Store database configured to run directly from flat files is configured like this:
[scaffolds:database]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor memory
-dir /home/fred/gbrowse/databases/yeast_scaffolds
The symbolic name for this database is scaffolds. It uses the Bio::DB::SeqFeature::Store module as its backend, and when initialized is created by calling:
Bio::DB::SeqFeature::Store->new(-adaptor=> 'memory',
-dir => '/home/fred/gbrowse/databases/yeast_scaffolds').
Referring to the Bio::DB::SeqFeature::Store documentation (by using perldoc Bio::DB::SeqFeature::Store) we find that this is the invocation to create an in-memory database from the annotation file(s) located in /home/fred/gbrowse/databases/yeast_scaffolds.
A database option that is named in the [GENERAL] section is the default database, used for any tracks that do not explicitly specify a database option of their own. For example:
[GENERAL] database = scaffolds
If the browser uses a single database only, you can implify the configuration file slightly by incorporating the appropriate db_adaptor and db_args options directly in the [GENERAL] section in lieue of a database option and corresponding [...:database] stanza. This creates an anonymous backend that does not need to be specifically named in a database stanza. For example:
[GENERAL]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor memory
-dir /home/fred/gbrowse/databases/yeast_scaffolds
Note: Plugins are temporarily limited to run on the default database indicated by the database option in the [GENERAL] section. This means that the default database must contain the DNA sequence in order for DNA analysis plugins, such as the restriction site annotator, to work properly.
Database Search Options
Ordinarily when the user types a search term into the landmarks text field, GBrowse will search through all configured databases for matches. You can control this behavior to restrict the behavior of the search or to disable searching entirely. This behavior is controlled through the search options option:
[scaffolds:database]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor memory
-dir /home/fred/gbrowse/databases/yeast_scaffolds
search options = exactname, -fulltext, +autocomplete
[expression:database]
db_adaptor = Bio::DB::SeqFeature::Store
db_args = -adaptor DBI::mysql
-dsn yeast_expression_data
search options = none
The value of this option is a comma-delimited list of choices. Choices are processed from left to right. The option "none" turns off all search options, "all" turns them all on, and a list of search types activates exactly those types. A +optionname will turn that option on, and a -optionname will turn it off.
Turn all searches on, except for the full text search:
search options = all -fulltext
Add autocomplete to the default searches:
search options = default +autocomplete
Only do exact searching:
search options = exact
The search types are:
- all
- Enable all search types.
- none
- Disable all searching on this database. Equivalent to a keyword list of ""
- default
- Equivalent to "exact, wildcard, stem, fulltext, heuristic".
- exact
- Allow exact matches on feature names and aliases. Wildcard characters will be ignored.
- wildcard
- Allow wildcards to be used in search terms. Only feature names and aliases will be searched.
- stem
- If an exact match does not work, and the user did not already include a wildcard, then add a wildcard to the end of the search term and try again.
- fulltext
- If more restricted searches are not successful, search through the notes, attributes and descriptions of the features for potential matches. This search may be time consuming!
- heuristics
- If this option is set, and none of the previous searches were successful, GBrowse will attempt to add or remove the prefixes "Chr", "chr" and "CHROMOSOME_" from the search term in an attempt to help a user who is using "X" to search for "ChrX" or vice-versa.
- autocomplete
- Allow the features in this database to be used for landmark autocompletion, provided that autocomplete is set to a true value in the general configuration section.
Track Definitions
After the database stanzas come a series of one or more track definition stanzas. Track definition stanzas are used to configure annotation tracks that appear in the browser details panel (the main panel) as well as those that appear in the overview and region panels. Track definition stanzas are also used to configure semantic zooming (in which the appearance of the track changes at different magnification levels) and tracks generated by plugins.
A typical track definition looks like this:
[Genes] database = annotations feature = gene glyph = generic bgcolor = yellow height = 6 link = http://www.google.com/search?q=$name key = Named genes
This track is named "Genes"; this name will be used if the user bookmarks or shares the track. Its features reside in a backend database named "annotations" (which would have been previously defined in a track definition stanza named "[annotations:database]"). The features retrieved from the database are of type "gene". The "generic" glyph is used to display the feature, and it is drawn with a background color of yellow and a height of 6 pixels. The human-readable key printed at the top of the track is "Named genes". Finally, when the user clicks on a feature in this track, his web browser will link to a Google search link created using the gene's name.
Track names can contain almost any character, including whitespace, but cannot contain the "-" or "+" signs because these are used to separate track names in the URL when bookmarking. ([My Genes] is OK, but [My-Genes] is not). As in the general configuration section, the track declaration contains multiple name=value option pairs. You can create a special track configuration section named [TRACK DEFAULTS] to define default fallback options used for all tracks. For example, if you want all tracks to show features of height 10 using the generic glyph, then you can create a [TRACK DEFAULTS] section like follows:
[TRACK DEFAULTS] glyph = generic height = 10
Individual tracks can override these defaults simply by changing the "glyph" and "height" options.
Database and Rendering Options
Several track options affect the connection between the gbrowser and the underlying database backend(s):
- database
- This option relates the track to a database that was previously defined with a database definition stanza. If this option is not present, then the default database indicated in the [GENERAL] section will be used.
- feature
- This relates the track to one or more feature types as they appear in the database. Recall that each feature has a method and source. This is represented in the form primary_tag:source_tag, where primary_tag describes the feature's type (e.g. "mRNA") and source_tag describes where the provenance of the feature. (In GFF files, these are called "method" and "source" respectively). For example, a feature of type "gene:sgd" has the primary_tag "gene" and the source_tag "sgd". It is possible to omit the source. A feature of type "gene" will include all features whose primary_tags are "gene", regardless of the source_tag field. It is not possible to omit the method.
- It is possible to have several feature types displayed on a single track. Simply provide the feature option with a space-delimited list of the features you want to include. For example:
feature = gene:sgd stRNA:sgd
- This will include features of type "gene:sgd" and "stRNA:sgd" in the same track and display them in a similar fashion.
- global feature
- If this option is present and set to a true value (e.g. "1"), GBrowse will automatically generate a pseudo-feature that starts at the beginning of the currently displayed region and extends to the end. This is often used in conjunction with the "translation" and "dna" glyphs in order to display global characteristics of the sequence. If this option is set, then you do not need to specify a "feature" option.
- remote feature
- This relates the track to a remote feature track somewhere on the Internet. The value is a http: or ftp: URL, and may correspond to a static file of features in GFF format, gbrowse upload format, a CGI script, or a DAS source. When this option is active, the "feature" option and most of the glyph control options described below are ignored, but the "citation" and "key" options are honored.
- Example:
- remote feature = http://www.wormbase.org/cgi-bin/das/wormbase?type=mRNA
- remote renderer
- This option, if present, indicates that this track is to be rendered by one or more remote rendering daemons. See Running a GBrowse2 Render Farm for information on using this option.
- das category, das landmark, das flatten, das subparts, das superparts, das glyph, das type
- All these options pertain to exporting the GBrowse database as a DAS data source. Please see the GBrowse DAS HOWTO for more information.
Glyph and Rendering Options
These options control the rendering of features onto the track, including their size, shape and color.This section descrbes the most commonly used options. Please see Glyphs and Glyph Options for a full description of GBrowse's many and diverse rendering options.
- bgcolor
- This controls the background color of the glyph. The format of colors is explained in Glyphs and Glyph Options.
- fgcolor
- This controls the foreground color (outline color) of the glyph. The format of colors is explained in Glyphs and Glyph Options.
- description
- This is a true or false value, where true is 1 and false is 0. If the option is set to true, then the description of the feature (any Note fields) is printed below the feature, space allowing.
- fontcolor
- This controls the color of the primary font of text drawn in the glyph. This is the font used for the features labels drawn at the top of the glyph.
- font2color
- This controls the color of the secondary font of text drawn in the glyph. This is the font used for the longish feature descriptions drawn at the bottom of the glyphs.
- glyph
- This controls the glyph (graphical icon) that is used to represent the feature. There are many glyphs ranging from simple to complex. The complete list of glyphs and glyph-specific options are listed GBrowse Glyphs and Glyph Options. The "generic" glyph is the default.
- height
- This option sets the height of the glyph. It is expressed in pixels.
- label
- This is a true or false value, where true is 1 and false is 0. If the option is set to true, then the name of the feature (i.e. its group name) is printed above the feature, space allowing.
- strand_arrow
- This is a true or false value, where true is 1 and false is 0. If this option is set to true, then the glyph will indicate the strandedness of the feature, usually by drawing an arrow of some sort. Some glyphs are inherently stranded, or inherently non-stranded and simply ignore this option.
In addition, there are many glyph-specific options. Please see Glyphs and Glyph Options for details.
Track Table Options
These options control the human-readable track label, as well as the way that tracks are grouped in the GBrowse tracks table.
- citation
- If present, this option creates a human-readable descriptive paragraph describing the feature and how it was derived. This is the text information that is displayed when the user clicks on the track name in the checkbox group. The value can either be a URL, in which case clicking on the track name invokes the corresponding URL, or a text paragraph, in which case clicking on the track name generates a page containing the text description. Long paragraphs can be continued across multiple lines, provided that continuation lines begin with whitespace.
- key
- This option controls the descriptive key that is drawn in the key area at the bottom of the image. It also appears in the checkboxes that the end user uses to switch tracks on and off. If not specified, it defaults to the track name.
- restrict
- This option allows you to restrict who is allowed to view the current track by host name, IP address or username/password. See GBrowse Authentication and Authorization for details.
- category
- This option allows you to group tracks into different groups on the GBrowse display in addition to the default group called 'General'. For example, if you wanted several tracks to be in a separate group called "Genes", you would add this to each of the track definitions:
category = Genes
- You can also create nested categories by separating category names by colons:
[label1] category = Genes:Coding ... [label2] category = Genes:Non-coding
- This will create a section in the tracks panel called "Genes", which will have two subsections called "Coding" and "Non-coding". The track named "label1" will be placed in the first section, while the track named "label2" will be placed in the second.
- If all tracks are categorized, then the "General" category will not be displayed. If you have used a "category tables" option in the [GENERAL] section of the configuration file, then the names of the tracks labeled with this category will be placed into a table of the appropriate dimensions. Tracks will be placed into the table in column-major format: you should first list stanzas for all rows of column 1, then all rows of column 2, etc.
- See the GBrowse 2.0 Tutorial for more details.
- select
- This option gives you the ability to create a form of subtrack which the user can turn on and off. It is most suitable for tracks that have a few large features in them, such as genome-wide wiggle tracks. The form of the option is as follows:
select = method value1 value2 value3'...
method is one of name, display_name, type, source or score. This is followed by a list of selections that will be presented to the user to select among when he clicks on the "menu" icon in the track's title bar. For example, if you have a track in which the features have one of the sources "day 1" , "day 2", and "day 3", you can allow the user to select which of the features are visible with this option:
select = source 'day 1' 'day 2' 'day 3'
The matches are case insensitive regular expressions, so "day 1" will match "Day 1" and "DAY 1a".
Linking Options
These options control what happens when the user clicks on a feature or mouses over it. It is usually convenient to place link options in the [TRACK DEFAULTS] section to generate default linking behavior, and then to override these options as needed on a case-by-case basis inside specific track stanzas.
- balloon click, balloon hover
These options control popup balloons that appear when the user clicks or hovers above a feature. See GBrowse Balloon Tips for information on how to generate static and dynamic content in these balloons.
- box_subparts
- Ordinarily, GBrowse will generate a single link for the entire feature, even if it contains multiple subparts. However, if this option is greater than zero, then gbrowse will generate imagemap rectangles for each of the subparts of a feature (e.g. the exons within a transcript), allowing you to link each subpart separately. The numeric value will control the number of levels of subfeatures that the boxes will descend into. For example, if using the "gene" glyph, set -box_subparts to 2 to create boxes for the whole gene (level 0), the mRNAs (level 1) and the exons (level 2).
- link
- The link option creates outgoing links from the GBrowse display. When the user clicks on a feature of interest, he will be taken to the corresponding URL.
- The link 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 annotation. Recognized variables include:
$name The feature's name (group name)
$id The feature's id (eg, PK from a database)
$class The feature's class (group class)
$method The feature's method
$source The feature's source
$ref The name of the sequence segment (chromosome, contig)
on which this feature is located
$description The feature's description (notes)
$start The start position of this feature, relative to $ref
$end The end position of this feature, relative to $ref
$segstart The left end of $ref displayed in the detailed view
$segend The right end of $ref displayed in the detailed view
- For example, the wormbase.conf file uses this link rule:
link = http://www.wormbase.org/db/get?name=$name;class=$class
- At run time, if the user clicks on an EST named yk1234.5, this will generate the URL
http://www.wormbase.org/db/get?name=yk1234.5;class=EST
- A special link named AUTO will cause the feature to link to the GBrowse Details Script, which summarizes information about the feature. The default is not to link at all.
- link_target
- By default links will replace the contents of the current window. If you wish, you can specify a new window to pop up when the user clicks on a feature, or designate a named window or frame to receive the contents of the link. To do this, add the "link_target" option to the [TRACK DEFAULTS] section or to a track stanza. The format is this:
link_target = _blank
- The value uses the HTML targetting rules to name/create the window to receive the value of the link. The first time the link is accessed, a window with the specified name is created. The next time the user clicks on a link with the same target, that window will receive the content of the link if it is still present, or it will be created again if it has been closed. A target named "_blank" is special and will always create a new window.
- The "link_target" option can also be computed dynamically. See Computed Options for details.
- title
- The title option controls the "tooltips" text that pops up when the mouse hovers over a glyph in certain browsers. The rules for generating titles are the same as the "link" option discussed above.The "title" option can also be computed dynamically. See for details.
- Note HTML characters such as "<", ">" and "&" are not automatically escaped from the title. This lets you do neat stuff, such as create popup menus, but also means that you need to be careful. In particular, you must not use the quote character (") in the title, but either use the " entity, or the single quote ('). The function CGI::escapeHTML() is available to properly escape HTML characters in dynamically-generated titles.
- The special title value "AUTO" causes a default description to appear describing the name, type and position of the feature. This is also assumed if the title option is missing or blank.
Grouping Options
A small number of options allow you to group related features together. This facility is described in more detail in Grouping GBrowse Features.
- group_pattern
- This option lets you connect related features by dotted lines based on a pattern match in the features' names. A typical example is connecting the 5' and 3' read pairs from ESTs or plasmids.
- group_on
- For Bio::DB::SeqFeature::Store databases only, the group_on field allows you to group features together by display_name, target or any other method. This is mostly useful for XY-plot data, where you may want to dynamically group related data points together so that they share the same vertical scaling.
- Example:
group_on = display_name
Adding Tracks to the Overview and Region Panels
You can make any set of tracks appear in the overview by creating a stanza with a title of the format [<label>:overview], where <label> is any unique label of your choice. The format of the stanza is identical to the others, but the indicated track will appear in the overview rather than as an option in the detailed view. For example, this stanza adds to the overview a set of features of method "gene", source "framework":
[framework:overview] feature = gene:framework label = 1 glyph = generic bgcolor = lavender height = 5 key = Mapped Genes
Similarly, you can make a track appear in the region panel by appending ":region" to its name:
[genedensity:region] feature = gene_density glyph = xyplot graph_type = boxes scale = right bgcolor = red fgcolor = red height = 20 key = SNP Density
Semantic Zooming
Sometimes you will want to change the appearance of a track when the user has zoomed out or zoomed in beyond a certain level. To indicate this, create a set of "length qualified" stanzas of format [<label>:<zoom level>], where all stanzas share the same <label>, and <zoom level> indicates the minimum size of the region that the stanza will apply to. For example:
[gene] feature = transcript:curated glyph = dna fgcolor = blue key = genes citation = example semantic zoom track [gene:500] feature = transcript:curated glyph = gene [gene:100000] feature = transcript:curated glyph = arrow [gene:500000] feature = transcript:curated glyph = generic
This series of stanzas says to use the "gene" glyph when the segment being displayed is 500 bp or longer, to use the "arrow" glyph when the segment being displayed is 100,000 bp or longer, and the "generic" glyph when the region being displayed is 500,000 bp or longer. For all other segment lengths (1 to 499 bp), the ordinary [gene] stanza will be consulted, and the "dna" glyph will be displayed. The bare [gene] stanza is used to set all but the "feature" options for the other stanzas. This means that the fgcolor, key and citation options are shared amongst all the [gene:XXXX] stanzas, but the "feature" option must be repeated.
You can override any options in the length qualified stanzas. For example, if you want to change the color to red in when displaying genes on segments between 500 and 99,999 bp, you can modify the [gene:500] stanza as follows:
[gene:500] feature = transcript:curated glyph = transcript2 fgcolor = red
It is also possible to display different features at different zoom levels, although you should handle this potentially confusing feature with care.
If you wish to turn off a track entirely, you can use the "hide" flag to hide the track when the display exceeds a certain size:
[6_frame_translation:50000] hide = 1
Advanced Topics
These are advanced configuration topics.
Computed Options
Many configuration file options can be computed at run time by using Perl subroutines as their values. These are known as "callbacks." Currently callbacks work with all options that can be placed in a [TRACK] section except for the "database" and "remote renderer" options. In addition, the "header", "footer" and "html1" through "html6" options in the GBrowse.conf and datasource [GENERAL] sections accept callbacks.
You need to know the Perl programming language to take advantage of this feature. The general format of this type of option is:
option name = sub {
some perl code;
some more perl code;
even more perl code;
}
The value must begin with the sequence "sub {" in order to be recognized as a subroutine declaration. After this, you can have one or more lines of Perl code followed by a closing brace. Continuation lines must begin with whitespace.
When the browser first encounters an option like this one, it will attempt to compile it into Perl runtime code. If successful, the compiled code will be stored for later use and invoked whenever the value of the option is needed. (Otherwise, an error message will appear in your server error log).
For options of type "footer", "header", and "html1" through "html6", the subroutine is passed no arguments. It is expected to produce some HTML and return it as a string value.
For glyph-specific features, such as "bgcolor" the subroutine will be called at run time with five arguments consisting of the feature, the name of the option, the current part number of the feature, the total number of parts in this feature, and the glyph corresponding to the feature. Usually you will just look at the first argument. The return value is treated as the value of the corresponding option. For example, this bgcolor subroutine will call the feature's primary_tag() method, and return "blue" if it is an exon, "orange" otherwise:
bgcolor = sub {
my $feature = shift;
return "blue" if $feature->primary_tag eq 'exon';
return "orange";
}
See the manual page for Feature and Lite for information on how to interrogate the feature object.
For special effects, such as coloring the first and last exons differently, you may need access to all five arguments. Here is an example that draws the first and last parts of a feature in blue and the rest in red:
sub {
my($feature,$option_name,$part_no,$total_parts,$glyph) = @_;
return 'blue' if $part_no == 0; # zero-based indexing!
return 'blue' if $part_no == $total_parts-1; # zero-based indexing!
return 'red';
}
If you need access to information in the parent of the feature (e.g. in a multipart feature), you can call the glyph's parent_feature() method:
sub {
my($feature,$option_name,$part_no,$total_parts,$glyph) = @_;
my $parent = $glyph->parent_feature;
return 'blue' if $parent->name =~ /Blue\d+/;
return 'red';
}
The parent_feature() method was added to Bioperl on 17 April 2008. If you are using an earlier version, parent_feature() will not be available.
See the Bio::Graphics::Panel manual page for more details.
Callbacks for the "link", "title", and "link_target" options have a slightly different call signature. They receive three arguments consisting of the feature, the Bio::Graphics::Panel object, and the Bio::Graphics::Glyph object corresponding to the current track within the panel:
link = sub {
my ($feature, $panel, $track) = @_;
... do something
}
Ordinarily you will only need to use the feature object. The other arguments are useful to look up panel-specific settings such as the pixel width of the panel or the state of the "flip" setting:
title = sub {
my ($feature,$panel,$track) = @_;
my $name = $feature->display_name;
return $panel->flip ? "$name (flipped)" : $name;
}
Named Subroutine References
If you use a version of BioPerl after April 15, 2003, you can also use references to named subroutines as option arguments. To use named subroutines, add an init_code section to the [GENERAL] section of the configuration file. init_code should contain nothing but subroutine definitions and other initialization routines. For example:
init_code = sub score_color {
my $feature = shift;
if ($feature->score > 50) {
return 'red';
} else {
return 'green';
}
}
sub score_height {
my $feature = shift;
if ($feature->score > 50) {
return 10;
} else {
return 5;
}
}
Then simply refer to these subroutines using the \&name syntax:
[EST_ALIGNMENTS] glyph = generic bgcolor = \&score_color height = \&score_height
You can declare global variables in the init_code subroutine if you use "no strict 'vars';" at the top of the section:
init_code = no strict 'vars';
$HEIGHT = 10;
sub score_height {
my $feature = shift;
$HEIGHT++;
if ($feature->score > 50) {
return $HEIGHT*2;
} else {
return $HEIGHT;
}
}
Due to the way the configuration file is parsed, there must be no empty lines in the init_code section. Either use comments to introduce white space, or "use" a .pm file to do anything fancy.
Subroutines that you define in the init_code section, as well as anonymous subroutines, will go into a package that changes unpredictably each time you load the page. If you need a predictable package name, you can define it this way:
init_code = package My; sub score_height { .... }
[EST_ALIGNMENTS] height = \&My::score_height
Running GBrowse under FastCGI
[FastCGI] is a web protocol for generating dynamic that replaces the usual CGI mechanism. The first time a script is requested, FastCGI launches that script as a long-running process. Subsequent requests are forwarded to that process. Because startup time is eliminated, the responsiveness of a FastCGI script is much improved.
GBrowse is FastCGI ready. To take advantage of this facility, you will need a version of Apache equipped with FastCGI support, and a short Apache configuration stanza for GBrowse. If your Apache was compiled from source, you will need to download and install the [mod_fastcgi module] following its installation directions. If you have a binary distribution, please install the appropriate package: libapache2-mod-fastcgi for APT/Debian systems, or "mod_fcgid" for RPM systems. You will also need the Perl FCGI module (libfcgi-perl for APT/Debian, fcgi-perl for RPM).
The next step is to create a suitable Apache configuration stanza for GBrowse, if needed. When you configured and install GBrowse, it probably created a default configuration for you, and stored it into your Apache web server's configuration directory (depending on your system, /etc/apache/conf.d/gbrowse2.conf, /etc/apache2/conf.d/gbrowse2.conf, /etc/httpd/conf.d/gbrowse2.conf, or similar). If this file is already installed, then you are all done. Fetch URL http://localhost/fgb2/gbrowse and compare the performance to GBrowse running as a CGI script.
If you declined to have the configuration script create this file and configured GBrowse manually, then you can generate a suitable config file by running ./Build apache_conf from within the GBrowse distribution directory. The FastCGI portion of the configuration file that is generated will looks something like this:
<IfModule mod_fastcgi.c>
Alias /fgb2 "/usr/lib/cgi-bin/gb2"
<Location /fgb2>
SetHandler fastcgi-script
</Location>
FastCgiConfig -initial-env GBROWSE_CONF=/etc/gbrowse2
</IfModule>
Copy this stanza into your main Apache configuration file, or, better, into the site configuration file directory, /etc/apache/conf.d (or similar). Restart Apache to pick up the configuration file changes and fetch the URL http://localhost/fgb2/gbrowse. You should notice a marked improvement in load and update speed. The improvement will be particularly noticeable if you combine FastCGI with a rendering slave, as described in Running a GBrowse2 Render Farm.
If things don't seem to work as advertised, please check the Apache server error log file, usually /var/log/apache/error_log, for clues about where things are going wrong.
Running GBrowse under modperl
[ModPerl] is an Apache extension that embeds a Perl interpreter in the Apache process. Because Perl is always loaded and running, the startup time of CGI scripts is greatly reduced.
GBrowse is modperl ready. To take advantage of this facility, you will need a version of Apache equipped with modperl support, and a short Apache configuration stanza for GBrowse. If your Apache was compiled from source, you will need to download and install the [mod_perl module] following its installation directions. If you have a binary distribution, please install the appropriate package: libapache2-mod-perl2 for APT/Debian systems, or "mod_perl" for RPM systems. No additional distributions are needed, although you may wish to install the mod_perl documentation and development packages as these are distributed separately.
To configure GBrowse to use modperl, you need a short Apache configuration file stanza. By default, an appropriate configuration file was already installed for you when you installed GBrowse, located at /etc/apache/conf.d/gbrowse2.conf, /etc/apache2/conf.d/gbrowse2.conf, or /etc/httpd/conf.d/gbrowse2.conf depending on your system. If it is already installed, and Apache is modperl enabled, then you are all done. Fetch http://localhost/mgb2/gbrowse and compare GBrowse's performance to the CGI version.
Otherwise, you can generate an appropriate stanza by running ./Build apache_conf from the GBrowse distribution directory. The stanza will look something like this:
<IfModule mod_perl.c>
Alias /mgb2 "/usr/lib/cgi-bin/gb2"
<Location /mgb2>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
</Location>
</IfModule>
Copy and paste this into the main Apache configuration file, or (better) into the site configuration file directory, /etc/apache/conf.d (or similar). Restart Apache to pick up the configuration file changes. Now fetch URL http://localhost/fgb2/gbrowse. You should notice a marked improvement in load and update speed. The improvement will be particularly noticeable if you combine modperl with a rendering slave, as described in Running a GBrowse2 Render Farm.
As always, if things don't seem to work as intended, useful information can be found in the Apache server error log file, usually /var/log/apache/error_log.
Controlling the gbrowse_details page
If a track definition's "link" option 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.
In theory, 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. Please update this page if you are successful on another platform.
Authentication & Authorization
You can restrict who has access to gbrowse by IP address, host name, domain or username and password. Restriction can apply to the datasource as a whole, or to particular annotation tracks.
To limit access to a whole datasource, you can use Apache's standard authentication and authorization. GBrowse uses a URL of this form to select which datasource it is set to:
http://your.host/cgi-bin/gb2/gbrowse/your_datasource
where "your_datasource" is the name of the currently selected database. For example, the yeast source is http://your.host/cgi-bin/gb2/gbrowse/yeast.
To control access to the entire database, create a <Location> section in httpd.conf. The <Location> section should look like this:
<Location /cgi-bin/gb2/gbrowse/your_database>
Order deny,allow
deny from all
allow from localhost .cshl.edu .ebi.ac.uk
</Location>
This denies access to everybody except for "localhost" and browsers from the domains .cshl.edu and .ebi.ac.uk. You can also limit by IP address, by username and password or by combinations of these techniques. See http://httpd.apache.org/docs/howto/auth.html for the full details.
You can also limit individual tracks to certain individuals or organizations. Unless the stated requirements are met, the track will not appear on the main screen or any of the configuration screens. To set this up, add a "restrict" option to the track you wish to make off-limits:
[PROPRIETARY]
feature = etc
glyph = etc
restrict = Order deny,allow
deny from all
allow from localhost .cshl.edu .ebi.ac.uk
The value of the restrict option is identical to the Apache authorization directives and can include any of the directives "Order," "Satisfy," "deny from," "allow from," "require valid-user" or "require user." The only difference is that the "require group" directive is not supported, since the location of Apache's group file is not passed to CGI scripts. Note that username/password authentication must be turned on in httpd.conf and the user must have successfully authenticated himself in order for the username to be available.
As with other gbrowse options, restrict can be a code subroutine. The subroutine will be called with three arguments consisting of the host, ip address and authenticated user. It should return a true value to allow access to the track, or a false value to forbid it. This can be used to implement group-based authorization or more complex schemes.
Here is an example that uses the Text::GenderFromName to allow access if the user's name sounds female and forbids access if the name sounds male. (It might be useful for an X-chromosome annotation site.)
restrict = sub {
my ($host,$ip,$user) = @_;
return unless defined $user;
use Text::GenderFromName qw(gender);
return gender($user) eq 'f';
}
You should be aware that the username will only be defined if username authentication is turned on and the user has successfully authenticated himself against Apache's user database using the correct password. In addition, the hostname will only be defined if HostnameLookups have been turned on in httpd.conf. In the latter case, you can convert the IP address into a hostname using this piece of code:
use Socket; $host = gethostbyaddr(inet_aton($addr),AF_INET);
Note that this may slow down the response time of gbrowse noticeably if you have a slow DNS name server.
Another thing to be aware of when restricting access to an entire datasource is that that even though the datasource itself will not be accessible to unauthorized users, the name of the datasource will still be available from the popup "Data Source" menu. If you wish the name to be suppressed from view, add the option hide=1 to the datasource configuration stanza of the GBrowse.conf file:
[example_datasource] description = Draft annotation of v. volvulus path = v_volvulus_draft.conf hide = 1
The restrict option can also be used in a [datasource] section of GBrowse.conf to conditionally enable display of the source to certain IP addresses or users. For example, to display the V. volvulus source only to users in the .ebi.ac.uk domain or to an authenticated user named "Admin":
[example_datasource]
description = Draft annotation of v. volvulus
path = v_volvulus_draft.conf
restrict = Satisfy any
Order deny,allow
deny from all
allow from .ebi.ac.uk
require user Admin
To completely disable generation of the data sources popup menu, set show sources=0 in the [GENERAL] section of GBrowse.conf.
| Bio | Graphics color value + and Graphics color values + |
| Graphics | Feature + |
| Bio|Graphics color value|Bio | Graphics color values + |
| Http://search.cpan.org/~cjfields/BioPerl-1.5.9 4/Bio/SeqFeature/Lite.pm Bio | Lite + |
| Http://search.cpan.org/~lds/Bio-Graphics-1.83/lib/Bio/Graphics/Feature.pm Bio | Feature + |
| SeqFeature | Lite + |
